Evolith Architecture Governance

@beyondnet/evolith-mcp

Evolith MCP Gateway — ファーストクラスの Model Context Protocol サーバー

バイリンガルナビゲーション： スペイン語版

MCP サーバーを CLI から切り離します。これは、CLI のサブプロセスを起動するのではなく、再利用可能なビジネスロジック層である @beyondnet/evolith-core と連携する Gateway として MCP ツールを公開する、ファーストクラスの製品です。

---

目次

1. アーキテクチャ図
2. トランスポート
3. インストールと設定
4. 認証
5. 利用可能なツール（55）
6. 利用可能なリソース（12 + 動的）
7. 利用可能なプロンプト（8）
8. 変更操作
9. 内部アーキテクチャ
10. エージェントのユースケース
11. クライアント設定
12. SmartCLI との統合
13. 拡張ガイド
14. 可観測性
15. ベストプラクティス
16. トラブルシューティング

---

アーキテクチャ図

sequenceDiagram
    participant Agent as "AI Agent<br/>(Cursor, Claude Desktop, Custom)"
    participant Gateway as "MCP Gateway<br/>@beyondnet/evolith-mcp"
    participant Core as "Business Logic<br/>@beyondnet/evolith-core"
    participant FS as "File System"
    participant Git as "Git"

    Note over Agent,Gateway: Transport: stdio (local) or Streamable HTTP (remote)

    Agent->>+Gateway: tools/call { name: "evolith-validate", args: { path: "/repo" } }

    Gateway->>Gateway: 1. Generate correlationId (evl-xxx)
    Gateway->>Gateway: 2. Lookup tool in ToolRegistry
    Gateway->>Gateway: 3. ABAC authorization check
    Gateway->>Gateway: 4. Start timing + structured log (Pino)

    Gateway->>+Core: ValidateSatelliteUseCase.execute({ satellitePath })
    Core->>+FS: Read evolith.yaml, rulesets/
    FS-->>-Core: Configuration + rule definitions

    Core->>+Git: Check ADR history, phase state
    Git-->>-Core: Phase & commit data

    Core->>Core: Evaluate rules (Native + OPA)
    Core-->>-Gateway: ValidationResult { status, issues }

    Gateway->>Gateway: 5. Wrap in SuccessEnvelope { success, data, meta }
    Gateway->>Gateway: 6. Audit log + completion duration

    Gateway-->>-Agent: { content: [{ type: "text", text: "{...}" }] }

    Note over Agent,Gateway: All errors wrapped in ErrorEnvelope with EvolithErrorCode

---

トランスポート

トランスポート	用途	コマンド
stdio（JSON-RPC 2.0）	ローカルエージェント、Cursor、Claude Desktop	evolith-mcp serve
Streamable HTTP（公式 MCP SDK）	リモートエージェント、スケーラビリティ	evolith-mcp serve --transport http --port 49100

デフォルトのポートは 3000 です（main.ts：環境変数 PORT または --port を使用し、どちらも指定されていない場合は 3000 になります）。例で使用している 49100 は任意の値であり、デフォルトではありません。

stdout は stdio トランスポートの JSON-RPC ストリーム用に確保されているため、ログは常に stderr（Pino）に書き込まれます。

---

インストールと設定

インストール

# From the monorepo
npm install @beyondnet/evolith-mcp

# Or globally
npm install -g @beyondnet/evolith-mcp

使用方法

# stdio (default) — for Cursor, Claude Desktop, etc.
evolith-mcp serve

# HTTP — for remote integration
evolith-mcp serve --transport http --port 49100

環境変数

変数	デフォルト	説明
TRANSPORT	stdio	アクティブなトランスポート：stdio または http
PORT	3000	HTTP トランスポートのポート
MCP_HTTP_HOST	0.0.0.0	HTTP サーバーのバインド先ホスト。ローカルのみで使用する場合は 127.0.0.1 を指定します
EVOLITH_API_KEY	—	HTTP トランスポートの認証用 API キー
EVOLITH_MCP_ALLOW_NO_AUTH	false	HTTP のみ。 API キーなしで HTTP を起動できるようにします（本番環境以外のみ）。production 環境および stdio では無視されます（起動時に警告が表示されます）
JWT_SECRET	—	API キーに加えて、Bearer JWT（HS256）の検証に使用する省略可能なシークレット
NODE_ENV	development	production では HTTP 認証が必須です
LOG_LEVEL	info	Pino のログレベル：trace、debug、info、warn、error
REDIS_URL	—	リソースキャッシュ用の Redis URL（例：redis://localhost:6379）。キャッシュは省略可能です。
OTEL_EXPORTER_OTLP_ENDPOINT	—	トレース用の OpenTelemetry エンドポイント
OTEL_SERVICE_NAME	evolith-mcp	トレースで使用するサービス名
EVOLITH_MCP_REQUEST_STATE_SECRET	—	MRTR の requestState を保護するキー（2026-07-28 パス）。未設定の場合は EVOLITH_API_KEY、次に JWT_SECRET、それらも未設定の場合はプロセスごとのキーが使用されます。複数のレプリカを稼働させる場合は必ず明示的に設定してください。承認の再試行が別のレプリカに到達すると拒否されます
EVOLITH_MCP_RESOURCE_AUTH_SERVERS	—	Protected Resource Metadata ドキュメントに公開する、カンマ区切りの認可サーバー発行者。デフォルトは EVOLITH_MCP_OAUTH_ISSUER です
EVOLITH_MCP_RESOURCE_URI	リクエストのホスト	resource として公開する、このサーバーの正規 URI（RFC 8707 リソース識別子）
EVOLITH_MCP_RESOURCE_SCOPES	read write	scopes_supported として公開され、WWW-Authenticate で要求されるスコープ

