Allstacks MCP Server

🚀 Allstacks MCP 服務器

Allstacks MCP 服務器是一個全面的模型上下文協議（MCP）服務器，它通過 HTTP 基本認證，為 Allstacks API 提供了可用於人工智能的訪問方式。

🚀 快速開始

安裝

1. 克隆此倉庫。
2. 使用 uv 安裝依賴：

uv sync

運行服務器

uv run server.py --username YOUR_USERNAME --password YOUR_PASSWORD

命令行選項：

• --username 或 -u：HTTP 基本認證的用戶名（必填）
• --password 或 -p：HTTP 基本認證的密碼（必填）
• --base-url 或 -b：覆蓋默認的 API 基礎 URL（默認值：https://api.allstacks.com/api/v1/）

MCP 客戶端配置

將以下內容添加到你的 MCP 客戶端配置文件（例如，Claude Desktop 的 claude_desktop_config.json）中：

{
    "mcpServers": {
        "allstacks": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/allstacks-mcp",
                "run",
                "server.py",
                "--username",
                "YOUR_USERNAME",
                "--password",
                "YOUR_PASSWORD"
            ]
        }
    }
}

重要提示：

• 將 /ABSOLUTE/PATH/TO/allstacks-mcp 替換為該目錄的完整路徑。
• 將 YOUR_USERNAME 和 YOUR_PASSWORD 替換為你的實際憑證。
• 在 macOS 上，uv 通常位於 ~/.local/bin/uv，請確保它在你的 PATH 中，或者使用完整路徑。
• Claude Desktop 不會繼承你 shell 的 PATH，因此使用 uv 的完整路徑更可靠。

替代配置（直接使用 Python）

如果你更喜歡從虛擬環境中直接使用 Python，可以使用以下配置：

{
    "mcpServers": {
        "allstacks": {
            "command": "/ABSOLUTE/PATH/TO/allstacks-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/allstacks-mcp/server.py",
                "--username",
                "YOUR_USERNAME",
                "--password",
                "YOUR_PASSWORD"
            ]
        }
    }
}

✨ 主要特性

全面的 API 覆蓋

所有工具均根據 Allstacks 官方 OpenAPI 規範進行驗證：

• ✅ 所有端點使用正確的路徑和參數。
• ✅ 詳細的參數描述來自官方 API 文檔。
• ✅ 適當的錯誤處理和驗證。
• ✅ 支持 HTTP 基本認證。
• ✅ 採用異步/等待機制以提高性能。

模塊化架構

工具按照 Allstacks API 結構組織成邏輯類別：

• 易於導航和理解。
• 關注點分離清晰。
• 所有工具遵循一致的模式。
• 有詳細的 OpenAPI 參考文檔。

豐富的工具描述

每個工具都包含：

• 目的和用例。
• 必需和可選參數。
• 預期的返回格式。
• OpenAPI 端點參考。
• 示例使用模式。

📦 安裝指南

1. 克隆此倉庫。
2. 使用 uv 安裝依賴：

uv sync

💻 使用示例

基礎用法

獲取 GMDTS 指標數據

# Get Generated Metric Data Time Series (GMDTS)
get_gmdts_data(
    project_id=123,
    metric_type="Velocity",
    start_date=1704067200000,
    end_date=1706745600000
)

帶過濾條件列出工作項

# List service items with filtering
list_service_items(
    item_type="CARD",
    limit=100,
    offset=0
)

高級用法

創建 AI 報告

# Generate AI analysis report
create_ai_report(
    org_id=456,
    report_type="project_health",
    project_id=123
)

預測工作包

# Get Monte Carlo forecast for work bundle
get_work_bundle_forecast(
    project_id=123,
    bundle_id=789,
    confidence_level=80
)

📚 詳細文檔

概述

此 MCP 服務器公開了 208 + 工具，這些工具被組織成 12 個類別，用於與 Allstacks 進行全面交互：

工具類別

1. 指標與分析（18 個工具）：GMDTS 數據、指標 V2、洞察配置、人口基準、公司指標。
2. 服務項與工作項（21 個工具）：工作項、父服務項、屬性鍵、估算方法、備註、過濾器集的完整 CRUD 操作。
3. 用戶與團隊（23 個工具）：完整的用戶管理、邀請、角色、團隊標籤、個人訪問令牌、服務用戶。
4. 組織與項目（28 個工具）：組織、項目、設置、服務、日曆、時間段、插槽配置。
5. 儀表盤與小部件（20 個工具）：完整的儀表盤/小部件 CRUD 操作、共享鏈接、克隆、小部件管理。
6. 員工分析（9 個工具）：員工指標、群組、工作項、時間線、摘要、時間段。
7. 預測與規劃（11 個工具）：V3 預測、速度、場景、容量規劃、圖表分析。
8. 標籤與標記（17 個工具）：標籤、標籤族、批量操作、服務項標籤分配。
9. 警報與監控（16 個工具）：警報規則、活動警報、通知、訂閱、偏好設置。
10. 人工智能與智能（18 個工具）：AI 報告、Action AI 代碼查詢、指標構建器、模式分析、調查、DX 分數、AI 工具使用情況。
11. 工作包（13 個工具）：可選工作包管理、預測、指標、克隆。
12. 風險管理（14 個工具）：風險定義、項目風險、評估、趨勢、解決。

