金大哥 - tempo-filler-mcp-server MCP 详情

article

README

🚀 Tempo Filler MCP 服务器

Tempo Filler MCP 服务器是一个用于在 JIRA 中管理 Tempo 工作日志的模型上下文协议（MCP）服务器。该服务器使 AI 助手能够与 Tempo 的时间跟踪系统进行交互，支持工作日志的检索、创建、批量操作和管理。

🚀 快速开始

获取代码：

# 克隆仓库
git clone https://github.com/TRANZACT/tempo-filler-mcp-server.git
cd tempo-filler-mcp-server

# 或者从 GitHub 下载并解压 ZIP 文件

构建服务器：

npm install && npm run build

配置你的 AI 助手：

{
    "servers": {
        "tempo-filler": {
            "type": "stdio",
            "command": "node", 
            "args": ["/full/path/to/tempo-filler-mcp-server/dist/index.js"],
            "env": {
                "TEMPO_BASE_URL": "https://jira.company.com",
                "TEMPO_PAT": "your-personal-access-token"
            }
        }
    }
}

测试：向你的 AI 助手询问 “Get my worklogs for this week”

✨ 主要特性

获取工作日志：可根据日期范围和问题过滤条件，为用户检索工作日志。
创建工作日志：自动解析问题，添加单个工作日志条目。
批量操作：利用并发处理高效创建多个工作日志条目。
删除工作日志：移除现有的工作日志条目。
资源访问：浏览工作日志数据和近期问题。
提示模板：为工作日志数据生成分析提示。

📦 安装指南

前提条件

Node.js（版本 16 或更高）
npm（随 Node.js 安装）
安装了 Tempo Timesheets 插件的 JIRA 实例
JIRA 账户的 个人访问令牌

分步设置

获取源代码：

# 选项 1：使用 Git 克隆
git clone https://github.com/TRANZACT/tempo-filler-mcp-server.git
cd tempo-filler-mcp-server

# 选项 2：下载 ZIP 文件
# - 访问 GitHub 仓库页面
# - 点击 “Code” → “Download ZIP” 
# - 解压并进入该文件夹

安装依赖项：

npm install

构建服务器：

npm run build

获取你的 JIRA 凭证（请参阅下面的身份验证设置）

📚 详细文档

配置

服务器需要环境变量进行身份验证和配置：

必需的环境变量

TEMPO_BASE_URL：你的 JIRA 实例 URL（例如，https://jira.company.com）
TEMPO_PAT：用于身份验证的个人访问令牌

可选的环境变量

TEMPO_DEFAULT_HOURS：每个工作日的默认工作小时数（默认值：8）

创建个人访问令牌（PAT）

登录到你的 JIRA 实例。
转到 Profile → Personal Access Tokens。
点击 Create token。
给它一个名称（例如，“Tempo MCP Server”）。
设置适当的权限（对问题和工作日志的读写访问权限）。
复制令牌值，用于 TEMPO_PAT。

与 AI 助手一起使用

GitHub Copilot 配置（VS Code）

添加到你的 MCP 服务器配置文件（例如，mcp.json）：

{
    "servers": {
        "tempo-filler": {
            "type": "stdio", 
            "command": "node",
            "args": [
                "/full/path/to/tempo-filler-mcp-server/dist/index.js"
            ],
            "env": {
                "TEMPO_BASE_URL": "https://jira.company.com",
                "TEMPO_PAT": "your-personal-access-token-here"
            }
        }
    }
}

Claude Desktop 配置

添加到你的 Claude Desktop 配置文件：

{
    "mcpServers": {
        "tempo-filler": {
            "command": "node", 
            "args": ["/full/path/to/tempo-filler-mcp-server/dist/index.js"],
            "env": {
                "TEMPO_BASE_URL": "https://jira.company.com",
                "TEMPO_PAT": "your-personal-access-token"
            }
        }
    }
}

设置步骤

构建服务器：npm run build
查找 dist/index.js 文件的完整路径：

# 获取完整路径（在 macOS/Linux 上使用 pwd，在 Windows 上使用 cd）
pwd  # 应该显示类似 /Users/yourname/tempo-filler-mcp-server 的内容

将配置添加到你的 AI 助手（使用完整路径 + /dist/index.js）
重启你的 AI 助手以加载 MCP 服务器
测试连接：询问 “Get my worklogs for this week”

身份验证设置

服务器使用个人访问令牌（PAT）进行安全身份验证：

在你的 JIRA 实例中生成一个 PAT：
- 转到 Profile → Personal Access Tokens。
- 创建具有问题和工作日志 读写权限 的令牌。
- 复制令牌值（你将无法再次看到它）。
设置环境变量：
- TEMPO_BASE_URL：你的 JIRA URL（例如，https://jira.company.com）
- TEMPO_PAT：你的个人访问令牌

