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 服务器相关的问题，请在仓库中提交问题。