バイナリでは、--transport／-t、--port／-p、--api-key、--allow-no-auth（HTTP のみ）の各フラグのほか、evolith-mcp version サブコマンドも使用できます。

---

認証

stdio トランスポート

リクエスト認証は不要です。プロセスはローカルで単一ユーザー向けであり、エージェントが直接起動するためです。トランスポートは明示的なローカルセッション主体（id=local-stdio-session、role=local-session、roles=[local-session, operator]、scopes=[read, write]）を確立し、すべての呼び出しの監査証跡に記録します（GT-572）。

これは認可のバイパスではありません。この ID を使ったすべての tools/call で、ABAC（ネイティブ＋OPA）は引き続き評価されます。deploy ツールは引き続き production で拒否されます（architect が必要です）。また、変更を伴うすべてのツールで、HITL ゲート { apply, approvalToken } が引き続き要求されます。--allow-no-auth／EVOLITH_MCP_ALLOW_NO_AUTH はstdio には適用されません（スキップするリクエスト認証が存在しないため）。これらを --transport stdio と併せて渡すと、サーバーは起動時に stderr へ警告を出力します。

HTTP トランスポート

本番環境（NODE_ENV=production）では、認証が必須です。validateAuth() は EVOLITH_MCP_ALLOW_NO_AUTH を無視し、有効な認証情報がないリクエストをすべて拒否します（401）。EVOLITH_API_KEY の値は任意のシークレット（どのような文字列でも可。プレフィックスは不要）で、値の一致によって比較されます。次の 2 つのヘッダーのいずれかで受け付けられます。

Authorization: Bearer <EVOLITH_API_KEY>
x-api-key: <EVOLITH_API_KEY>

/health は公開されており（死活監視プローブ）、認証情報は不要です。

OAuth 発行者が設定されている場合、/.well-known/oauth-protected-resource（およびパスに挿入された /.well-known/oauth-protected-resource/<path>）も公開されます。これは RFC 9728 のドキュメントであり、認証されていないクライアントが、どの認可サーバーにアクセスすべきかを確認するために読み取ります。そのため、取得しようとしている認証情報でこのドキュメントへのアクセスを制限すると、検出できなくなります。このドキュメントには MCP データは含まれず、発行者、リソース識別子、スコープ名のみが含まれます。保護されたリソースから返される 401 には、さらに WWW-Authenticate: Bearer resource_metadata="…", scope="…" チャレンジが含まれます。これは MCP クライアントが優先して使用すべき検出メカニズムです。発行者が設定されていない場合、このエンドポイントは authorization_servers が空のドキュメントを公開するのではなく、404 を返します。

クライアント登録がこのサーバーを経由することはありません。このサーバーはリソースサーバーであり、2026-07-28 の改訂では、クライアントは認可サーバーで Client ID Metadata Document（または事前登録）を通じて client_id を取得します。Dynamic Client Registration は非推奨であり、ここでは実装されていません。登録エンドポイントが導入された場合にビルドが失敗するよう、protected-resource-metadata.spec.ts が設定されています。

プロトコルのリビジョン

サーバーは、同じ HTTP エンドポイントで 2 つのプロトコルリビジョンに応答します。

リビジョン	リクエストでの選択方法	形式
2026-07-28（現行）	各リクエストの _meta["io.modelcontextprotocol/protocolVersion"]、または server/discover の呼び出し	ステートレスです。initialize、notifications/initialized、Mcp-Session-Id はありません。すべての結果に resultType が含まれます。承認ゲートは、封印された requestState（MRTR）を持つ InputRequiredResult で表現されます
2025-11-25	initialize リクエスト	@modelcontextprotocol/sdk が提供する、ハンドシェイクベースの経路です。この経路では Mcp-Session-Id が発行され、必須となります

どちらのリビジョンも同一のディスパッチを経由するため、ABAC（ネイティブと OPA）、スコープゲート、承認ゲート、監査ログは、どちらの経路でも同じコードが使われます。公開されている SDK が今もこのリビジョンを最新として宣言しているため、2025-11-25 の経路を維持しています。別の設計として用意されているわけではありません。

2026-07-28 の経路では、状態を変更するツールは elicitation/create リクエストと不透明な requestState を伴う resultType: "input_required" で応答します。クライアントは人間の承認を得て、元の呼び出しを再試行します。つまり、新しい JSON-RPC ID を使い、同じパラメーターに requestState と inputResponses を加えます。requestState は AES-256-GCM で封印され、プリンシパル、テナント、元の呼び出し、短い TTL に紐付けられているため、ユーザー、呼び出し、時刻をまたいで再利用することはできません。すでに承認を得ている呼び出し元は、{ apply: true, approvalToken } をインラインで渡して、往復処理を省略することもできます。これは 2025-11-25 の経路とまったく同じです。

以下の ApiKeyProvisioningService は、evk_ プレフィックス、SHA-256 ハッシュ、TTL を持つキーを発行するための高度なオプション機能です。ここで説明する、起動時の EVOLITH_API_KEY とは独立しています。

API キーのプロビジョニング