可用工具

1. `get_worklogs` - 检索时间日志

检索指定日期范围内的工作日志，支持可选过滤。参数：

startDate（字符串）：开始日期，格式为 YYYY-MM-DD
endDate（字符串，可选）：结束日期，默认为开始日期
issueKey（字符串，可选）：按特定问题键过滤

示例用法：

"Get my July hours"
→ 返回结果：总计：184 小时（23 条记录）
          • PROJ-1234：184.0 小时（23 条记录）

"Show me my worklogs for PROJ-1234 in July"  
→ 将结果过滤到特定问题

2. `post_worklog` - 记录单个条目

为特定问题和日期创建新的工作日志条目。参数：

issueKey（字符串）：JIRA 问题键（例如，“PROJ-1234”）
hours（数字）：工作小时数（小数，范围 0.1 - 24）
startDate（字符串）：日期，格式为 YYYY-MM-DD
endDate（字符串，可选）：多日条目的结束日期
billable（布尔值，可选）：时间是否可计费（默认值：true）
description（字符串，可选）：工作描述

示例用法：

"Log 8 hours to PROJ-1234 for July 10th"
→ 返回结果：✅ 工作日志创建成功
          问题：PROJ-1234 - 示例项目任务
          小时数：8 小时
          日期：2025-07-10
          工作日志 ID：1211549

3. `bulk_post_worklogs` - 创建多个条目

利用并发处理高效创建多个工作日志条目。参数：

worklogs（数组）：工作日志对象数组：
- issueKey（字符串）：JIRA 问题键
- hours（数字）：工作小时数
- date（字符串）：日期，格式为 YYYY-MM-DD
- description（字符串，可选）：工作描述
billable（布尔值，可选）：所有条目时间是否可计费

示例用法：

"Post 8 hours a day every weekday from July 11 to 15 on PROJ-1234"
→ 返回结果：✅ 批量工作日志创建开始
          正在处理 3 个工作日志条目...
          ✅ 成功：3
          ❌ 失败：0
          📊 总小时数：24

"Fill all weekdays in July with 8 hours on PROJ-1234"
→ 为该月的所有工作日创建 23 个条目

4. `delete_worklog` - 移除条目

按 ID 删除现有的工作日志条目。参数：

worklogId（字符串）：要删除的 Tempo 工作日志 ID

示例用法：

"Delete worklog with ID 1211547"
→ 移除指定的工作日志条目

示例交互

查看你的时间日志

"Get my July hours"
→ 返回 7 月所有工作日志的摘要，按问题和日期汇总

"Show me my worklogs for July 2025"  
→ 使用 get_worklogs 检索详细的工作日志信息

"What did I work on last week?"
→ 获取上周的工作日志，并按问题细分

创建单个工作日志条目

"Log 8 hours to PROJ-1234 for July 10th"
→ 创建单个工作日志条目：
   ✅ 问题：PROJ-1234 - 示例项目任务
   ✅ 小时数：8 小时（可计费）
   ✅ 日期：2025-07-10
   ✅ 工作日志 ID：1211549

"Post 6.5 hours on PROJ-123 for today with description 'Bug fixes and testing'"
→ 使用 post_worklog 并添加自定义描述

批量工作日志创建

"Post 8 hours a day every weekday from July 11 to 15 on PROJ-1234"
→ 创建 5 个工作日志条目（跳过周末）：
   ✅ 7 月 11 日（星期五）：8 小时
   ✅ 7 月 14 日（星期一）：8 小时  
   ✅ 7 月 15 日（星期二）：8 小时
   总计：3 个工作日共 24 小时

"Fill my timesheet for this week - 4 hours PROJ-1111 and 4 hours PROJ-2222 each day"
→ 使用 bulk_post_worklogs 处理每天多个问题

"Finish filling up the days until July 31st"
→ 自动填充该月剩余的工作日

高级批量操作

"Log time for the entire month of July:
- PROJ-1234: 8 hours every weekday  
- Skip weekends
- All time should be billable"
→ 为 7 月的所有工作日创建 22 个工作日志条目

"Fill my Q2 timesheet with 8 hours daily split between:
- 60% on PROJ-1234 (development)
- 40% on PROJ-5678 (meetings)"
→ 计算小时数并为该季度创建条目

工作日志管理

"Delete worklog with ID 1211547"
→ 移除指定的工作日志条目

"Show me a summary of my July hours by issue"
→ 按问题分组工作日志，显示总计和百分比

实际使用示例

基于成功的实现，以下是一些实际场景：

每日时间记录

