adrkit decision memory

@adrkit/mcp

コーディングエージェントのための、決定論的でオフラインの読み取り専用の意思決定メモリです。チームがすでに却下した決定も含まれます。

エージェントのハーネスが、Git で管理された 1 つの ADR（アーキテクチャ決定記録）コーパスを stdio 経由で検索できる、ローカルのモデルコンテキストプロトコルサーバーです。「これは決定済みですか？」「これらのファイルには何が適用されますか？」「これは何に置き換えられましたか？」といった質問に答えます。廃止された決定や却下された決定も明示的に提示するため、エージェントがチームですでに却下された方法を再提案するのを防ぎます。

モデル呼び出しなし。ネットワーク呼び出しなし。書き込みなし。 このサーバーはリポジトリ内の Markdown ファイルを読み取り、構造化 JSON を返します。LLM を呼び出さず、ソケットを開かず、コーパスを変更することもありません。すべてのツールには readOnlyHint: true と openWorldHint: false が注釈されています。

adrkitの一部です。コーパスは、型付き YAML フロントマターを持つ決定ごとの Markdown ファイルとして Git に保存されています（@adrkit/core）。このサーバーは読み取りのみを行います。公式 MCP レジストリには dev.adrkit/mcp として登録されています（これは Node/npm の @adrkit/mcp パッケージであり、PyPI の adr-kit Python パッケージとは無関係です）。

ステータス

npm で Node 22 以降向けに公開されています。意図的に小規模な読み取り専用の stdio インターフェイスを備え、ツールは 4 つで、書き込み経路はありません。

adrkit はまだプレ 1.0 です。クライアントへのインストールを再現可能にする必要がある場合は、latest を指定するのではなく、MCP 設定で @adrkit/mcp のバージョンを明示的に固定してください。

クイックスタート

公開済みのバイナリは adrkit-mcp です。npx を使って実行します（インストール不要）。

npx -y @adrkit/mcp --cwd /path/to/your/repo --dir docs/adr

stdio 経由で JSON-RPC を使用するため、通常は手動で実行するのではなく、MCP クライアントから接続します。以下にコピーして貼り付けられるクライアント設定を示します。

Claude Desktop

claude_desktop_config.json を編集します（macOS の場合： ~/Library/Application Support/Claude/claude_desktop_config.json）。Claude は任意の作業ディレクトリからサーバーを起動するため、ADRKIT_MCP_CWD にリポジトリの絶対パスを設定してください。

{
  "mcpServers": {
    "adrkit": {
      "command": "npx",
      "args": ["-y", "@adrkit/mcp"],
      "env": {
        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
        "ADRKIT_MCP_DIR": "docs/adr"
      }
    }
  }
}

VS Code

ワークスペース内に .vscode/mcp.json を作成します（VS Code は servers キーを使用し、${workspaceFolder} を置換します）。

{
  "servers": {
    "adrkit": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@adrkit/mcp", "--cwd", "${workspaceFolder}", "--dir", "docs/adr"]
    }
  }
}

Cursor

.cursor/mcp.json（プロジェクト単位）または ~/.cursor/mcp.json（グローバル）を作成します。

{
  "mcpServers": {
    "adrkit": {
      "command": "npx",
      "args": ["-y", "@adrkit/mcp"],
      "env": {
        "ADRKIT_MCP_CWD": "/absolute/path/to/your/repo",
        "ADRKIT_MCP_DIR": "docs/adr"
      }
    }
  }
}

GitHub Copilot CLI

~/.copilot/mcp-config.json（ユーザーレベル）または ./.copilot/mcp-config.json（リポジトリ単位）に追加します。Copilot CLI は信頼済みのリポジトリディレクトリからサーバーを実行するため、通常はデフォルトの cwd が正しく解決されます。

{
  "mcpServers": {
    "adrkit": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@adrkit/mcp", "--dir", "docs/adr"],
      "tools": ["*"]
    }
  }
}

copilot セッション内で /mcp add を使って、対話形式で追加することもできます。

設定リファレンス

オプション	環境変数	デフォルト	説明
--cwd <path>	ADRKIT_MCP_CWD	process.cwd()	リポジトリのルートです。読み取り可能な .git エントリを含むディレクトリに正規化できる必要があります（通常のクローン、またはリンクされたワークツリーの .git ファイル）。
--dir <path>	ADRKIT_MCP_DIR	docs/adr	ADR ディレクトリです。--cwd を基準に解決され、--cwd の配下に収まる必要があります（realpath で検証するため、シンボリックリンクによる範囲外への逸脱は拒否されます）。

フラグは環境変数より優先され、環境変数はデフォルトより優先されます。使用できない設定の場合、診断メッセージを stderr に出力して、ゼロ以外の終了コードで終了します（解析できないフラグの場合は 2、無効なルート／ディレクトリの場合は 1）。トランスポートは起動しません。stdout は JSON-RPC プロトコルフレーム専用です。

プロトコル改訂

サーバーは同じ stdio 接続上で、MCP プロトコルの両方の世代に対応しており、 クライアントがどちらを使うか選択します。最初のやり取りで世代が選択され、 接続が続く間はその世代に固定されます。

