tempo-mcp-server

🚀 Tempo MCP 服务器

Tempo MCP 服务器用于管理 Jira 中的 Tempo 工时记录。它借助 Tempo 的 API 提供跟踪时间和管理工作日志的工具，可通过 Claude、Cursor 及其他兼容 MCP 协议的客户端访问。

✨ 主要特性

• 获取工时记录：获取特定日期范围内的所有工时记录。
• 创建工时记录：在 Jira 问题上记录时间。
• 批量创建：单次操作中创建多个工时记录。
• 编辑工时记录：修改已记录的时间、日期和描述。
• 删除工时记录：删除现有的工时记录。

📦 安装指南

系统要求

• Node.js 18+（推荐使用 LTS 版本）
• Jira Cloud 实例
• Tempo API 令牌
• Jira API 令牌

💻 使用示例

有以下两种主要方式使用此 MCP 服务器：

1. NPX（推荐给大多数用户）：直接运行而无需安装。
2. 本地克隆：克隆仓库用于开发或自定义。

选项 1: NPX 使用方法

通过 npx 最简单的使用方式是直接运行而不进行安装。

连接到 Claude 桌面端（NPX 方法）

1. 打开您的 MCP 客户端配置文件：
   • macOS 系统：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows 系统：%APPDATA%\Claude\claude_desktop_config.json
2. 添加以下配置：

{
  "mcpServers": {
    "Jira_Tempo": {
      "command": "npx",
      "args": [
        "@ivelin-web/tempo-mcp-server"
      ],
      "env": {
        "TEMPO_API_KEY": "your_tempo_api_key_here",
        "JIRA_SITE": "your_jira_site_url_here"
      }
    }
  }
}

3. 保存文件后，您的 MCP 服务器即可通过 Claude 等客户端使用。

选项 2: 本地克隆

如果您希望进行开发或自定义服务器，请执行以下步骤：

1. 克隆此仓库到本地：

git clone https://github.com/yourusername/tempo-mcp-server.git

2. 进入项目目录并安装依赖项：

cd tempo-mcp-server
npm install

3. 启动服务器进行开发：

npm run dev

📚 详细文档

项目结构

tempo-mcp-server/
├── src/                  # 源代码目录
│   ├── config.ts         # 配置管理文件
│   ├── index.ts          # MCP 服务器实现文件
│   ├── jira.ts           # Jira API 集成文件
│   ├── tools.ts          # 工具实现文件
│   ├── types.ts          # TypeScript 类型和模式定义
│   └── utils.ts          # 辅助函数文件
├── build/                # 编译生成的 JavaScript 代码
├── tsconfig.json         # TypeScript 配置文件
└── package.json          # 项目元数据和脚本配置

工具说明

获取工时记录 (/list)

• 功能：列出所有已记录的工时记录。
• 请求参数：
  • worklogId：特定工时记录的 ID（可选）
• 返回值：包含工时记录详细信息的 JSON 数组。

创建工时记录 (/create)

• 功能：在 Jira 问题上创建新的工时记录。
• 请求参数：
  • issueKey：需要记录时间的问题键
  • timeSpentHours：正数，表示花费的时间（小时）
  • date：工时记录的日期，格式为 YYYY-MM-DD
  • description：描述内容（可选）

批量创建工时记录 (/bulk-create)

• 功能：单次操作中批量创建多个工时记录。
• 请求参数：
  • worklogEntries：包含以下属性的数组：
    • issueKey：需要记录时间的问题键
    • timeSpentHours：正数，表示花费的时间（小时）
    • date：工时记录的日期，格式为 YYYY-MM-DD
    • description：描述内容（可选）

编辑工时记录 (/edit)

• 功能：修改现有的工时记录。
• 请求参数：
  • worklogId：要修改的工时记录 ID
  • timeSpentHours：正数，表示新的时间记录（小时）
  • description：新的描述内容（可选）
  • date：新的日期，格式为 YYYY-MM-DD（可选）

删除工时记录 (/delete)

• 功能：删除指定的工时记录。
• 请求参数：
  • worklogId：要删除的工时记录 ID

错误处理和调试

如果在使用过程中遇到问题，请按照以下步骤进行排查：

1. 确保所有环境变量都已正确设置：

echo $TEMPO_API_KEY && echo $JIRA_SITE

2. 验证您的 Tempo 和 Jira API 令牌是否具有正确的权限。通常，您需要具备以下权限：
   • 对问题的读取和写入权限
   • 对工时记录的管理权限
3. 检查控制台输出中的错误信息，这将帮助您定位具体的问题。
4. 如果问题仍然存在，可以尝试使用调试模式运行服务器：

npm run inspect

📄 许可证

MIT

信用

此服务器实现了由 Anthropic 创建的 模型上下文协议 规范。