Squad AI

Squad MCP Server

一个远程 MCP 服务，可将 Squad——AI 产品反馈智能平台——直接接入你的 AI 工作流。将 Squad 连接到 Claude、ChatGPT 或任何兼容 MCP 的 AI 助手，无需切换上下文，即可将原始用户反馈转化为信号、洞察、行动和简报。

Squad 持续收集反馈，将其归类为信号，提炼为洞察，并关联到推动产品发展的行动和目标。MCP 服务提供同样的智能能力——读取决策背后的证据、收集新反馈，并通过助手生成简报。

🚀 快速开始

面向用户

只需几秒，即可将 Squad 连接到你的 AI 助手：

Claude Code：

claude mcp add --transport http squad https://mcp.meetsquad.ai/mcp

首次使用时，系统会提示你在浏览器中通过 OAuth 进行身份验证。

其他 MCP 客户端：

使用 https://mcp.meetsquad.ai/mcp 进行连接——系统会通过服务的 .well-known/oauth-protected-resource 元数据（其中会将客户端指向 PropelAuth 作为授权服务）自动发现 OAuth 配置。

📖 使用示例

详细的实际示例请参阅 USAGE_EXAMPLES.md。你可以尝试提出以下请求：

• 整理反馈——“在 Squad 中记录这条支持工单，并告诉我它是否属于已知主题。”
• 每周回顾——“进行我的每周产品回顾：有哪些变化？哪些事项需要决策？”
• 追溯证据——“向我展示洞察 IN-42 背后的客户信号。”
• 起草简报——“为行动 AC-12 生成一份简报。”
• 搜索所有内容——“查找所有与新手引导流程阻力相关的反馈。”
• 追溯工单依据——“在我开始实施之前，提取 AC-7 背后的客户证据。”

Squad 实体使用简短的显示 ID进行引用，以便助手标注其证据：

前缀	实体	前缀	实体
SI-	信号	GL-	目标
IN-	洞察	BR-	简报
AC-	行动	DC-	文档
CL-	集群

工具

该服务端提供 30 个工具。写入工具需要使用 write:workspace 范围创建的令牌；读取工具只需要 read:workspace。

• list_workspaces — 列出你可以访问的所有组织和工作区，并标记当前选项。
• select_workspace — 选择后续工具要操作的组织和工作区。
• get_workspace_overview — 一次调用即可了解概况：使命和描述、主要目标、近期信号活动、证据链健康状况，以及未完成工作的数量。
• update_workspace — 更新当前工作区的名称、描述、使命陈述或徽标。
• list_members — 列出当前组织中的人员及其用户 ID。
• search — 跨信号、洞察、行动、目标、文档和集群进行关键词搜索。
• get_entity — 通过显示 ID（SI-1、IN-1、AC-1、GL-1、BR-1、DC-1、CL-1）或 UUID 获取任意实体。也可用于检查异步工作。
• list_signals — 浏览原始反馈信号，可按来源、类型、情感倾向、集群和日期范围筛选。
• find_similar_signals — 查找与给定信号语义相关的信号——“还有其他人也这么说吗？”
• list_clusters — 浏览信号集群（反馈中的反复主题），包括规模和标签。
• get_cluster — 获取集群的标签、统计信息、成员信号和关联洞察。
• list_insights — 浏览按综合评分排名的提炼洞察，可按类别、评分、状态筛选，或限定到某个目标。
• list_actions — 浏览按证据所指示的后续行动排名的行动，可按状态、负责人、优先级或所属洞察筛选。
• get_action_context — 一次调用即可获取执行某项行动所需的全部信息：该行动、所属洞察、相关客户证据以及它服务的目标。
• update_action — 编辑行动的优先级、工作量、类别或备注；分配负责人；或将其关联到洞察或简报。
• update_action_status — 推进行动的生命周期：开始、完成、忽略或暂缓。
• list_goals — 按重要性排序的战略目标。
• create_goal — 创建战略目标。
• update_goal — 更新目标的标题、描述或重要性。
• update_insight — 管理洞察：设置类别或状态，并关联或取消关联其支持的目标。
• dismiss_signal — 从工作区永久移除信号（噪声、垃圾信息或误导入的内容）。
• get_activity — 工作区变更动态，包含人员和 Squad Agent 的活动，按时间从新到旧排序。
• list_documents — 浏览工作区知识文档（和简报），查看其路径和标签。
• create_document — 根据 Markdown 创建知识文档（研究摘要、会议记录、分析）。
• update_document — 替换文档的 Markdown 正文和／或标题，并管理标签。
• list_briefs — 查看简报及其状态（building/draft/in_review/finalised/failed）和建议。
• generate_brief — 启动 AI，根据某项行动或洞察生成简报。
• update_brief_status — 推进简报的审核流程：draft、in_review 或 finalised。
• ingest_signal — 将用户反馈导入证据链（1–50 项，由服务端去重）。
• list_integrations — 查看此工作区已连接的反馈来源及其同步状态。