クライアントが最初に送るもの	サーバーが提供するもの
server/discover、または 2026 _meta エンベロープを含む任意のリクエスト	2026-07-28 — ステートレス、ハンドシェイクなし
initialize / notifications/initialized	ネゴシエートされた 2025 年代のリビジョン

2026-07-28 には initialize ハンドシェイクもセッション ID もありません。各 リクエストは独自のプロトコルバージョンとクライアントの機能を _meta に含み、 各結果は自己記述型です（resultType と、_meta 内のサーバー ID）。tools/list と server/discover はキャッシュ可能（SEP-2549）であり、4 つのツールからなる インターフェースはプロセスの実行中に固定され、コーパスの内容を含まないため、 ttlMs: 300000, cacheScope: "public" を指定して提供されます。コーパスの読み取りは キャッシュできません。すべての tools/call で新しい射影が読み込まれます。

世代間でツールに変更はありません。同じ名前、同じスキーマ、同じアノテーション、 同じ構造化結果です。サーバーは 2026-07-28 リビジョンで非推奨になった機能 （roots、sampling、logging）も、削除された機能（sessions、ping、 resources/subscribe）も使用しません。

4 つのツール

ツールは正確に 4 つで、すべて読み取り専用です。各ツールは固定のアノテーション （readOnlyHint: true、destructiveHint: false、idempotentHint: true、 openWorldHint: false）を共有し、content[0].text に決定的な、人が読める要約行を 返し、コーパス独自の解析／検証結果を含む findings ページを持ちます。内容を持つ すべてのレスポンスには、兄弟フィールドとして corpusHealth も含まれます： { fingerprint, recordCount, excludedCount }。

以下の形状は実際の入出力契約です（ packages/mcp/src/tools を参照）。各ツールの構造化出力は { corpusHealth?, result } です。「output」の下に 示すオブジェクトは、判別可能な result ユニオンのメンバーです（outcome をキーと します）。findings と増加するすべての配列はカーソルでページネーションされます （ページネーションを参照）。簡潔にするため、 findings と繰り返し現れるページネーション用フィールドはここでは省略しています。

search_decisions

id、title、tags、body に対する正規化されたリテラル部分文字列検索です （デフォルトで、置き換えられた／却下されたレコードの墓場も含みます）。フィルターは AND で結合されます。status／scope はいずれかに一致し、tags はすべてに一致します。

// input
{
  "query": "postgres",          // required, 1–256 code units, non-empty after trim
  "status": ["accepted"],        // optional, ≤6, any-of
  "tags": ["database"],          // optional, ≤32 tags × ≤64 chars, all-of
  "scope": ["backend"]           // optional, ≤3, any-of
}
// output → single "results" branch (empty results use the same branch)
{
  "outcome": "results",
  "items": [
    {
      "id": "0007",
      "title": "Adopt Postgres",
      "status": "accepted",
      "sourcePath": "docs/adr/0007-adopt-postgres.md",
      "matchedFields": ["title", "body"]   // subset of id | title | tag | body
    }
  ],
  "cursor": null
}

get_decision

1 件の ref に対する、型付けされた完全な frontmatter と本文です。

// input
{ "ref": "0007" }               // AdrRef, 1–128 chars (local id, or a "log:id" federated ref)
// output → discriminated on "outcome"
// found (the full record is nested under "decision"):
{
  "outcome": "found",
  "decision": {
    "requestedRef": "0007",
    "id": "0007",
    "title": "Adopt Postgres",
    "status": "accepted",
    "sourcePath": "docs/adr/0007-adopt-postgres.md",
    "frontmatter": { /* typed YAML: status, tags, affects, relations, ... */ },
    "body": "## Context\n..."
  }
}
// other outcomes:
// { "outcome": "not-found", "requestedRef": "9999" }
// { "outcome": "ambiguous-local-id", "requestedRef": "0007", "candidates": [ /* DecisionSummary[] */ ] }
// { "outcome": "federated-log-unavailable", "requestedRef": "core:12", "log": "core", "id": "12" }

log:id のフェデレーション ref は認識されますが、解決も置換もされません。 このサーバーが読み取るローカルコーパスは 1 つだけです。

get_decision_context

各レコード独自の affects マッチャーを使って、リポジトリ相対の files[] に対する 支配的な決定／有効な提案／過去の決定を返します。パスはパターンとの照合にのみ 使用され、開かれることはありません。

// input
{
  "files": ["src/db/pool.ts", "src/db/schema.sql"]
  // 1–256 entries; each POSIX, 1–1024 chars; no leading "/", no "..", no drive, no "\"
}
// output → single "matches" branch (all three arrays; empty is the same branch)
{
  "outcome": "matches",
  "governing": [
    {
      "id": "0007",
      "title": "Adopt Postgres",
      "status": "accepted",
      "sourcePath": "docs/adr/0007-adopt-postgres.md",
      "firedMatchers": [ { "type": "path", "pattern": "src/db/**" } ],
      "relations": { "supersedes": [], "supersededBy": null, "relatesTo": [], "conflictsWith": [] }
    }
  ],
  "activeProposals": [],
  "history": []
}

