AI导哈

模型上下文协议服务器

Allstacks MCP Server 是一个全面的模型上下文协议（MCP）服务器，提供对 Allstacks API 的 AI 就绪访问，支持 HTTP Basic 和 Bearer 个人访问令牌认证。

  • by Allstacks
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Allstacks/allstacks-mcp-server

使用说明

Allstacks MCP服务器

全面的模型上下文协议（MCP）服务器，提供对Allstacks API的AI就绪访问。使用HTTP Basic（用户名+密码）或承载个人访问令牌进行身份验证。

概述

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

工具类别

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

项目结构

allstacks-mcp-server/
├── allstacks_mcp/
│   ├── __init__.py
│   ├── __main__.py             # python -m allstacks_mcp entry point
│   ├── server.py               # Main entry — 170 tools, resources, arg parsing
│   ├── client.py               # HTTP client (Basic + Bearer auth)
│   └── tools/                  # Tool modules by category
│       ├── __init__.py
│       ├── metrics.py          # 8 metrics tools
│       ├── service_items.py    # 12 service item tools
│       ├── users_teams.py      # 20 user/team tools
│       ├── org_projects.py     # 28 org/project tools
│       ├── dashboards.py       # 18 dashboard tools
│       ├── employee.py         # 8 employee analytics tools
│       ├── forecasting.py      # 9 forecasting tools
│       ├── labels.py           # 15 label management tools
│       ├── alerts.py           # 13 alert/monitoring tools
│       ├── ai_analytics.py     # 13 AI & analytics tools
│       ├── work_bundles.py     # 12 work bundle tools
│       ├── risk_management.py  # 12 risk management tools
│       └── discovery.py        # 2 API discovery tools and 2 resources
├── pyproject.toml
├── uv.lock
└── README.md

快速开始

先决条件

  • Python 3.10或更高版本
  • 紫外线 包管理器(curl -LsSf https://astral.sh/uv/install.sh | sh)
  • Allstacks帐户具有以下任一功能：
    • Allstacks UI中的个人访问令牌（PAT）-- 建议所有用户使用，SSO需要
    • 用户名+密码（仅适用于本地帐户，不适用于SSO）

安装

使用Allstacks MCP服务器的最简单方法是通过 uvx，它在一个命令中安装并运行服务器：

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

就是这样！服务器将启动并准备接受MCP连接。

看 身份验证模式 了解全套支持的身份验证选项（PAT与HTTP Basic）以及何时使用每个选项。有关本地开发或对该项目的贡献，请参阅 本地开发 下面的部分。

身份验证和安全

身份验证模式

服务器支持两种身份验证模式。挑选 一 --它们是相互排斥的。

选项A——使用个人访问令牌的承载身份验证（推荐；SSO用户需要）

在Allstacks UI中生成PAT 个人访问令牌 并传递它 --token:

uvx allstacks-mcp --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/
  • ✅ 工作为 所有用户，包括仅SSO帐户
  • ✅ 令牌可以从UI中撤销，而无需更改帐户凭据
  • ✅ 比基于密码的身份验证更安全
  • 令牌以以下方式发送 Authorization: Bearer <token>

选项B——使用用户名+密码的HTTP基本身份验证

仅适用于 本地账户 设置了密码。仅SSO用户将收到401错误。

uvx allstacks-mcp --username your-email@example.com --password your-password --base-url https://app.allstacks.com/api/v1/
  • ⚠️ 仅适用于本地帐户（非SSO用户）
  • 使用HTTP基本身份验证发送凭据

基本URL: 默认值为 https://app.allstacks.com/api/v1/.用覆盖 --base-url 如果您的部署使用不同的端点。

🔒 安全最佳实践

凭据管理

⚠️ 重要：您的凭据提供了对Allstacks帐户的完全访问权限。

  1. 更喜欢个人访问令牌而不是密码 --可撤销、有范围且是SSO用户的唯一选择。

  2. 将凭据从shell历史记录和配置文件中删除 如果可能的话。服务器仅从CLI标志读取凭据，因此，如果要将它们存储在环境变量中，请在启动时将它们展开到标志中：

    export ALLSTACKS_TOKEN="your-pat"
uvx allstacks-mcp --token "$ALLSTACKS_TOKEN"

# or, for Basic auth:
export ALLSTACKS_USERNAME="your-username"
export ALLSTACKS_PASSWORD="your-password"
uvx allstacks-mcp --username "$ALLSTACKS_USERNAME" --password "$ALLSTACKS_PASSWORD"

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

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

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

过程安全

备注：命令行参数(--username, --password, --token)在流程列表中可见，包括在启动时从环境变量展开时。用于生产用途：

  • 限制对运行服务器的主机的访问，这样其他用户就无法读取其进程列表
  • 将凭据存储在安全的机密管理器中，并仅在启动时注入
  • 使用专用的Allstacks帐户或可以快速撤销的短期PAT

数据访问和隐私

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

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

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

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

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

用法

令牌高效响应

大容量列表和时间序列工具接受可选 response_format 论点：

  • response_format="json" 返回已打印好的JSON输出 并且仍然是兼容性的默认值。
  • response_format="toon" 返回紧凑的TOON样式文本编码。数组 重复的对象被表示为表，这会删除重复的字段 每行的名称。

例子：

get_org_metrics_v2_data(org_id, config, response_format="toon")
list_service_items(item_type="CARD", limit=100, response_format="toon")
get_capacity_planning(org_id, start_date="2026-06-01", end_date="2026-06-30", response_format="toon")

使用形状类似常见API响应的合成有效载荷进行测量，使用 字符计数作为独立于标记器的代理：

有效载荷形状 漂亮的JSON字符 TOON字符 缩减
度量时间序列，90行x 4个标量字段 11413 2449 79%
分页服务项列表，100行x 5个标量字段 12357 2367 81%
分配/容量行，60行x 6个标量字段 11421 2133 81%

独立运行服务器

承载/PAT（推荐；SSO用户需要）：

uvx allstacks-mcp --token YOUR_PAT

基本/用户名+密码（仅限本地帐户）：

uvx allstacks-mcp --username YOUR_USERNAME --password YOUR_PASSWORD

命令行选项：

  • --token 或 -t：用于承载身份验证的个人访问令牌（用户名/密码的替代品）
  • --username 或 -u：HTTP基本身份验证的用户名（与配对 --password)
  • --password 或 -p：HTTP基本身份验证密码（与配对 --username)
  • --base-url 或 -b：覆盖默认的API基本URL（默认值： https://app.allstacks.com/api/v1/)
  • --openapi-schema-url：覆盖已发布的OpenAPI架构URL（默认值： <base-url>/schema/)