提示词

通过 MCP 提示词提供的现成工作流：

• triage-feedback — 检查重复项、导入一条反馈，并报告其归属位置。
• weekly-product-review — 了解有哪些变化、证据表明什么，以及有哪些事项需要决策。
• draft-decision-brief — 根据某项行动或洞察生成简报，并将其逐步完善为可读的草稿。
• ground-this-ticket — 面向编码 Agent：在开始构建之前，获取某项工作的相关客户证据。

资源

固定这些资源，让战略问题无需调用工具即可回答：

• squad://workspace/context — 当前工作区的使命和产品背景。
• squad://goals — 工作区的战略目标及其重要性排名。

工具能力

• ✅ 每个工具都带有安全注解（readOnlyHint / destructiveHint）
• ✅ 结构化的 Zod 输入模式
• ✅ 通过 OAuth 隔离用户和工作区的数据访问
• ✅ 受作用域限制的写入（write:workspace）

🏗️ 架构

┌─────────────┐         OAuth          ┌──────────────┐
│  Claude /   │ ◄────────────────────► │  PropelAuth  │
│  ChatGPT    │    (Authentication)     │   (IdP)      │
└─────────────┘                         └──────────────┘
       │
       │ HTTPS + Bearer Token
       ▼
┌──────────────────────────────────────────────┐
│  Squad MCP Server                            │
│  ┌────────────────────────────────────────┐  │
│  │  OAuth → introspect + verify token     │  │
│  │  JWT minting → service credentials     │  │
│  │  Redis → workspace selection + tokens  │  │
│  │  MCP handler → tools / prompts / res.  │  │
│  │  PostHog → tool-call telemetry         │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘
       │
       │ Squad API Calls (minted JWT)
       ▼
┌──────────────┐
│  Squad API   │
└──────────────┘

该服务基于 mcp-use v2 构建，并通过 GraphQL 与 Squad 平台 API 通信。每个请求都以无状态方式处理：MCP 层不保留会话，每次调用都会重新验证自己的 bearer token。Redis 存储持久化的用户级状态（工作区选择和已签发 token 缓存），因此任何实例都可以处理任何请求。后端类型由已提交的 GraphQL 架构快照生成（参见 GraphQL 代码生成）。

🛠️ 开发

此代码库包含 Squad MCP 远程服务的源代码。

前置条件

• Node.js 22+
• pnpm
• Nix（可选，通过 flake.nix 提供可复现的开发环境）
• PropelAuth 凭据（OAuth 2.1 客户端 + 后端 API 密钥）
• Redis（本地使用时可选；未配置时，工作区选择会回退到内存）

本地设置

# Clone repository
git clone https://github.com/the-basilisk-ai/squad-mcp.git
cd squad-mcp

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your PropelAuth credentials (and SQUAD_ENV=dev to target the dev platform)

# Start development server with hot reload
pnpm dev

# Server available at http://localhost:3232

环境变量

变量	必需	用途
PROPELAUTH_CLIENT_ID / PROPELAUTH_CLIENT_SECRET	✅	用于 token 验证的 OAuth 2.1 客户端凭据
PROPELAUTH_API_KEY	✅	用于签发服务 JWT 的后端集成密钥
SQUAD_ENV		dev 或 production（默认值为 production）——选择身份验证/API/应用 URL
PORT / MCP_URL / BASE_URI		服务端口和对外公布的基础 URL
REDIS_URL		用于确保部署安全的工作区选择和 token 缓存的 Redis 连接（未设置时使用内存）。部署时使用受限的 mcp 用户，参见 Redis 访问控制
SQUAD_GRAPHQL_URL		覆盖 Squad GraphQL 端点（代码生成也会使用）
POSTHOG_API_KEY / POSTHOG_HOST		启用工具调用遥测
LOG_LEVEL		日志详细程度

可用命令

pnpm dev                # Start dev server with hot reload (mcp-use)
pnpm build              # Build the server (mcp-use)
pnpm start              # Start the built server
pnpm deploy             # Deploy via mcp-use
pnpm test               # Run unit tests (vitest)
pnpm format             # Lint/format check (biome)
pnpm format:fix         # Auto-fix lint/format issues
pnpm codegen            # Regenerate GraphQL types from schema.graphql
pnpm codegen:check      # Fail if generated GraphQL types are stale

