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 端點正常工作。