Agent Core

agent-core-mcp

AI エージェントのための決定論的な計算ツールです。 正確な差分比較、ハッシュ計算、JSON クエリ、カレンダー計算、厳格な実行期限付きの正規表現抽出、CSV 解析、類似度スコアリング、単位／基数変換を MCP サーバーとして提供します。

依存関係ゼロ。ネットワーク接続なし。読み取り専用。

---

なぜこれが必要なのか

言語モデルは文章の生成には優れていますが、正確で再現性のある機械的な計算は苦手です。これは能力の不足ではなく、アーキテクチャ上の特性です。確率的なシステムにカウント、差分比較、ハッシュ計算、カレンダー計算を求めれば、一定の割合で自信満々に間違った回答が返ってくることは避けられません。

このサーバーは、そうした処理をモデルの外に移し、決定論的なエンジンで実行します。

得られるのは、より良い推測ではありません。正確で再現可能な、まったく異なる種類の回答です。

MCP エコシステムに特有の理由もあります。公開されているサーバーで最も多く報告される問題は、認証情報の流出、未開示のシェル実行、既知の CVE を含む依存関係ツリー、クライアントがハングするサーバーです。ネットワーク接続も、認証情報も、実行機能もなく、すべての処理に期限を設けたサーバーであれば、これらの問題はどれも発生しません。

保証

保証	意味
依存関係ゼロ	node_modules はありません。監査対象も、古くなるものも、壊れるものもありません。
ネットワークアクセスなし	外部への通信は一切行いません。リクエストは一度も送信しません。
認証情報なし	トークン、API キー、環境変数を読み取りません。
読み取り専用	ファイルへの書き込み、シェル実行、状態の保持はありません。呼び出しごとにステートレスです。
決定論的	同一の入力に対して、バイト単位で同一の出力を返します。
上限付き	すべてのループと結果セットに上限があります。正規表現の実行はワーカースレッドで行い、期限が来ると終了するため、パターンによってクライアントがハングすることはありません。

サーバーは、機械可読な contract リソース（agent-core://contract）としてこれらを公開します。これにより、クライアントはこのファイルを信頼するのではなく、インストールするものを検証できます。

インストール

npx agent-core-mcp

実行にインストール手順は必要ありません。Node.js 18 以降が必要です。

入手先：

• npm — agent-core-mcp
• 公式 MCP レジストリ — io.github.kinbinghua-lgtm/agent-core-mcp
• ソース — github.com/kinbinghua-lgtm/agent-core-mcp

設定

Claude Code

このリポジトリには .mcp.json が含まれているため、クローンするだけで使えます。

git clone https://github.com/kinbinghua-lgtm/agent-core-mcp
cd agent-core-mcp
claude   # the agent-core server is discovered automatically

または、任意のプロジェクトに追加します。

{
  "mcpServers": {
    "agent-core": {
      "command": "npx",
      "args": ["-y", "agent-core-mcp"]
    }
  }
}

Claude Desktop、Cursor、VS Code、Windsurf、Continue、Zed

同じ設定ブロックを、そのクライアントの MCP 設定ファイルに記述します。API キーも環境変数も不要です。登録も必要ありません。

ツール

ツール	機能	モデル自身が実行すべきでない理由
diff_text	行番号と追加・削除数を含む、正確な行単位の差分（LCS）	正確な系列の整列が必要です。処理が停止しなくなるのを避けるため、サイズの大きすぎる入力は拒否します
hash	sha256 / sha512 / sha1 / md5 / HMAC、16 進数 + base64 + UTF-8 バイト長	確認だけで計算することはできません
json_validate	有効性に加え、パーサーのメッセージと計算された行・列	目視でエラー箇所を特定すると間違いやすいためです
json_query	a.b[0].c のようなパスアクセス。「存在しない」と「存在するが null」を区別します	これらを混同すると、実際のバグが気付かれないまま発生します
json_pick	1 回の呼び出しで複数のパスを解決します	N 回の往復より効率的です
text_stats	コードポイント、UTF-8 バイト数、行数、単語数、文数、段落数、ユニークな単語数、頻出単語	確率的な生成が特に間違えやすいのがカウントです
date_calc	日／週／月／年／時間／分／秒／営業日単位の期間	30 日単位で近似せず、実際の暦月を扱います
date_add	暦に基づいて日付を加算します	月末やうるう年を正しく処理します
regex_extract	インデックス、番号付き・名前付きキャプチャグループを含むすべてのマッチを、厳格な制限時間内で抽出します	悪意のあるパターンは停止せずに実行され続けるのではなく、終了させられます
regex_analyze	パターンの ReDoS リスクを静的に評価します	入れ子の量指定子、重複する選択肢、後方参照を検出します
fuzzy_match	Sorensen-Dice 類似度で候補を順位付けします	感覚ではなく、決定論的なスコアを使います
similarity	単一の類似度スコア（0～1）	—
parse_table	引用符、エスケープ、改行を含む RFC 4180 CSV/TSV。区切り文字を自動検出します	単純なカンマ分割では、実際の CSV を正しく処理できません
convert	長さ、質量、時間、データサイズを変換します。異なる種類間の変換は拒否します	単位の誤りは気付かれないまま深刻な問題を引き起こします
base_convert	任意精度で 2～36 進数を変換します	素朴な変換では、2^53 を超える値の精度が失われます

ReDoS の制限時間

regex_extract は省略可能な budgetMs を受け付けます（デフォルトは 1000、最大は 10000）。制限時間を超えると、ワーカースレッド上の実行は終了させられます。