测试服务

# Check health
curl http://localhost:3232/health

# Check OAuth discovery
curl http://localhost:3232/.well-known/oauth-protected-resource

# Check server-card discovery (SEP-2127)
curl -H 'Accept: application/mcp-server-card+json' \
  http://localhost:3232/mcp/server-card
curl http://localhost:3232/.well-known/ai-catalog.json

# Test with the built-in inspector
pnpm dev   # then open the inspector and connect to http://localhost:3232/mcp

项目结构

squad-mcp/
├── server.ts                   # MCP server entry point (OAuth, tool/prompt/resource registration)
├── server.json                 # MCP registry metadata (see MCP_REGISTRY.md)
├── schema.graphql              # Committed snapshot of the Squad platform GraphQL schema
├── codegen.ts                  # GraphQL Code Generator config
├── src/
│   ├── tools/                  # Tool implementations, grouped by surface
│   │   ├── registry.ts         # Single registration path (annotations, errors, telemetry)
│   │   ├── workspace.ts        # list/select workspaces, overview, members
│   │   ├── search.ts           # semantic search
│   │   ├── get-entity.ts       # fetch any entity by display ID / UUID
│   │   ├── evidence.ts         # signals, clusters, insights
│   │   ├── actions-read.ts     # list actions, action context
│   │   ├── actions-write.ts    # update actions + status
│   │   ├── strategy-read.ts    # goals, activity
│   │   ├── strategy-write.ts   # create/update goals, insights, dismiss signals
│   │   ├── knowledge.ts        # documents + briefs
│   │   ├── ingest.ts           # ingest new signals
│   │   └── integrations.ts     # list connected sources
│   ├── prompts/                # MCP prompt workflows
│   ├── resources/              # MCP resources (workspace context, goals)
│   ├── gql/                    # Generated GraphQL types (pnpm codegen)
│   ├── graphql/                # GraphQL operation documents
│   ├── helpers/                # OAuth provider, token minting, workspace selection, KV/Redis
│   └── lib/                    # Squad API client, logger, telemetry, server card
├── railway.toml                # Railway deployment config
└── .env.example                # Environment template

🏭 生产部署

这是由 Squad 维护的托管服务。用户通过 OAuth 连接，无需自托管。

架构说明（供贡献者参考）：

• 部署在 Railway 上，并通过 /health 就绪检查
• 以无状态方式处理请求，Redis 保存用户级工作区选择和 token 缓存，因此实例可以水平扩展
• 遵循 MCP 规范，使用可流式传输的 HTTP 传输方式
• 发布 SEP-2127 发现文档：位于 https://mcp.meetsquad.ai/mcp/server-card 的 Server Card 和位于 https://mcp.meetsquad.ai/.well-known/ai-catalog.json 的 AI Catalog；两者均公开、可缓存，并由 server.json 构建

💬 支持

需要 Squad MCP 服务方面的帮助？

• 电子邮件： [email protected]
• 文档：
  • Squad MCP 指南 — 完整的设置与集成指南
  • USAGE_EXAMPLES.md — 实际使用示例
• 问题反馈： GitHub Issues — Bug 报告和功能请求
• 隐私政策： meetsquad.ai/privacy-policy
• Squad 平台： meetsquad.ai

🤝 参与贡献

欢迎贡献！Pre-commit 钩子会自动运行 biome 和 vitest。请确保：

• pnpm format 通过（biome）
• pnpm build 编译无错误
• pnpm test 通过
• 如果修改了 GraphQL 操作，pnpm codegen:check 通过
• 所有工具都包含安全注释

📄 许可证

MIT

🔗 链接

• Squad MCP 文档 — 完整的设置与集成指南
• Squad 平台
• MCP 规范
• 问题跟踪器

GraphQL 代码生成

后端访问通过 GraphQL Code Generator 进行类型化。schema.graphql 是 Squad 平台 API 架构的已提交快照；src/gql/ 根据该快照和 src/graphql/ 中的操作文档生成。

• 刷新快照：从 API 仓库复制 packages/graphql/src/schema/generated.graphql 并覆盖 schema.graphql（或设置 SQUAD_GRAPHQL_URL 以检查实时端点），然后运行 pnpm codegen。
• CI 会运行 pnpm codegen:check，如果 src/gql/ 已过期则会失败。