跳到主要内容

项目范围限定

Almirant MCP 服务器支持在连接 URL 中使用可选的 projectId 参数，以自动将操作限制在指定项目中。当 AI 代理在单个项目上下文中工作时，此功能尤其有用。

工作方式​

在连接 URL 中配置 projectId 后：

  • list_projects 仅返回已配置的项目
  • list_work_items 自动按项目筛选
  • create_work_item 将该项目用作默认值
  • create_task、create_story、create_feature、create_epic 要求在会话中配置 projectId
  • list_idea_items 自动按项目筛选
  • list_milestones 自动按项目筛选
  • get_board_context 返回已配置项目的看板

未配置 projectId 时，工具会在组织的所有项目中运行。

配置​

将 projectId 参数作为查询字符串添加到 URL 中：

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=<your-project-uuid>",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

如何获取项目 ID​

有两种方式可查找项目 ID：

从 Almirant 界面获取​

  1. 在 Almirant 中导航至所需项目
  2. UUID 会显示在浏览器 URL 中：https://app.almirant.ai/projects/<project-uuid>/...

从未限定范围的 MCP 获取​

在未配置 projectId 的情况下运行 list_projects 工具，以获取包含其 ID 的完整项目列表：

{
  "tool": "list_projects"
}

响应将包含每个项目的 id：

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Project"
    }
  ]
}

参数覆盖​

接受显式 projectId 参数的工具始终优先使用该参数，而非会话中配置的值。这使你无需更改配置即可对其他项目执行一次性操作：

{
  "tool": "list_work_items",
  "params": {
    "projectId": "another-project-uuid"
  }
}

受范围限定影响的工具​

工具使用 projectId 时的行为
list_projects仅返回已配置的项目
list_work_items自动按项目筛选
create_work_item未传递 projectId 时使用该项目作为默认值
create_task要求会话中包含 projectId（不接受参数）
create_story要求会话中包含 projectId（不接受参数）
create_feature要求会话中包含 projectId（不接受参数）
create_epic要求会话中包含 projectId（不接受参数）
get_board_context返回已配置项目的看板
get_project_roadmap使用已配置项目作为回退值
list_idea_items自动按项目筛选
list_milestones使用已配置项目作为回退值
create_milestone使用已配置项目作为回退值
get_implement_context使用已配置项目作为回退值
get_ideation_context使用已配置项目作为回退值
get_validate_context使用已配置项目作为回退值
resolve_work_items配置后按项目筛选结果
建议

对于 AI 代理工作流，建议始终在连接 URL 中配置 projectId。这可避免因上下文缺失导致的错误，并确保所有操作均在正确的项目中执行。