suspec-mcp

Suspec の決定的チェッカーにシェルなしでアクセスするための、薄い MCP stdio アダプターです。薄さが特徴です。 チェックコントラクト 0.26.0 を要求し、すべての CLI JSON ペイロードを検証し、順序付けられたレポートと終了ステータスを保持します。

ツール

suspec_check

絶対アーティファクトパスの順序付き非空配列に対して、1 つの CLI プロセスを実行します。フロントマターの type: が動作を選択します。

Spec、task、change-plan、campaign の入力は CLI チェックを受けます。Inventory、audit、research、panel は checked: false を返します。欠落した型と不明な型は拒否されます。

1 回の呼び出しは C002 などのファイル横断チェックを保持します。タスクパスは 1 つの specPath を共有し、すべてのタスクがそのスペックを指定する必要があります。無効なコンパニオンペアリングは、ok: false を含む CLI の構造化された拒否を生成します。

すべてのアーティファクト結果は自身の型を繰り返します。型を持たないのは、オプションの最後の (file set) レポートだけです。

suspec_get_checks

簡潔モードで、コントラクトのバージョンと各コアチェックの ID および重大度を返します。名前を取得するには responseFormat: "detailed" を使用します。同じコントラクトは suspec://checks で利用できます。

起動時とリソース読み取りでは、終了コード 0 で正確なコントラクト 0.26.0 が必要です。リソースの失敗は、エラードキュメントをリソースコンテンツとして返す代わりにスローします。

Related MCP server: governed-mcp

エンベロープ

アダプターの呼び出しが成功するたびに、以下を返します：

• ok: CLI が実行され、有効なペイロードを生成したかどうか。診断がクリーンかどうかではありません。

• source: 正確なコマンドと終了コード。

• data: 検証済みの詳細出力または簡潔なプロジェクション。

• オプションの note。

• responseFormat。

ok はアダプターが機能したことを意味し、アーティファクトが良好であることを意味しません。ブロッキング診断のあるチェックも ok: true のままです。data.level、診断、source.exitCode を確認してください。

CLI の終了コード 0、1、2 はコントラクトに属します。その他の終了コードはアダプターの起動失敗です。JSON 形式の stdout は新しいコントラクトを交渉しません。構造化された CLI エラーは終了コード 2 の場合のみ受け入れられます。

インストール

Node.js 22.6 以降と suspec CLI が必要です。どちらのパッケージも公開されていません。

git clone https://github.com/jcosta33/suspec-mcp
cd suspec-mcp
corepack enable
pnpm install --frozen-lockfile

GUI クライアントがシェル PATH に依存しないように、絶対エントリポイントを構成します：

{
  "mcpServers": {
    "suspec": {
      "command": "/absolute/path/to/suspec-mcp/bin/suspec-mcp.js",
      "args": ["--suspec-bin", "/absolute/path/to/suspec-cli/bin/suspec.js"]
    }
  }
}

CLI の優先順位：

各ツール呼び出しは完全なアーティファクトパスを提供します。サーバーはリポジトリ、ワークスペース、構成、ストアをバインドしません。これはアダプターであり、第二の製品ブレインではありません。 ~/.agents/artifacts/<workspace>/ に特別な実行時意味はありません。ユーザーレベルのポリシーインストールは CLI の役割です：suspec setup を直接実行してください。MCP はセットアップ、ストレージ、プロモーション、ライフサイクル、オーケストレーションの表面を公開しません。

セキュリティ

• プライマリパスとコンパニオンパスは絶対パスであり、制御文字、フォーマット文字、行区切り文字を含んではいけません。

• アダプターはシェルを使用せず、固定の引数配列を渡します。

• check とサポートされているコンパニオンまたはコントラクトのフラグのみが CLI に到達します。setup はサブプロセスが開始する前に拒否されます。

• CLI のチェック表面は読み取り専用です。

サーバーはプロセスがアクセスできる任意のパスを読み取ることができます。ファイルシステムの権限はセキュリティ境界であり、提案ではありません。プロセスの権限をクライアントの信頼境界に合わせるか、OS のサンドボックスを適用してください。

開発

フィクスチャのドリフトには実際の CLI を使用します。手書きの一致は何も証明しません。SUSPEC_BIN を絶対 CLI ソースパスに設定してください。そうしない場合、suspec-cli という名前の兄弟パッケージがディスカバリを満たす可能性があります。生成は他のパッケージを拒否します。

export SUSPEC_BIN=/absolute/path/to/suspec-cli/bin/suspec.js
pnpm install
pnpm test:run
pnpm gate
pnpm fixtures

test/fixtures/provenance.json は CLI の git HEAD、完全なダーティワークツリーハッシュ、バイナリハッシュを記録します。scripts/generate-fixtures.mjs が出力をキャプチャし、テストはすべてのフィクスチャを src/suspec/contract.ts を通じて解析します。フィクスチャは生成され、手編集されることはありません。

ライセンス

MIT