Tempo MCP 服务器

这是一个用于管理 Jira 中的 Tempo 工时记录的 MCP 服务器。该服务器通过 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          # 项目元数据和脚本配置

工具说明

以下是 MCP 服务器支持的工具及其详细信息：

获取工时记录 (/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 创建的 模型上下文协议 规范。