Tempo Filler MCP Server

🚀 Tempo Filler MCP 服务器

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

🚀 快速开始

1. 获取代码：

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

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

2. 构建服务器：

npm install && npm run build

3. 配置你的 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"
            }
        }
    }
}

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

✨ 主要特性

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

📦 安装指南

前提条件

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

分步设置

1. 获取源代码：

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

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

2. 安装依赖项：

npm install

3. 构建服务器：

npm run build

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

📚 详细文档

配置

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

必需的环境变量

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

可选的环境变量

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

创建个人访问令牌（PAT）

1. 登录到你的 JIRA 实例。
2. 转到 Profile → Personal Access Tokens。
3. 点击 Create token。
4. 给它一个名称（例如，“Tempo MCP Server”）。
5. 设置适当的权限（对问题和工作日志的读写访问权限）。
6. 复制令牌值，用于 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"
            }
        }
    }
}

设置步骤

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

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

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

身份验证设置

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

1. 在你的 JIRA 实例中生成一个 PAT：
   • 转到 Profile → Personal Access Tokens。
   • 创建具有问题和工作日志 读写权限 的令牌。
   • 复制令牌值（你将无法再次看到它）。
2. 设置环境变量：
   • 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 端点正常工作。