# 在 VS Code 中使用 GitHub Copilot：
用户："Log 8 hours on PROJ-1234 for today"
AI：✅ 工作日志创建成功
    问题：PROJ-1234 - 示例项目任务
    小时数：8 小时
    日期：2025-08-01
    工作日志 ID：1211550
    花费时间：1 天

每月时间填充

# 整月的批量操作：
用户："Fill all weekdays in July with 8 hours on PROJ-1234"
AI：✅ 批量工作日志创建开始
    正在处理 23 个工作日志条目...
    ✅ 成功：23
    ❌ 失败：0  
    📊 总小时数：184

时间跟踪分析

# 每月摘要：
用户："Get my July hours"
AI：📊 总小时数：184 小时（23 条记录）
    
    按问题细分：
    • PROJ-1234：184.0 小时（23 条记录）
    
    每日模式：每个工作日 8 小时
    完成情况：100%（所有工作日已填充）

开发

项目结构

src/
├── index.ts              # 主 MCP 服务器入口点
├── tempo-client.ts       # 带有 PAT 身份验证的 Tempo API 客户端
├── tools/                # 工具实现
│   ├── get-worklogs.ts
│   ├── post-worklog.ts
│   ├── bulk-post.ts
│   └── delete-worklog.ts
└── types/                # TypeScript 类型定义
    ├── tempo.ts
    ├── mcp.ts
    └── index.ts

构建命令

npm run build：将 TypeScript 编译为 JavaScript
npm run dev：构建并运行服务器
npm run typecheck：进行类型检查但不编译

测试

可以使用 MCP Inspector 或与兼容的 AI 助手集成来测试服务器。

安全性

使用个人访问令牌进行安全身份验证。
不记录或暴露任何凭证。
对所有参数进行输入验证。
采用速率限制和错误处理，防止 API 滥用。

API 兼容性

此服务器与以下版本兼容：

JIRA Core/Software 8.14+
Tempo Timesheets 4.x
模型上下文协议规范

故障排除

设置问题

找不到服务器 / 路径问题：

确保使用 dist/index.js 的 完整绝对路径。
在 Windows 上：C:\Users\YourName\tempo-filler-mcp-server\dist\index.js
在 macOS/Linux 上：/Users/YourName/tempo-filler-mcp-server/dist/index.js
验证文件是否存在：ls dist/index.js（应显示该文件）

构建失败：

检查 Node.js 版本：node --version（应为 16 或更高）
清除缓存并重试：npm cache clean --force && npm install && npm run build
检查构建输出中的错误消息

AI 助手未加载服务器：

添加配置后完全重启你的 AI 助手。
检查配置文件语法（有效的 JSON）。
验证环境变量是否正确设置。

身份验证问题

验证你的个人访问令牌是否有效且具有适当的权限。
检查你的 JIRA 实例 URL 是否正确。
确保 Tempo 已在你的 JIRA 实例中正确安装和配置。

连接问题

验证与你的 JIRA 实例的网络连接。
检查防火墙和代理设置。
确认你的环境可以访问 JIRA 实例。

权限问题

确保你的用户账户有权限为指定问题记录时间。
验证 Tempo 是否配置为允许你的用户记录时间。
检查 JIRA 中的项目权限。

📄 许可证

ISC 许可证 - 详情请参阅 package.json。

🤝 贡献

欢迎贡献代码！请遵循现有的代码风格，并确保所有工具与真实的 Tempo API 端点正常工作。

tempo-filler-mcp-server

README

🚀 Tempo Filler MCP 服务器

🚀 快速开始

✨ 主要特性

📦 安装指南

前提条件

分步设置

📚 详细文档

配置

必需的环境变量

可选的环境变量

创建个人访问令牌（PAT）

与 AI 助手一起使用

GitHub Copilot 配置（VS Code）

Claude Desktop 配置

设置步骤

身份验证设置

可用工具

1. get_worklogs - 检索时间日志

2. post_worklog - 记录单个条目

3. bulk_post_worklogs - 创建多个条目

4. delete_worklog - 移除条目

示例交互

查看你的时间日志

创建单个工作日志条目

批量工作日志创建

高级批量操作

工作日志管理

实际使用示例

每日时间记录

每月时间填充

时间跟踪分析

开发

项目结构

构建命令

测试

安全性

API 兼容性

故障排除

设置问题

身份验证问题

连接问题

权限问题

📄 许可证

🤝 贡献

运行方式说明

托管运行

本地运行 / 其它方式

1. `get_worklogs` - 检索时间日志

2. `post_worklog` - 记录单个条目

3. `bulk_post_worklogs` - 创建多个条目

4. `delete_worklog` - 移除条目