ApiKeyProvisioningService は、キーのライフサイクルを管理します。

操作	説明
generateKey(label, options)	evk_ プレフィックス、SHA-256 ハッシュ、設定可能な TTL（デフォルトは 90 日）を持つキーを生成します
validateKey(rawKey)	保存済みのハッシュと照合してキーを検証し、有効期限を確認します
rotateKey(keyId)	現在のキーを失効させ、同じクライアント用の新しいキーを生成します
revokeKey(keyId)	キーをただちに失効させます

キーには read、write、admin のスコープが付与されます。また、キーは tenant に紐付けられます。

ABAC モデル

AbacEvaluator は、各ユーザーが呼び出せるツールをロールに基づいて制御します。

ツールの種類	許可されるロール	環境
読み取り（list、get、status）	認証済みのすべてのロール	すべて
書き込み（fix、install、set）	operator、sre、architect、admin	すべて
書き込み	developer、qa	本番環境以外
デプロイ（deploy、publish、merge）	architect、admin、operator、sre	すべて
デプロイ	architect 以外のすべてのユーザー	本番環境ではブロック

ABAC コード：

コード	原因
ABAC-01	ユーザーのロール／環境ではツールが許可されない
ABAC-02	ロールを持たないユーザー — すべてのツールが拒否される
ABAC-03	ツールが既知のグループに分類されていない

ツールの分類（部分文字列によるヒューリスティック）。 内部のロールセットは DEVELOPER = {developer, qa}、OPERATOR = {operator, sre}、ARCHITECT = {architect, admin} です。各ツールの読み取り／書き込み／デプロイの分類は、ツール名に対するヒューリスティック（abac-evaluator.ts）で判定されます。名前に read／list／get が含まれる場合、または evolith- で始まらない場合は読み取りに分類されます。write／replace／run／fix／advance が含まれる場合は書き込みに、deploy／publish／merge が含まれる場合はデプロイに分類されます。このヒューリスティックにより、evolith-phase-advance は遷移を提案するだけのツールですが、advance の部分文字列があるため書き込みに分類されます。どのグループにも該当しないツールは ABAC-03 で拒否されます。

認証の優先順位（HTTP）。 ガード（mcp-server-auth.ts）は、まず API キーを評価します。Authorization: Bearer <token> または x-api-key ヘッダーが EVOLITH_API_KEY と一致すると、admin コンテキスト（ロール admin、すべてのツールが許可）を付与します。キーが一致せず、JWT_SECRET が定義されている場合に限り、Bearer を JWT HS256 として検証します。この場合、JWT ペイロードの roles が ABAC に渡されます。/health は公開されています。本番環境では認証が必須であり（EVOLITH_MCP_ALLOW_NO_AUTH は無視されます）。

---

利用可能なツール（55）

ツールは実行時に tools/list で取得します。いずれも生データを返し、Gateway が SuccessEnvelope または ErrorEnvelope でラップします。

