MCP Tools

要約 (summary): AutonoMath は MCP (Model Context Protocol) サーバーとして 6 つのツールを公開する。Claude Desktop / Cursor / ChatGPT (Plus 以降) / Gemini から直接呼び出せる。

Protocol: MCP 2025-06-18 (FastMCP SDK, Python mcp package). Transport: stdio JSON-RPC.

前提 (Setup)

インストール・クライアント設定は getting-started.md を参照。

MCP server は stdio 転送で動作する。AutonoMath バイナリまたは python -m jpintel_mcp.mcp.server で起動可能。

---

search_programs

目的: 制度 (補助金 / 融資 / 税制 / 共済) の横断検索。

引数 (Arguments):

name	type	default	description
q	string | null	null	自由記述。3 文字以上で FTS5 trigram、2 文字以下は substring 一致
tier	string[] | null	null	S / A / B / C / X の OR 集合
prefecture	string | null	null	都道府県名 (完全一致)
authority_level	string | null	null	正本 (英語): national / prefecture / municipality / financial。日本語別名 (国 / 都道府県 / 市区町村 / 公庫) も受け付け、サーバ側で英語に正規化
funding_purpose	string[] | null	null	資金用途のフィルタ
target_type	string[] | null	null	対象者種別のフィルタ
amount_min_man_yen	number | null	null	助成上限の下限 (万円)
amount_max_man_yen	number | null	null	助成上限の上限 (万円)
include_excluded	bool	false	true で tier=X も含める
limit	int	20	1〜100
offset	int	0	ページング
fields	string	"default"	"minimal" / "default" / "full"。レスポンスサイズ切替

fields 選択肢:

値	results[] の中身	目安
minimal	unified_id / primary_name / tier / prefecture / authority_name / amount_max_man_yen / official_url	~150-300 B/row。list rendering / quick filter
default (省略時)	従来の Program 全フィールド	通常の tool chain
full	Program + enriched (A-J) + source_mentions + lineage (source_url / source_fetched_at / source_checksum)	深い分析。REST ?fields=full と shape 同一

戻り値 (Return):

{
  "total": 153,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "unified_id": "...",
      "primary_name": "...",
      "tier": "A",
      "prefecture": "青森県",
      "amount_max_man_yen": 500,
      "funding_purpose": ["設備投資"],
      "target_types": ["認定新規就農者"],
      "official_url": "https://...",
      "...": "..."
    }
  ]
}

結果構造は REST /v1/programs/search と同じ (api-reference.md)。

Claude が呼ぶタイミング:

• ユーザーが「青森県で使える設備投資補助金を教えて」のような検索系質問をしたとき
• 「IT 導入補助金の一覧」「中小企業向けの補助金」等の条件絞り込み

---

get_program

目的: 特定制度の完全な詳細を取得 (enriched JSON + source_mentions 付き)。

引数:

name	type	default	description
unified_id	string	(required)	制度の一意 ID (search_programs の結果や他ツールで返る)
fields	string	"default"	"minimal" / "default" / "full"。REST /v1/programs/{unified_id}?fields=... と parity

fields 選択肢 (get_program):

値	中身
minimal	7-key whitelist — UI の最初の表示に十分な見出しだけ
default	従来通りの ProgramDetail (Program + enriched + source_mentions + lineage)。互換性維持
full	同上。enriched / source_mentions / lineage は null でも key が必ず存在する契約に揃う

戻り値:

search_programs の 1 件分の構造 + enriched (A-J 次元の詳細) + source_mentions (一次資料 URL + fetched_at) + 取得時点の lineage (source_url / source_fetched_at / source_checksum)。REST /v1/programs/{unified_id} と同じ構造 (MCP parity)。

{
  "unified_id": "keiei-kaishi-shikin",
  "primary_name": "経営開始資金",
  "tier": "S",
  "enriched": {
    "A_basics": {"...": "..."},
    "B_target": {"...": "..."},
    "J_statistics": null
  },
  "source_mentions": [
    {"url": "https://www.maff.go.jp/...", "fetched_at": "2026-04-15T..."}
  ],
  "source_url": "https://www.maff.go.jp/...",
  "source_fetched_at": "2026-04-22T13:20:57.045412+00:00",
  "source_checksum": "638865704e10041c",
  "...": "..."
}

source_url / source_fetched_at / source_checksum は migration 001 前の旧 DB 行では null になる (移行後は必ず埋まる)。

Claude が呼ぶタイミング:

• search_programs で候補が絞り込まれた後、ユーザーが 1 件の詳細を求めたとき
• 「この制度の申請窓口の締切は？」「必要書類は？」のような掘り下げ質問

エラー: 存在しない ID は例外 (ValueError: program not found)。

