specshield-mcp-server

SpecShield MCP サーバー

AI コーディングエージェント向けの API 変更デプロイゲートです。 Claude、Cursor などの MCP クライアント内で、「この API 変更を利用者にリリースしても安全ですか？」 と尋ねて、変更による破壊的な影響が利用者に及ぶ前に検出できます。

SpecShield バックエンドの薄いアダプターです。すべてのツールは読み取り専用／分析専用で、コードを変更することはありません。

仕様の差分を取るだけではだめなのでしょうか？ 無料のものも含め、多くのツールが破壊的変更を一覧表示します。SpecShield の役割は、その判断を下すことです。デプロイできますか？ ——ここで主役となるのがデプロイゲートです。

⚙️ エージェントではなく CI/CD で使いますか？ specshield CLI は、同じ破壊的変更チェックと can-i-deploy チェックをパイプライン（GitHub Action、終了コード）で実行します。同じ役割を果たす 2 つの入り口です。AI エージェントにはこのサーバーを、CI/CD には CLI をご利用ください。

ツール

#	ツール	回答する内容
1	is_change_safe ⭐	この変更はマージ／デプロイしても安全ですか？ 利用者に影響しますか？（safeToMerge ＋リスク＋ブロック理由）
2	explain_breaking_changes	何が影響を受けるか、開発者と利用者への影響、推奨される移行方法
3	generate_migration_guide	移行ガイド（Markdown）＋安全な段階的リリース手順
4	generate_release_notes	開発者向け／顧客向け／内部向けのリリースノート
5	compare_specs	生の差分（破壊的変更／追加／変更／警告）＋リスクスコア
6	run_governance_review 🔒	破壊的変更に加えた API ガバナンスルールセット（operationId の欠落、エラーレスポンス、セキュリティスキーム、ページネーション、バージョン管理など）→ 該当箇所の特定と修正案。有料（Team 以上）

ツール 1～5 は、仕様をインラインで渡す（baseSpecContent／targetSpecContent）か、パスで指定します（baseSpecPath／targetSpecPath）。run_governance_review は単一の仕様をレビューします（specContent／specPath）。

🔒 run_governance_review は有料機能です。FREE API キーを使用すると、payment_required エラーが返されます。specshield.io/pricing でプランをアップグレードしてください。

セットアップ、検証、トラブルシューティングの詳細：docs/mcp-server-setup.md。

インストール

Node.js ≥ 20 と SpecShield API キー（specshield.io/account から取得）が必要です。

npx -y specshield-mcp-server

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "specshield": {
      "command": "npx",
      "args": ["-y", "specshield-mcp-server"],
      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
    }
  }
}

Claude Code

claude mcp add specshield --env SPECSHIELD_API_KEY=ss_your_key_here -- npx -y specshield-mcp-server

Cursor

~/.cursor/mcp.json（またはプロジェクトの .cursor/mcp.json）：

{
  "mcpServers": {
    "specshield": {
      "command": "npx",
      "args": ["-y", "specshield-mcp-server"],
      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
    }
  }
}

設定

環境変数	必須	デフォルト	用途
SPECSHIELD_API_KEY	はい	—	SpecShield API キーです。シークレットとして保存し、絶対にコミットしないでください。
SPECSHIELD_API_URL	いいえ	https://api.specshield.io	バックエンドのベース URL（セルフホスト／ステージング環境で上書き）。
SPECSHIELD_TIMEOUT_MS	いいえ	30000	リクエストごとのタイムアウト。
SPECSHIELD_LOG_LEVEL	いいえ	info	debug | info | warn | error（ログは stderr に出力されます）。

プロンプトの例（デプロイゲートから始める）

• 「古い openapi.yaml と新しい openapi.yaml はこちらです。この API 変更を利用者にリリースしても安全ですか？」
• 「v1.yaml と v2.yaml を比較して、デプロイできるか、できない場合はその理由を教えてください。」
• 「この 2 つの仕様間の破壊的変更と、利用者が移行する方法を説明してください。」
• 「この API 変更について、顧客向けのリリースノートを作成してください。」

セキュリティとプライバシー

• API キーが必要です。 設定したバックエンドへの X-Api-Key ヘッダーとしてのみ送信されます。
• 読み取り専用／分析専用です。 変更を加えるツール、シェル実行、任意のファイルアクセスはありません（仕様ファイルはパスを明示的に渡した場合にのみ読み取られます）。
• シークレットや仕様のログ記録はありません。 サーバーは仕様の内容、API キー、リクエストボディを記録しません。エラーメッセージは機密情報が伏せられ、機械可読です。
• 仕様は、分析のために設定した SpecShield バックエンドへ送信されます。

ローカル開発

npm install
npm run build      # tsc → dist/
npm test           # vitest (no network)
npm run lint
npm run smoke      # boots the server against a stubbed backend and lists tools
npm start          # run the built server over stdio

ライセンス

MIT © SpecShield Software Private Limited