list_superseded

置き換えられたすべてのレコードと、その直接のローカルな置換状態を返します。 却下された方針をエージェントが再提案するのを防ぐツールです。

// input (pagination only)
{}
// output → single "entries" branch
{
  "outcome": "entries",
  "items": [
    {
      "id": "0003",
      "title": "Use MySQL",
      "status": "superseded",
      "sourcePath": "docs/adr/0003-use-mysql.md",
      "supersededBy": {            // one of four states:
        "resolved": true,
        "target": { "id": "0007", "title": "Adopt Postgres", "status": "accepted", "sourcePath": "docs/adr/0007-adopt-postgres.md" }
      }
      // unresolved states:
      //   { "resolved": false, "targetRef": "0099", "reason": "dangling" }
      //   { "resolved": false, "targetRef": "0007", "reason": "ambiguous", "candidateCount": 2 }
      //   { "resolved": false, "targetRef": "core:1", "reason": "federated-unavailable", "log": "core", "id": "1" }
    }
  ],
  "cursor": null
}

関連 ref（supersedes、supersededBy、relatesTo、conflictsWith）はそのまま表示され、 展開されることはありません。2 回目の get_decision 呼び出しでたどってください。 置き換え関係は 1 ホップ先まで報告され、推移的な探索は行われません。

ライブラリの公開インターフェース

パッケージのルートがエクスポートするのは、シールされたライフサイクルファクトリーだけです。基盤となる SDK サーバー、その登録内容、トランスポートにアクセスする方法はありません：

import { createAdrkitMcpServer } from '@adrkit/mcp';

const server = createAdrkitMcpServer({ cwd: process.cwd(), dir: 'docs/adr' });
await server.start();   // validates the root, then serves one stdio connection
// ... later:
await server.close();

createAdrkitMcpServer(options?) は構築時にファイルシステムへアクセスせず、start() と close() のみを持つ、凍結された null プロトタイプのハンドルを返します。

トランスポートの起動失敗や、終了したクライアントによる EPIPE などのバックグラウンドストリームエラーは、省略可能な onError オプションを通じて報告されます。デフォルトでは、標準エラーに診断メッセージが出力されます。adrkit-mcp バイナリはさらに、ゼロ以外の終了コードで終了します。標準出力には何も書き込まれません。標準出力はプロトコルフレーム用に確保されています。

MCP の stdio バインディングで定められているとおり、標準入力を閉じることがシャットダウンのシグナルになります。adrkit-mcp バイナリは、標準エラーに何も出力せずに終了コード 0 で終了します。標準入力が閉じられたときに処理中のリクエストは中断され、応答されません。そのため、クライアント（またはリクエストをパイプで渡すスクリプト）は、必要なすべての応答を読み取るまで標準入力を開いたままにしておく必要があります。

制限

query は1～256コードユニット（トリミング後に空でないこと）、ref は1～128、files[] は1～1024個のPOSIX文字のみで構成される項目を1～256件（先頭の /、..、ドライブレター、バックスラッシュは不可）、status は最大6件、scope は最大3件、tags は最大32件（各64文字以下）です。結果と指摘事項のページはデフォルト20件、最大100件です。ADRのレコードごとのソース上限は64 KiBです（サイズ超過のレコードは除外され、切り詰められることなく record-too-large の指摘事項として示されます）。すべての入力オブジェクトは厳密に検証されます。不明なフィールドは、コーパスにアクセスする前に拒否されます。

ページネーションとカーソルの再開

増加し続ける各チャネルは cursor を返します（最終ページでは null）。カーソルは不透明でバージョン管理され、コーパスのフィンガープリントと呼び出しのクエリ形状の両方に紐付けられています。返されたカーソルは、コーパスが変更されていない状態で、同一のリクエストパラメーターを使用する場合に限り再利用してください。それ以外の場合、エラーではない invalid-cursor の結果（corpus-changed、query-mismatch、wrong-channel、offset-out-of-range、cursor-not-applicable、version-unsupported、decode-failed）が返されるため、カーソルを指定せずにページ取得を最初からやり直してください。主結果チャネルと findings チャネルは、それぞれ独立してページ分割されます。ADR ディレクトリを読み取れない場合は、corpus-unavailable の結果が返されます。

境界（設計上、対象外）

5つ目のツールはありません。書き込み、提案、PR作成はできません。MCP のプロンプト、リソース、サブスクリプション、サンプリングには対応していません。HTTP/SSE トランスポートや認証には対応していません。モデル、埋め込み、ランキング、ネットワークにはアクセスしません。永続キャッシュ、インデックス、データベースはありません。名前付きログのフェデレーションや複数リポジトリの集約には対応していません。推移的な supersession の走査は行いません。

ツールチェーン

Bun を使用して開発・テストしています。公開成果物は Node.js >=22 を対象とする ESM で、Node 22 および24で検証されています。ランタイム依存関係は @adrkit/core、@modelcontextprotocol/server（MCP TypeScript SDK v2）、zod のみです。

Apache-2.0。