---

batch_get_programs

目的: get_program を最大 50 件まで一度に叩く。search_programs の結果 20 件について全件 enriched を取りたい場合に、20 回 get_program を叩くのではなく 1 回で済ませる。

引数:

name	type	default	description
unified_ids	string[]	(required)	1〜50 件の制度 ID。重複は自動 dedupe (最初の出現順で一意化)。空配列 / 50 超は ValueError

戻り値:

{
  "results": [
    {
      "unified_id": "keiei-kaishi-shikin",
      "primary_name": "経営開始資金",
      "tier": "S",
      "enriched": {"A_basics": {"...": "..."}},
      "source_mentions": [],
      "source_url": "https://...",
      "source_fetched_at": "2026-04-22T...",
      "source_checksum": "638865...",
      "...": "..."
    }
  ],
  "not_found": ["UNI-typo-1"]
}

field	type	description
results	object[]	各要素は get_program(fields="full") と同じ shape。dedupe 後の入力順を保存
not_found	string[]	DB で解決できなかった ID (例外ではなく部分成功扱い。空でない batch は 404 にしない)

enriched / source_mentions / lineage 3 キーは null でも必ず存在する (fields="full" の契約と同じ)。

Claude が呼ぶタイミング:

• search_programs で絞り込まれた 20 件候補について、全件の詳細を一気に取得したいとき
• 比較 UI で候補リストの各行に enriched 情報を展開したいとき
• 「この 10 件全部について必要書類を横並びで教えて」のような比較系指示

エラー:

• ValueError: unified_ids required — 空配列
• ValueError: unified_ids cap is 50, got N — 50 件超
• 個別 ID の解決失敗は例外にしない (not_found に入る)

Rate limit: 現状は batch 全体で 1 リクエスト扱い (TODO: 将来 N 件 × N 単位の credits 会計に移行予定。src/jpintel_mcp/api/programs.py の batch_get_programs docstring 参照)。

---

list_exclusion_rules

目的: 排他ルール全件の列挙。

引数: なし。

戻り値:

[
  {
    "rule_id": "agri-001",
    "kind": "mutex",
    "severity": "absolute",
    "program_a": "keiei-kaishi-shikin",
    "program_b": "koyo-shuno-shikin",
    "program_b_group": [],
    "description": "同時受給不可",
    "source_notes": "MAFF 要綱第3条",
    "source_urls": ["https://..."],
    "extra": {}
  }
]

Claude が呼ぶタイミング:

• ユーザーが「どの補助金を併用すると失格になる？」と聞いたとき
• 農業制度の全体像 (新規就農 / 認定農業者 / スーパー L の依存関係) を表示するとき

注: 現在 35 件 (農業核心 22 + 非農業 13)。条件付きルール (解雇禁止・みなし大企業等) は W3 以降で追加予定。exclusions.md 参照。

---

check_exclusions

目的: 候補制度セットを渡して、併用した場合に triggered する排他ルールを列挙。

引数:

name	type	default	description
program_ids	string[]	(required)	制度 ID の配列 (unified_id または農業 canonical 名)

戻り値:

{
  "program_ids": ["keiei-kaishi-shikin", "koyo-shuno-shikin"],
  "hits": [
    {
      "rule_id": "agri-001",
      "kind": "mutex",
      "severity": "absolute",
      "programs_involved": ["keiei-kaishi-shikin", "koyo-shuno-shikin"],
      "description": "同時受給不可",
      "source_urls": ["https://..."]
    }
  ],
  "checked_rules": 35
}

Claude が呼ぶタイミング:

• ユーザーが複数の候補制度をリストアップして「これ全部併用できる？」と聞いたとき
• search_programs で複数候補を提示した後、自動的に安全性チェックをかけたいとき

エラー: 空配列は例外 (ValueError: program_ids required)。

---

get_meta

目的: データセット概況 (制度数 / tier 分布 / 都道府県分布 / ルール数 / ingest 時刻)。

引数: なし。

戻り値:

{
  "total_programs": 6771,
  "tier_counts": {"S": 59, "A": 525, "B": 3297, "C": 2421, "X": 469},
  "prefecture_counts": {"青森県": 42, "_none": 4311},
  "exclusion_rules_count": 35,
  "last_ingested_at": "2026-04-22T09:00:00Z",
  "data_as_of": "2026-04-21"
}

Claude が呼ぶタイミング:

• ユーザーが「データベースの網羅範囲は？」「最新いつ？」と聞いたとき
• デバッグ用に dataset の生存確認

---

関連

• api-reference.md — 同機能を REST で叩く場合の仕様
• exclusions.md — 排他ルールの概念
• getting-started.md — Claude Desktop 連携設定