項目結構

allstacks-mcp/
├── server.py                    # 主入口點 - 208+ 工具
├── allstacks_mcp/
│   ├── __init__.py
│   ├── client.py               # HTTP 基本認證客戶端
│   └── tools/                  # 按類別劃分的工具模塊
│       ├── __init__.py
│       ├── metrics.py          # 18 個指標工具
│       ├── service_items.py    # 21 個服務項工具
│       ├── users_teams.py      # 23 個用戶/團隊工具
│       ├── org_projects.py     # 28 個組織/項目工具
│       ├── dashboards.py       # 20 個儀表盤工具
│       ├── employee.py         # 9 個員工分析工具
│       ├── forecasting.py      # 11 個預測工具
│       ├── labels.py           # 17 個標籤管理工具
│       ├── alerts.py           # 16 個警報/監控工具
│       ├── ai_analytics.py     # 18 個人工智能與分析工具
│       ├── work_bundles.py     # 13 個工作包工具
│       └── risk_management.py  # 14 個風險管理工具
├── pyproject.toml
├── uv.lock
├── FILTERED_ENDPOINTS.md       # 端點驗證文檔
├── TOOLS_MAPPING.md            # 完整的 API 映射
├── ENDPOINT_VERIFICATION.md    # 驗證結果
└── README.md

認證與安全

所需憑證

服務器使用 HTTP 基本認證 連接到 Allstacks API。你需要：

• 用戶名：你的 Allstacks 用戶名或電子郵件地址。
• 密碼：你的 Allstacks 密碼或 API 密鑰。
• 基礎 URL：（可選）默認為 https://api.allstacks.com/api/v1/。

🔒 安全最佳實踐

憑證管理

⚠️ 重要：你的憑證可以完全訪問你的 Allstacks 賬戶。

1. 使用環境變量（推薦）

export ALLSTACKS_USERNAME="your-username"
export ALLSTACKS_PASSWORD="your-api-key"

2. 儘可能使用 Allstacks API 密鑰 而非密碼

• 從你的 Allstacks 賬戶設置中生成 API 密鑰。
• API 密鑰可以撤銷，而無需更改你的密碼。

3. 切勿將憑證提交到版本控制

• MCP 客戶端配置文件可能包含憑證。
• 將配置文件添加到 .gitignore 中。

4. 定期輪換憑證 以增強安全性。

進程安全

注意：命令行參數（--username、--password）在進程列表中可見。對於生產環境：

• 使用環境變量。
• 使用安全的配置文件。
• 考慮使用秘密管理系統。

數據訪問與隱私

此 MCP 服務器作為 Allstacks API 的 代理：

• ✅ 不存儲或記錄你的憑證。
• ✅ 不緩存 API 響應。
• ✅ 不本地持久化任何數據。
• ✅ 原樣返回 API 數據，不做修改。

AI 訪問：當與 AI 助手（如 Claude）一起使用時，AI 將可以訪問：

• 通過你的 Allstacks 憑證可訪問的所有數據。
• 與你的 Allstacks 用戶賬戶相同的權限。
• 根據你的權限創建、修改和刪除資源的能力。

建議：考慮使用具有有限權限的專用 Allstacks 賬戶進行 AI 訪問。

API 兼容性

此服務器基於 Allstacks 官方 API v1 規範構建，包括：

• 僅非管理員端點（無破壞性操作）。
• 適當時對資源進行完整的 CRUD 操作。
• 批量操作以提高效率。
• 適當的分頁支持。
• 查詢參數驗證。

開發

添加新工具

1. 在 allstacks_mcp/tools/ 中創建或更新工具文件。
2. 遵循現有的工具註冊模式。
3. 包含帶有 OpenAPI 參考的完整文檔字符串。
4. 將模塊添加到 allstacks_mcp/tools/__init__.py 中。
5. 在 server.py 的 register_all_tools() 函數中註冊它。

測試

# Run the server in development mode
uv run server.py --username test_user --password test_pass --base-url https://api-dev.allstacks.com/api/v1/

🔧 技術細節

此服務器基於 Allstacks 官方 API v1 規範構建，對所有工具進行了全面的驗證和測試。採用模塊化架構，將工具按類別組織，便於管理和擴展。使用 HTTP 基本認證確保安全連接，同時支持異步/等待機制以提高性能。每個工具都有詳細的文檔和示例，方便用戶使用。

📄 許可證

本項目採用 MIT 許可證。

支持

如果你對 Allstacks API 有任何問題或疑問，請聯繫 Allstacks 團隊。如果你遇到與本 MCP 服務器相關的問題，請在倉庫中提交問題。