件数は、生成された Product Surface Inventory の登録元（tools/*.ts、resources.service.ts、prompts.service.ts）から算出しています。以下の表には、エリアごとにグループ化したすべてのツールを記載しています。内容が一致しない場合は、tools/list とインベントリを優先してください。

検証

ツール	説明	変更を伴う
evolith-validate	Evolith のガバナンスルール（GOV、INH、ACL、OCB）に照らしてリポジトリを検証します	いいえ
evolith-composable-validate	複数のモードを組み合わせ可能な検証：SDLC、Architecture、Ruleset、ADR、Ad-hoc	いいえ

evolith-composable-validate スキーマ：

{
  "path": "string (required) — path to the satellite repository",
  "corePath": "string — path to the Evolith Core",
  "engine": "'native' | 'opa' — evaluation engine (default: native)",
  "topology": "'modular-monolith' | 'microservices' | 'serverless' | ... — enables Architecture mode",
  "phase": "'discovery' | 'design' | 'construction' | 'qa' | 'release' — enables SDLC mode (the schema also accepts the legacy aliases 'f1'..'f5', deprecated)",
  "ruleset": "string — enables Ruleset mode",
  "adr": "'adr-0002' | 'adr-0005' | 'adr-0010' | ... — enables ADR mode",
  "file": "string — enables Ad-hoc mode over a single file"
}

フィールドを組み合わせることでモードを有効にします。1 回の呼び出しで複数のモードを使用できます。

---

評価（ADR-0101）

ツール	説明	変更を伴う
evolith-evaluate	正規の EvaluationContext（ゲート、アーティファクト、ルール、コンプライアンス）を評価し、ADR-0073 のエンベロープ形式で EvaluationResult を返します。ステートレスです。製品、テナント、イニシアチブは不透明なコンテキストとして扱われます	いいえ
evolith-ruleset-list	この Core が評価できるルールセットパックを一覧表示します。evolith-validate の select で受け付ける正規の参照と、各パックのルール数を示します	いいえ

---

アーキテクチャ

ツール	説明	変更を伴う
evolith-architecture-validate	サテライトプロジェクトをアーキテクチャルールに照らして検証します	いいえ
evolith-drift-detect	宣言されたアーキテクチャと実際のアーキテクチャのずれを検出します	いいえ
evolith-topology-recommend	技術的なシグナルに基づいてトポロジー構成を推奨します（助言的、ADR-0104）：Core が推奨し、テナントが確定します	いいえ
evolith-phase-artifacts-evaluate	確定済みのトポロジー構成に対し、後続フェーズのアーティファクトの完全性を測定します（助言的、ADR-0104）	いいえ

---

パターン

ツール	説明	変更あり
evolith-pattern-list	正式なパターンとアンチパターン（PAT-NNNN）を一覧表示します。カテゴリ、種類、適用可能なトポロジーで絞り込むこともできます	いいえ
evolith-pattern-get	IDでパターンを1つ取得します。問題、影響要因、解決策、トポロジーごとの適用性、関連するADRが含まれます	いいえ
evolith-pattern-list-by-topology	トポロジーに適用されるパターンを、適用の強さ（必須 → 推奨 → 任意）と、それぞれが課すルールとともに一覧表示します	いいえ

---

トポロジー

ツール	説明	変更あり
evolith-topology-list	Evolith Coreで利用可能なすべてのアーキテクチャトポロジーを一覧表示します	いいえ
evolith-topology-get	IDでトポロジーの完全なマニフェストを取得します	いいえ

evolith-topology-list のスキーマ：

{
  "corePath": "string — path to the Core (optional, default: ../evolith)"
}

evolith-topology-get のスキーマ：

{
  "id": "string (required) — topology ID (e.g. modular-monolith)",
  "corePath": "string — path to the Core (optional)"
}

利用可能なトポロジー： modular-monolith、distributed-modules、microservices、serverless、edge-computing、event-driven、data-mesh、agentic-ai

---

SDLC ゲート

ツール	説明	変更あり
evolith-gate-evaluate	特定のSDLCフェーズゲートを評価します	いいえ
evolith-phase-advance	フェーズ移行を提案します	いいえ¹

¹ evolith-phase-advance は移行を提案するだけで、実行はしません。実行はオペレーターまたはTrackerが担当します。

---

SDLC

ツール	説明	変更あり
evolith-sdlc-status	リポジトリの現在のSDLCフェーズ状態を取得します	いいえ
evolith-sdlc-handoff	フェーズの引き継ぎを実行し、エビデンスマニフェストを生成します	はい
evolith-dora-metrics	Git履歴からDORAメトリクスを概算します。デプロイ頻度、リードタイム（概算）、期間（days、デフォルトは90日）内のコミット総数とマージコミット数が含まれます	いいえ
evolith-sdlc-generate	MarkdownのDDDモデルにあるMermaidのclassDiagramから、ヘキサゴナルアーキテクチャのスキャフォールドを生成します（sdlc generate と同等）	はい

---

MoSCoW

ツール	説明	変更あり
evolith-moscow-create	プロジェクトのフェーズ用にMoSCoWマトリクスを作成します	はい
evolith-moscow-load	既存のMoSCoWマトリクスを読み込みます	いいえ
evolith-moscow-update	MoSCoWマトリクスの項目を更新します	はい
evolith-moscow-remove	マトリクスから項目を削除します	はい
evolith-moscow-list	プロジェクトのMoSCoWマトリクスを一覧表示します	いいえ
evolith-moscow-validate	マトリクスの形式が正しいことを検証します	いいえ
evolith-moscow-report	MoSCoWの優先順位付けレポートを生成します	いいえ

² .evolith/moscow/{phase}.json に書き込む3つのMoSCoWツール（create、update、remove）は、2026-07-11以降 moscow.tools.ts で mutative: true を宣言しているため、ディスパッチャーはこれらに apply／approvalToken を要求します。load、list、validate、report は読み取り専用です。

---

ADR

ツール	説明	変更あり
evolith-adr-list	すべてのArchitecture Decision Record（ID、タイトル、ステータス、日付）を一覧表示します	いいえ
evolith-adr-get	ID（ADR-0001）または番号でADRの詳細を取得します	いいえ
evolith-adr-matrix	ADRマトリクスの概要（ステータス別の合計、最近のADR）を取得します	いいえ
evolith-adr-create	ADRを作成します。reference/architecture/adrs/<id>.md に書き込み、マトリクスを更新します	はい
evolith-adr-update	ADRのステータス（Proposed、Accepted、Deprecated、Superseded、Amended）を更新します	はい

---

エージェント

ツール	説明	変更あり
evolith-agent-install	リポジトリにEvolithエージェントをインストールします	はい
evolith-agent-list	インストール済みのエージェントを一覧表示します	いいえ
evolith-agent-validate	エージェントの設定を検証します	いいえ
evolith-agent-upgrade	エージェントをテンプレートの最新バージョンにアップグレードします	はい
evolith-agent-remove	リポジトリからエージェントを削除します	はい
evolith-agent-run	エージェントランタイムのパイプラインを通じてインテントを実行します	はい

---

サテライト

ツール	説明	変更
evolith-satellite-list	ローカルの satellite-registry.json に登録されているサテライトを一覧表示します	いいえ
evolith-satellite-status	ID を指定して、登録済みサテライトのステータスと詳細を取得します	いいえ
evolith-satellite-create	GitHub にサテライトリポジトリを作成して登録します（ADR-0073 エンベロープ）	はい
evolith-satellite-adopt	既存の GitHub リポジトリをサテライトとして採用します（ADR-0073 エンベロープ）	はい

---

スキャフォールディングと初期化

ツール	説明	変更
evolith-init-batch	サテライトを非対話形式（バッチ／CI）で初期化します。プロンプトなしで init --config <json> ／ init --yes と同等の処理を行います	はい
evolith-scaffold	段階的な成熟度軸に沿ってサテライトをスキャフォールディングします（フェーズ 1 モジュラーモノリス → 2 分散モジュール → 3 マイクロサービス）	はい
evolith-docs-scaffold	Evolith が必要とする基本ドキュメント（README.md、AGENTS.md、MASTER_INDEX.md、evolith.yaml）をスキャフォールディングします。docs コマンドと同じ処理です	はい
evolith-fixtures	デモとテスト用の再現可能なフィクスチャとサンプルデータ（evolith.yaml、ADR、ルールセット）を用意します	はい

---

アップグレード

ツール	説明	変更
evolith-upgrade-plan	上流の Core に対するサテライトのアップグレードを計画します（ドライラン）。変更計画、破壊的変更、推定リスクを提示し、書き込みは行いません	いいえ
evolith-upgrade-apply	上流の Core からサテライトのアップグレードを適用します。上流のみの変更を書き込み、ローカルのみの変更は一切書き込みません	はい

---

ナレッジ

ツール	説明	変更
evolith-knowledge-search	BM25 優先のハイブリッド検索を使用して、アーキテクチャナレッジコーパス（ADR、ルールセット、標準）を検索します。引用付きでチャンクを順位付けして表示します	いいえ

---

修正

ツール	説明	変更
evolith-auto-fix	検出された違反を自動修正します	はい

---

設定

ツール	説明	変更
evolith-config-get	evolith.yaml から設定値を取得します	いいえ
evolith-config-set	evolith.yaml の値を更新します	はい

---

可観測性

ツール	説明	変更
evolith-metrics	内部 MCP Gateway のメトリクス（呼び出し、レイテンシ、エラー）を返します	いいえ

CLI と同等の読み取り機能（GT-682）

MCP に対応する機能がなかった 3 つの CLI コマンドを、core-domain 内の CLI 独自のリーダーを使う読み取り専用ツールとして移植しました。書き込みモード（history --clear/--replay、profile create/switch/delete、standards --init/--validate/--export）は CLI で引き続き使用できます。

ツール	説明	変更
evolith-history	CLI のコマンド履歴（$HOME/.evolith/history.jsonl）を読み取ります：list、get、search、stats	いいえ
evolith-profile	CLI のプロファイルストアを読み取ります：current（アクティブなプロファイルとその値）または list	いいえ
evolith-standards	<path>/reference/standards にある標準を読み取ります：list（省略可能な category 指定）または get	いいえ

---

利用可能なリソース（12 ＋動的）

リソースは resources/list で取得し、resources/read で読み取ります。

静的リソース（resources/list）

URI	名前	説明
evolith://rulesets	ルールセット	Evolith Core のすべてのルールセットを一覧表示します
evolith://phase-gates	フェーズゲート	フェーズゲートの定義と要件
evolith://agents	エージェント	インストール済みの Evolith エージェントの一覧
evolith://core/info	Core 情報	Core の一般情報（バージョン、ルールセットの合計数、機能）
evolith://governance/version	ガバナンスのバージョン	ガバナンススキーマのバージョン
evolith://core/version	Core のバージョン	Core スキーマのバージョン
evolith://repository/config	リポジトリ設定	現在のリポジトリの evolith.yaml の内容
evolith://moscow/phase-0	MoSCoW フェーズ 0	検討フェーズの MoSCoW マトリクス
evolith://architecture/topologies	アーキテクチャトポロジー	利用可能なすべてのトポロジーの一覧
evolith://architecture/patterns	アーキテクチャパターン	適用可能性と適用ルールを含む、標準パターンとアンチパターン（PAT-NNNN）
evolith://capabilities	機能マニフェスト	評価エンジンのバージョン管理された機能マニフェスト（evaluationKinds、エンジン、サーフェス、supportedConsumers）
evolith://contracts	マシンコントラクト	Core が外部コンシューマー向けに公開する、機械可読なスキーマ／コントラクト一式

動的 URI（resources/read からアクセス可能）

URI パターン	説明
evolith://ruleset/{name}	名前を指定したルールセットの内容（例：evolith://ruleset/governance/base）
evolith://agent/{name}	インストール済みエージェントの定義（例：evolith://agent/winston）
evolith://architecture/topology/{id}	トポロジーのマニフェスト（例：evolith://architecture/topology/modular-monolith）
evolith://open-core/artifacts	Open-Core 境界（OCB）ルール
evolith://acl/rules	アンチコラプションレイヤールール
evolith://moscow/{phase}	任意のフェーズの MoSCoW 分析（例：evolith://moscow/phase-1）

---

利用可能なプロンプト（8 件）

プロンプトは prompts/list で取得し、prompts/get で呼び出します。

プロンプト	説明	引数
evolith/validate-repository	ガバナンスルールに照らしてリポジトリを検証します	path（必須）、ruleset（任意）
evolith/agent-onboarding	新しいエージェントをインストールして設定します	name（必須）、template（任意：standard/minimal/enterprise）
evolith/architecture-review	F1/F2/F3 アーキテクチャレビュー	path（必須）、level（任意：F1/F2/F3）
evolith/prepare-discovery	検討フェーズの成果物を準備します	path（必須）
evolith/phase-gate-check	フェーズゲートの準備状況を確認します	path（必須）
evolith/sdlc-handoff	SDLC フェーズの引き継ぎを実行します	path（必須）、fromPhase（必須）、toPhase（必須）
evolith/ruleset-analysis	ルールセットへの準拠状況を分析します	ruleset（必須）、path（任意）
evolith/moscow-prioritization	SDLC の MoSCoW マトリクスを作成します	path（必須）、phase（任意、デフォルト：phase-0）

---

変更を伴う操作

変更を伴う操作としてマークされたツール（mutative: true）は、誤った変更を防ぐため、明示的な承認を必要とします。ディスパッチャー（mcp-tool-dispatch.ts:137）は、リクエストに次の両方のフィールドが含まれていない場合、FORBIDDEN を返して呼び出しを拒否します。

{
  "name": "winston",
  "dir": "/path/to/repo",
  "apply": true,
  "approvalToken": "<non-empty-token>"
}

• apply は正確に true である必要があります。
• approvalToken は空でない文字列である必要があります。サーバーがこれを平文でログに記録することはありません。監査前に sha256:… のフィンガープリントに変換します。

approvalToken はプロトコルレベルでの承認コントラクトです。一部のツールスキーマでは引き続き confirm フィールドが宣言されており、ヘルパー関数 isMutationAllowed() も存在します（evolith.yaml から mcp.allowMutations を読み取ります）。しかし、handleCallTool で実際に実行を阻止するガードは apply + approvalToken です。confirm も mcp.allowMutations も、その代わりにはなりません。

変更を伴うツール

ツール	操作
evolith-agent-install	エージェントのファイルをリポジトリに書き込みます
evolith-agent-upgrade	エージェントの設定を上書きします
evolith-agent-remove	エージェントのディレクトリを削除します
evolith-agent-run	Agent Runtimeを通じてインテントを実行します（スキルによっては書き込みを行う場合があります）
evolith-config-set	evolith.yaml を変更します
evolith-sdlc-handoff	引き継ぎマニフェストを生成し、状態を書き込みます
evolith-sdlc-generate	DDDモデルからヘキサゴナル構造のスキャフォールドを書き込みます
evolith-auto-fix	コードに自動修正を適用します
evolith-adr-create / evolith-adr-update	ADRファイルとADRマトリクスを書き込みます
evolith-moscow-create / evolith-moscow-update / evolith-moscow-remove	.evolith/moscow/{phase}.json を書き込みます
evolith-satellite-create / evolith-satellite-adopt	GitHubリポジトリを作成またはリンクし、ローカルのサテライトレジストリを書き込みます
evolith-init-batch / evolith-scaffold / evolith-docs-scaffold / evolith-fixtures	サテライトのファイル、ドキュメントベース、またはフィクスチャを書き込みます
evolith-upgrade-apply	上流の変更をサテライトに書き込みます

コードで mutative: true が宣言されているツールはちょうど20個です（2026-09-20時点。残りの35個は読み取り専用です）。ディスパッチャーが設計上保護するのはこのツール群です。ツールが保護されるのは変更を伴うためであり、ここに列挙されているためではありません。evolith-upgrade-plan と evolith-phase-advance は意図的に読み取り専用です。計算と提案を行いますが、書き込みは行いません。

---

内部アーキテクチャ

GatewayはNestJSアプリケーションです（モジュール＋依存性注入）。

@beyondnet/evolith-mcp/
├── src/
│   ├── main.ts                         ← Bootstrap, parseArgs, stdio/HTTP startup
│   ├── app.module.ts                   ← Root module
│   ├── common/
│   │   ├── errors.ts                   ← ErrorCodes + DomainException
│   │   ├── envelopes.ts                ← SuccessEnvelope / ErrorEnvelope + correlationId
│   │   └── stderr-logger.ts            ← LoggerService over Pino → stderr
│   ├── mcp/
│   │   ├── mcp.module.ts
│   │   ├── tool.interface.ts           ← McpTool interface + MCP_TOOLS token
│   │   ├── tool-registry.service.ts    ← dynamic tool registry
│   │   ├── mcp-server.service.ts       ← MCP SDK Server + dispatch + transports
│   │   ├── mcp-tool-dispatch.ts        ← dispatch with ABAC + audit + mutative guard
│   │   ├── mcp-server-auth.ts          ← HTTP authentication (EVOLITH_API_KEY)
│   │   ├── abac-evaluator.ts           ← native ABAC evaluator + OPA
│   │   ├── api-key-provisioning.service.ts  ← API key lifecycle
│   │   ├── audit-logger.ts             ← structured log of every tool call
│   │   ├── mcp-cache.service.ts        ← resource cache in Redis
│   │   ├── metrics.service.ts          ← internal Gateway metrics
│   │   ├── prompts.service.ts          ← serves prompts/list and prompts/get
│   │   └── resources.service.ts        ← serves resources/list and resources/read
│   ├── tools/
│   │   ├── tools.module.ts             ← registers every tool
│   │   ├── validate.tool.ts            ← evolith-validate
│   │   ├── composable-validate.tool.ts ← evolith-composable-validate (GT-312)
│   │   ├── architecture.tools.ts       ← evolith-architecture-validate, drift-detect
│   │   ├── topology.tools.ts           ← evolith-topology-list, topology-get
│   │   ├── gate.tools.ts               ← evolith-gate-evaluate
│   │   ├── phase-advance.tools.ts      ← evolith-phase-advance
│   │   ├── sdlc.tools.ts               ← sdlc-status, sdlc-handoff, dora-metrics
│   │   ├── moscow.tools.ts             ← moscow-create/load/update/remove/list/validate/report
│   │   ├── agent.tools.ts              ← agent-install/list/validate/upgrade/remove
│   │   ├── auto-fix.tools.ts           ← evolith-auto-fix
│   │   ├── config.tools.ts             ← config-get, config-set
│   │   └── metrics.tool.ts             ← evolith-metrics
│   ├── resources/
│   │   └── corpus-resource.handler.ts  ← handler for documentary corpus resources
│   ├── watcher/
│   │   └── watcher.service.ts          ← watches workspace files for changes
│   └── domain/
│       └── domain.module.ts            ← wires @beyondnet/evolith-core to @beyondnet/evolith-infra-providers

@beyondnet/evolith-core               ← business logic (use-cases, validators, types)
@beyondnet/evolith-infra-providers    ← adapters (NodeFileSystem, YamlConfigParser, DiskRulesetRepository)

WatcherService

WatcherService は、Gatewayの実行中にユーザーが設定を編集した場合にキャッシュを無効化したり、再検証をトリガーしたりできるよう、ワークスペース内のファイル（例：evolith.yaml）を監視します。長時間稼働するstdioトランスポートでは自動的に有効になります。

CorpusResourceHandler

ドキュメントコーパスのリソース（ADR、プレイブック、仕様書）へのアクセスを処理します。これにより、エージェントは変更を伴うツールを呼び出すことなく、構造化されたアーキテクチャコンテキストを読み取れます。

---

エージェントのユースケース

1. Claude Desktopからリポジトリを検証する

// prompts/get
{
  "name": "evolith/validate-repository",
  "arguments": { "path": "/Users/me/my-service" }
}

このプロンプトは、エージェントに evolith-validate を使って、ブロッキングとなる違反を報告するよう指示します。

2. Cursorからエージェントをオンボーディングする

// prompts/get
{
  "name": "evolith/agent-onboarding",
  "arguments": { "name": "guardian", "template": "enterprise" }
}

エージェントは evolith-agent-install を実行し、続けて evolith-agent-validate を実行します。

3. アーキテクチャを自動レビューする

// tools/call
{
  "name": "evolith-composable-validate",
  "arguments": {
    "path": "/repo",
    "topology": "modular-monolith",
    "phase": "design",
    "engine": "native"
  }
}

SDLC検証とアーキテクチャ検証を1回の呼び出しにまとめます。

4. MoSCoWとゲートチェックを組み合わせたSDLCサイクル全体

1. tools/call evolith-sdlc-status     → current state of the phase
2. tools/call evolith-moscow-create   → create the prioritization matrix
3. tools/call evolith-gate-evaluate   → evaluate the gate of the current phase
4. tools/call evolith-sdlc-handoff    → generate the handoff manifest
5. tools/call evolith-phase-advance   → propose moving on to the next phase

5. 検証前にトポロジーを照会する

// tools/call
{ "name": "evolith-topology-list" }
// → list of available topologies

{ "name": "evolith-topology-get", "arguments": { "id": "agentic-ai" } }
// → full manifest with rules and requirements

---

クライアントの設定

Cursor（~/.cursor/config.json）

{
  "mcpServers": {
    "evolith": {
      "command": "evolith-mcp",
      "args": ["serve"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "evolith": {
      "command": "evolith-mcp",
      "args": ["serve"]
    }
  }
}

カスタムエージェント（HTTPトランスポート）

# Start the HTTP server
EVOLITH_API_KEY=evk_abc123 evolith-mcp serve --transport http --port 49100

# Call it from the agent
curl -X POST http://localhost:49100/mcp \
  -H "Authorization: Bearer evk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"evolith-validate","arguments":{"path":"/repo"}},"id":1}'

---

SmartCLIとの統合

evolith-cli mcp からの移行計画

フェーズ1 — 共存（現在）： evolith-cli mcp は引き続き動作します。evolith-mcp serve が新しいエントリーポイントです。

フェーズ2 — 非推奨化： evolith-cli mcp は console.warn を出力するようになります。Cursor／Claude Desktopの設定を evolith-mcp に移行してください。

フェーズ3 — 削除： メジャーバージョンの更新で、@beyondnet/evolith-cli からMCPコードを削除します。CLIの検証コマンドは引き続き使用できます。

動作上の違い

項目	evolith-cli mcp（レガシー）	evolith-mcp（新規）
トランスポート	stdioのみ	stdio + Streamable HTTP
認証	認証なし	HTTP経由のABAC + APIキー
キャッシュ	キャッシュなし	Redis（オプション）
可観測性	基本的なログ	Pino + OTEL + 監査ロガー
ツール	一部	55個すべてのツール

拡張ガイド

新しいツールを追加するには：

1. McpTool を実装した src/tools/my-tool.tool.ts を作成します（schema、execute。状態を変更する場合は readonly mutative = true を追加します）。
2. 必要なドメインサービスを（@beyondnet/evolith-core から）注入します。
3. 生データを返します。McpServerService が自動的に SuccessEnvelope でラップし、エラーを ErrorEnvelope に格納します。
4. tools.module.ts にツールを登録します。プロバイダーを追加し、MCP_TOOLS ファクトリーに含めます。

import { Injectable } from "@nestjs/common";
import { McpTool, McpToolSchema } from "../mcp/tool.interface";

@Injectable()
export class MyTool implements McpTool {
  readonly schema: McpToolSchema = {
    name: "evolith-my-tool",
    description: "Description of what it does",
    inputSchema: {
      type: "object",
      properties: { param1: { type: "string", description: "..." } },
      required: ["param1"],
    },
  };

  async execute(args: Record<string, unknown>): Promise<unknown> {
    if (!args.param1) throw new Error("param1 is required");
    return { ok: true };
  }
}

状態を変更するツールには、readonly mutative = true を追加します。そうするとディスパッチャーは、ツールを実行する前に、リクエストに { "apply": true, "approvalToken": "..." } が含まれていることを要求します。

---

可観測性

Pino ログ → stderr

すべてのログは stderr に出力されます（stdout には出力されません）。構造化された JSON 形式で、correlationId、tool、duration、success を含みます。

# Follow the logs live (stdio)
evolith-mcp serve 2>&1 | grep '"level"'

evolith-metrics ツール

Gateway の内部メトリクスを返します。

{
  "uptimeMs": 1820345,
  "totalCalls": 142,
  "totalFailures": 4,
  "tools": {
    "evolith-validate": { "calls": 80, "failures": 1, "totalLatencyMs": 1440, "avgLatencyMs": 18 },
    "evolith-gate-evaluate": { "calls": 32, "failures": 0, "totalLatencyMs": 992, "avgLatencyMs": 31 }
  },
  "recentErrors": ["RULESET_NOT_FOUND: ..."]
}

OpenTelemetry

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_SERVICE_NAME=evolith-mcp \
evolith-mcp serve

監査ロガー

すべてのツール呼び出しは、toolName、userId、tenant、environment、allowed（ABAC）、durationMs、correlationId とともに記録されます。記録は JSON 形式で stderr に出力されます。

---

推奨事項

• エージェントのワークフローの入口としてプロンプトを使用してください。ツールを実行する順序をエージェントが推論する必要がなくなります。
• 同等の読み取り専用ツールで事前に検証せずに、状態を変更する呼び出しをまとめて承認しないでください。
• 変更の実際の範囲を把握できるよう、evolith-auto-fix の前に evolith-validate を実行してください。
• 本番環境の HTTP では、API キーを 90 日ごとにローテーションし、必要最小限のスコープに制限してください。
• 長期間稼働するインストールでは、resources/read でファイルシステムを繰り返し読み取らないよう、Redis の使用を推奨しますが、必須ではありません。
• 複数のモードが必要な場合は、個別に呼び出す代わりに evolith-composable-validate を使用してください。レイテンシーを抑え、結果を関連付けられます。

---

トラブルシューティング

stdio：ログが MCP のレスポンスに混在して表示される

ログは stderr に出力されます。クライアントが stdout と stderr を統合している場合は、ストリームを分けてください。

evolith-mcp serve 2>/tmp/mcp.log

stdio：Refusing to start the MCP stdio transport（GT-572）

NODE_ENV=production では、stdio トランスポートは local-session プリンシパルを暗黙的に受け取りません。他の本番環境向けサーフェスと同じ、設定済みの認証情報を要求します。認証情報がない場合、サーバーは起動しません。起動時に stderr へエラーを出力して終了コード 78（EX_CONFIG）で終了し、すべてのツールを公開した後にすべての tools/call を FORBIDDEN で拒否することはありません。

対処方法（いずれか 1 つ）：

export EVOLITH_API_KEY=<key>                                  # container: -e EVOLITH_API_KEY=<key>
evolith-mcp serve --transport stdio --api-key <key>
NODE_ENV=development evolith-mcp serve --transport stdio      # local development session

--allow-no-auth / EVOLITH_MCP_ALLOW_NO_AUTH は開発用の HTTP 専用スイッチであり、本番環境の認証情報の代わりには意図的に使用できません。

HTTP：401 Unauthorized

サーバーで EVOLITH_API_KEY が設定されていることと、リクエストで Authorization: Bearer <key> または x-api-key: <key> に同じ値を送信していることを確認してください。値は完全一致で比較されます（evk_ プレフィックスは不要です）。NODE_ENV=production では、EVOLITH_MCP_ALLOW_NO_AUTH=true の場合でも認証が必須です。

ツールが見つからない（Tool not found in registry）

ツールが tools.module.ts に登録されていない可能性があります。プロバイダーが追加されていることと、schema.name の名前が呼び出し時の名前と完全に一致することを確認してください。

ABAC-02: No roles present

ユーザーコンテキスト（mcp-user-context）にロールがありません。HTTP トランスポートでは、JWT またはユーザーコンテキストにロールクレームが正しく含まれていることを確認してください。

Redis を利用できない

キャッシュは適切に縮退動作します。リソースはキャッシュなしでファイルシステムから直接提供され、ログに警告が出力されます。

OPA：policy.wasm not found

OPA 評価器は、CORE_PATH 配下の sdk/cli/rulesets/opa/policy.wasm を必要とします。ポリシーがない場合の動作は、フェイルオープンではなくフェイルクローズ（GT-348/349）です。ファイルが存在せず、NODE_ENV === "production" の場合、評価器は allowed: false と ABAC_POLICY_MISSING 違反を返します（ハード拒否）。OPA 評価器が判定を保留し、ネイティブポリシーに判断を委ねるために allowed: true を返すのは、非本番環境の場合のみです。OPA エンジン内でエラーが発生した場合は、常に拒否されます。ネイティブ評価を強制するには、engine: "opa" を指定しないでください。

---

ライセンス

ISC — Beyondnet