これは単なる利便性ではありません。Node の正規表現エンジンは中断できないため、壊滅的なバックトラッキングを引き起こすパターンはメインスレッドを無期限にブロックします。(a+)+$ を 'a'.repeat(n) + '!' に対して実行した際の増加を測定した結果は次のとおりです。

n	時間
20	18 ms
22	70 ms
24	276 ms
26	1108 ms

文字が 2 つ増えるごとに、およそ 4 倍になります。n=40 では処理が戻りません。クライアントのメインスレッドで実行される MCP サーバーでは、ユーザーのエディターがフリーズします。プロセスの分離と終了が、実質的に唯一の防止策です。

制限時間を超えると、応答でその旨を伝え、呼び出し元にパターンの修正方法を示します。

{
  "timedOut": true,
  "budgetMs": 300,
  "safety": {
    "risk": "high",
    "reasons": ["nested quantifier inside a repeated group — classic exponential backtracking"]
  },
  "advice": "Pattern execution exceeded 300ms and was terminated. ... Rewrite it to remove ambiguity — typically by replacing a nested quantifier such as (a+)+ with an unambiguous form such as a+ ..."
}

引数の検証

呼び出しはすべて、ディスパッチ前にツール独自の JSON Schema に照らして検証されます。必須フィールド、プリミティブ型、列挙値への適合、数値の範囲、未定義のプロパティを確認します。不正な呼び出しには、自信ありげな誤答ではなく、具体的なエラーを返します。

クライアントがスキーマを常に正しく遵守するとは限らないため、これは重要です。不正な呼び出しを黙って処理するサーバーは、呼び出しを拒否するサーバーよりも問題です。

例

正確な差分

{ "a": "line one\nline two", "b": "line one\nline 2" }

→ { "added": 1, "removed": 1, "lines": [ { "op": "equal", "aLine": 1, "bLine": 1 }, ... ] }

精度を保つ大きな整数の変換

{ "value": "9007199254740993", "fromBase": 10, "toBase": 16 }

→ { "result": "20000000000001", "decimal": "9007199254740993" }

2 つの日付の間の営業日

{ "from": "2026-01-05", "to": "2026-01-12", "unit": "businessDays" }

→ { "value": 5 }

実行前にパターンを確認する

{ "pattern": "(a+)+$" }

→ { "risk": "high", "reasons": ["繰り返しグループ内の入れ子の量指定子 — 指数関数的なバックトラッキングを引き起こす典型的なパターン"] }

存在しない場合と null の場合

{ "json": "{\"a\":null}", "path": "a" }

→ { "resolved": true, "found": false, "value": null, "type": "null" }

設計上のメモ

なぜ HTTP ではなく stdio なのですか？ stdio サーバーにはリッスンソケットがありません。攻撃対象領域も、公開するポートも、誤設定する認証もなく、データがマシンの外に出ることもありません。純粋な計算処理に HTTP を使っても、リスクが増えるだけで利点はありません。

なぜキャッシュしないのですか？ すべての呼び出しはステートレスです。キャッシュを導入すると状態が生まれ、無効化の不具合やデータが残存する場所が発生します。処理のコストは十分に低いため、トレードオフにはなりません。

なぜサイズ超過の入力を拒否するのですか？ ハングした MCP サーバーはクライアントセッションも巻き添えにします。実行可能な対処方法を示して拒否するほうが、メモリを使い果たすより確実に優れています。

なぜ依存関係を一切使わないのですか？ 依存関係はどれも、更新、セキュリティ勧告、サプライチェーンリスク、そしてサーバーが動かなくなる理由をもう一つ増やすという、継続的な負担になります。ここで必要な機能はすべて Node の標準ライブラリでまかなえます。

開発

node server.cjs              # speaks MCP over stdio
node selftest.mjs            # engine verification, 35 assertions
node protocol-test.cjs       # protocol verification, 88 assertions
npm test                     # both suites

どちらのテストスイートも、インストール手順なしで通常の Node 上で実行できます。

selftest.mjs は、公開済みの定数とのハッシュ照合、2^53 を超える大きな整数の往復変換、RFC 4180 の引用符処理における境界ケース、Unicode の単語分割、カレンダー演算を確認します。protocol-test.cjs は、偽のトランスポートを介して実際のハンドラーを実行し、ハンドシェイク、バージョンネゴシエーション、すべてのツール、引数の検証、ReDoS の実行期限、不正なフレーム、分割されたフレーム、バッチ、並行リクエストの対応付け、決定性を網羅します。

これらのテストスイートで見つかった2つのバグは、どちらも回帰テストとして残しています。

• 単語分割正規表現における ReDoS。 元の textStats のパターンは [\p{L}\p{N}][\p{L}\p{N}'’-]* でした。これは重複する文字クラスが2つ隣接しています。長い文字列の末尾に一致しない文字が続くと、バックトラッキングが指数関数的に増大してプロセスがハングしました。このパッケージに含まれるアナライザーでは検出できませんでした。アナライザーは、与えられたパターンを静的に検査するだけで、ソースに手書きされたパターンは確認できないためです。上記の実行期限は、この問題があるために設けられています。
• スキーマ検証がありませんでした。 必須引数が欠けていても、単に値がないものとして扱われていました。そのため、path を指定し忘れた呼び出し元には、エラーではなく missing-key が返されていました。クライアント側のスキーマは、強制力のある検証ではありません。

ライセンス

MIT — LICENSE を参照してください。