Squad AI

Squad MCP Server

Squad — AI プロダクトのフィードバックインテリジェンスプラットフォーム — を AI ワークフローに直接取り込むリモート MCP サーバーです。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 を使用して接続します。OAuth 設定は、サーバーの .well-known/oauth-protected-resource メタデータを通じて自動的に検出されます。このメタデータによって、クライアントは認可サーバーとして PropelAuth に誘導されます。

📖 使用例

実際の詳細な使用例については、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 — 1回の呼び出しで全体を把握できます。ミッションと説明、主要な目標、最近のシグナル活動、エビデンスチェーンの健全性、未完了の作業数を取得します。
• 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 — アクション、その親インサイト、その根拠となる顧客エビデンス、関連する目標をまとめて1回の呼び出しで取得し、アクションの実行に必要な情報を揃えます。
• update_action — アクションの優先度、工数、カテゴリ、メモを編集したり、担当者を割り当てたり、インサイトまたはブリーフにリンクしたりします。
• update_action_status — アクションのライフサイクルに沿って、開始、完了、却下、または保留にします。
• list_goals — 重要度順に並んだ戦略目標を一覧表示します。
• create_goal — 戦略目標を作成します。
• update_goal — 目標のタイトル、説明、または重要度を更新します。
• update_insight — インサイトを整理し、カテゴリやステータスを設定したり、支援する目標をリンクまたはリンク解除したりします。
• dismiss_signal — ノイズ、スパム、または誤って取り込まれたコンテンツなどのシグナルを、ワークスペースから完全に削除します。
• get_activity — 人とSquadエージェントによる、ワークスペースの変更履歴を新しい順に表示します。
• 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 — 重複を確認し、フィードバックを1件取り込み、取り込み先を報告します。
• weekly-product-review — 何が変わったか、エビデンスが何を示しているか、何を判断する必要があるかを確認します。
• draft-decision-brief — アクションまたはインサイトからブリーフを生成し、読みやすい下書きに仕上げます。
• ground-this-ticket — コーディングエージェント向け。作業に着手する前に、その作業の根拠となる顧客エビデンスを取得します。

リソース

これらをピン留めしておけば、戦略に関する質問のためにツールを呼び出す必要はありません。

• 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 レイヤーはセッションを保持せず、呼び出しのたびに独自のベアラートークンを再イントロスペクションします。Redis はユーザーごとの永続的な状態（ワークスペースの選択と発行済みトークンのキャッシュ）を保存するため、どのインスタンスでもあらゆるリクエストを処理できます。バックエンドの型は、コミット済みの 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	✅	トークンのイントロスペクションに使用する OAuth 2.1 クライアントの認証情報
PROPELAUTH_API_KEY	✅	サービス JWT の発行に使用するバックエンド統合キー
SQUAD_ENV		dev または production（デフォルトは production）— 認証／API／アプリの URL を選択します
PORT / MCP_URL / BASE_URI		サーバーのポートと外部に公開するベース URL
REDIS_URL		デプロイ環境で安全にワークスペースを選択し、トークンをキャッシュするための 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 経由で接続するため、セルフホストは不要です。

アーキテクチャに関する注記（コントリビューター向け）：

• /health レディネスチェックを備え、Railway 上にデプロイされています
• リクエスト処理はステートレスです。Redis がユーザーごとのワークスペース選択とトークンキャッシュを保持するため、インスタンスを水平スケーリングできます
• ストリーミング可能な HTTP トランスポートについて、MCP 仕様に準拠しています
• SEP-2127 のディスカバリードキュメントを公開しています。Server Card（https://mcp.meetsquad.ai/mcp/server-card）と AI Catalog（https://mcp.meetsquad.ai/.well-known/ai-catalog.json）はいずれも公開され、キャッシュ可能で、server.json から生成されます

💬 サポート

Squad MCP サーバーでお困りですか？

• メール： [email protected]
• ドキュメント：
  • Squad MCP ガイド — セットアップと統合の完全ガイド
  • USAGE_EXAMPLES.md — 実際の使用例
• 問題報告： GitHub Issues — バグ報告と機能リクエスト
• プライバシーポリシー： 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/ が古い場合は失敗します。