要么通过 --token 或两者 --username 和 --password --不能同时使用这两种模式。

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop的 claude_desktop_config.json 或克劳德密码 mcp.json).

建议使用PAT/承载身份验证（适用于所有用户，包括SSO）：

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--token",
                "YOUR_PERSONAL_ACCESS_TOKEN",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

备选方案——用户名+密码（仅限本地帐户）：

{
    "mcpServers": {
        "allstacks": {
            "command": "uvx",
            "args": [
                "allstacks-mcp",
                "--username",
                "your-email@example.com",
                "--password",
                "your-password",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

重要提示：

  • 替换 YOUR_PERSONAL_ACCESS_TOKEN 使用Allstacks UI中的实际PAT
  • 或更换 your-email@example.com 和 your-password 使用您的凭据（仅限本地帐户）
  • 这 --base-url 是可选的（默认为 https://app.allstacks.com/api/v1/)
  • OpenAPI资源使用 <base-url>/schema/ 除非 --openapi-schema-url 被提供
  • uvx 自动安装并运行PyPI的最新版本，无需手动安装！

使用本地克隆进行开发？ 请参阅 本地开发 配置模式部分。

特性

API全面覆盖

所有工具都根据官方Allstacks OpenAPI规范进行了验证：

  • ✅ 所有端点都使用正确的路径和参数
  • ✅ API官方文件中的详细参数说明
  • ✅ 正确的错误处理和验证
  • ✅ 通过承载令牌（PAT）或HTTP Basic进行身份验证
  • ✅ 异步/等待性能

API发现资源

代理可以在不加载完整工具目录的情况下发现API形状：

  • get_openapi_schema：使用配置的凭据在运行时获取已发布的OpenAPI模式
  • allstacks://openapi 和 schema://api：MCP资源公开与JSON相同的运行时模式
  • list_tool_categories：返回度量、分配、交付、AI影响和相关域的紧凑域到工具名称映射

模块化架构

工具被组织成与Allstacks API结构匹配的逻辑类别：

  • 易于导航和理解
  • 明确区分关注点
  • 所有工具的一致模式
  • OpenAPI参考文献记录良好

丰富的工具描述

每个工具包括：

  • 目的和用例
  • 必需和可选参数
  • 预期返回格式
  • OpenAPI端点引用
  • 示例使用模式

工具使用示例

获取指标V2数据

# Query Metrics V2 using an inner config object. Use ai_metric_builder first
# when you want to turn a natural-language question into this config shape.
get_project_metrics_v2_data(
    project_id=123,
    config={
        "item_type": "CARD",
        "dimensions": [{"field": "state"}],
        "measures": [{"aggregation": "count"}],
    },
    response_format="toon",
)

使用筛选列出工作项

# 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操作
  • 批量操作以提高效率
  • 适当的分页支持
  • 查询参数验证

本地开发

如果你想为这个项目做出贡献，或者从本地克隆而不是PyPI运行：

设置

  1. 克隆存储库：

    git clone https://github.com/allstacks/allstacks-mcp-server.git
cd allstacks-mcp-server

  2. 安装依赖项：

    uv sync

从本地克隆运行

持票人/PAT（推荐）：

uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

用户名+密码（仅限本地帐户）：

uv run python -m allstacks_mcp.server --username YOUR_USERNAME --password YOUR_PASSWORD --base-url https://app.allstacks.com/api/v1/

MCP客户端配置（本地克隆）

对于Claude Desktop或Claude Code，在使用本地克隆时使用此配置模式：

{
    "mcpServers": {
        "allstacks": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/allstacks-mcp-server",
                "run",
                "python",
                "-m",
                "allstacks_mcp.server",
                "--token",
                "YOUR_PAT",
                "--base-url",
                "https://app.allstacks.com/api/v1/"
            ]
        }
    }
}

替换 /ABSOLUTE/PATH/TO/allstacks-mcp-server 带有克隆存储库的完整路径。

发展

添加新工具

  1. 在中创建或更新工具文件 allstacks_mcp/tools/
  2. 遵循现有的工具注册模式
  3. 包含带有OpenAPI引用的完整文档字符串
  4. 将模块添加到 allstacks_mcp/tools/__init__.py
  5. 在中注册 allstacks_mcp/server.pys register_all_tools() 功能

测试

在处理代码库时，以开发模式运行服务器：

# From local clone with Bearer token
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://app.allstacks.com/api/v1/

# Or with a dev/staging environment
uv run python -m allstacks_mcp.server --token YOUR_PAT --base-url https://api-dev.allstacks.com/api/v1/

许可证

麻省理工学院

支持

有关Allstacks API的问题，请联系Allstacks团队。 对于此MCP服务器特有的问题，请在存储库中提交问题。

相关 MCP