Allstacks MCP Server

Allstacks MCP服务器

全面的模型上下文协议（MCP）服务器，使用HTTP基本身份验证提供对Allstacks API的AI就绪访问。

概述

此MCP服务器公开 194+工具 组织成 12个类别 与Allstacks进行全面交互：

工具类别

1. 度量与分析（20个工具）：GMDTS数据、指标V2（包括资本化预览）、模板、洞察配置、人口基准、公司指标
2. 服务项目和工作项目（18个工具）：完成工作项、父服务项、属性键、估计方法、注释、过滤器集的CRUD
3. 用户和团队（20个工具）：完整的用户管理、邀请、角色、团队标签、个人访问令牌、服务用户
4. 组织和项目（31个工具）：组织、项目、设置、服务、日历、时间段、时段、资本化报告（V2）
5. 仪表板和小部件（18个工具）：完整的仪表板/小部件CRUD、共享链接、克隆、小部件管理
6. 员工分析（8个工具）：员工指标、队列、工作项、时间线、摘要、期间
7. 预测与规划（10个工具）：V3预测、速度、情景、容量规划、图表分析
8. 标签和标记（15个工具）：标签、标签系列、批量操作、服务项目标签分配
9. 警报和监控（14个工具）：警报规则、活动警报、通知、订阅、首选项
10. 人工智能与智能（16种工具）：AI报告、Action AI代码查询、指标构建器、AI指标构建器（项目）、模式分析、调查、DX评分、AI工具使用
11. 工作包（12个工具）：可选择的工作包管理、预测、指标、克隆
12. 风险管理（12种工具）：风险定义、项目风险、评估、趋势、解决方案

项目结构

allstacks-mcp/
├── server.py                    # Main entry point - 194+ tools
├── allstacks_mcp/
│   ├── __init__.py
│   ├── client.py               # HTTP Basic Auth client
│   └── tools/                  # Tool modules by category
│       ├── __init__.py
│       ├── metrics.py          # 20 metrics tools
│       ├── service_items.py    # 18 service item tools
│       ├── users_teams.py      # 20 user/team tools
│       ├── org_projects.py     # 31 org/project tools
│       ├── dashboards.py       # 18 dashboard tools
│       ├── employee.py         # 8 employee analytics tools
│       ├── forecasting.py      # 10 forecasting tools
│       ├── labels.py           # 15 label management tools
│       ├── alerts.py           # 14 alert/monitoring tools
│       ├── ai_analytics.py     # 16 AI & analytics tools
│       ├── work_bundles.py     # 12 work bundle tools
│       └── risk_management.py  # 12 risk management tools
├── pyproject.toml
├── uv.lock
├── FILTERED_ENDPOINTS.md       # Endpoint verification document
├── TOOLS_MAPPING.md            # Complete API mapping
├── ENDPOINT_VERIFICATION.md    # Verification results
└── README.md

安装

1. 克隆此存储库
2. 使用安装依赖项 uv:

   uv sync

身份验证和安全

所需凭据

服务器使用 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"

1. 使用所有堆栈API密钥 尽可能使用密码

- 从Allstacks帐户设置生成API密钥 - API密钥可以在不更改密码的情况下被吊销

1. 从不提交凭据 到版本控制

- MCP客户端配置文件可能包含凭据 - 将配置文件保存在 .gitignore

1. 定期轮换凭据 增强安全性

过程安全

备注：命令行参数(--username, --password)在流程列表中可见。用于生产用途：

• 使用环境变量
• 使用安全配置文件
• 考虑使用秘密管理系统

数据访问和隐私

此MCP服务器充当 通过 至Allstacks API：

• ✅ 不存储或记录您的凭据
• ✅ 不缓存API响应
• ✅ 不在本地保存任何数据
• ✅ 返回API数据as-is而不进行修改

AI访问：当与人工智能助手（如Claude）一起使用时，人工智能将可以访问：

• 所有数据均可通过Allstacks凭据访问
• 与您的Allstacks用户帐户具有相同的权限
• 创建、修改和删除资源的能力（取决于您的权限）

推荐：考虑使用具有有限AI访问权限的专用Allstacks帐户。

用法

运行服务器

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端点引用
• 示例使用模式

工具使用示例

获取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
)

API兼容性

此服务器是根据官方Allstacks API v1规范构建的，包括：

• 仅限非管理员端点（无破坏性操作）
• 在适当的情况下对资源进行完整的CRUD操作
• 批量操作以提高效率
• 适当的分页支持
• 查询参数验证

发展

添加新工具

1. 在中创建或更新工具文件 allstacks_mcp/tools/
2. 遵循现有的工具注册模式
3. 包含带有OpenAPI引用的完整文档字符串
4. 将模块添加到 allstacks_mcp/tools/__init__.py
5. 在中注册 server.pys 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的问题，请联系Allstacks团队。 对于此MCP服务器特有的问题，请在存储库中提交问题。