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 創建的 模型上下文協議 規範。