mcp-server 読解ガイド

1事前知識：MCPのしくみ

MCP（Model Context Protocol）は、AIアプリケーション（Claude Code、Claude Desktop等）が外部の道具やデータに接続するための通信規約です。登場人物は3者います。

• ホスト：利用者が操作するAIアプリ。Claude Codeそのもの。
• クライアント：ホストの中で、1つのサーバーとの接続を受け持つ部品。サーバー1つにつき1つ。
• サーバー：道具を提供する側。このリポジトリのmcp-serverはこれにあたります。

やり取りするメッセージはすべてJSON-RPC 2.0です。idを持つ「要求」には必ず同じidの「応答」（resultかerror）を返し、idを持たない「通知」には応答しません。

stdioトランスポート：標準出力はプロトコル専用

MCPにはメッセージの運び方（トランスポート）が2種類あり、このサーバーはstdioを使います。クライアントがサーバーを子プロセスとして起動し、標準入力に要求を書き込み、標準出力から応答を読みます。1行が1メッセージです。

1回の接続の流れ

接続は「初期化 → 発見 → 実行 → 終了」の順に進みます。サーバーが能動的に何かを送ることはなく、すべてクライアントからの要求への応答です。

実際の初期化のやり取りです（instructionsは途中で省略）。

→ stdin
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}
← stdout
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18",
  "capabilities":{"logging":{},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},
  "serverInfo":{"name":"dbxray","version":"0.2.0"},
  "instructions":"DBのテーブル定義（dbxrayが出力したスキーマのスナップショット）を調べるサーバー。全体像はlist_schemas、…"}}

tools.listChanged:falseは「起動後にツールの一覧は変わらない」という宣言です。resourcesも同じく一覧は変わらず、購読（subscribe）にも対応しません。スナップショットは起動時に読んだまま変わらないためです。loggingはSDKが自動で付け加える能力で、このサーバーは使っていません。versionはjarのマニフェストのImplementation-Versionで、jar以外から起動するとdevになります。

ツール：定義・結果・2種類のエラー

MCPのサーバーが提供できるものは3種類（ツール・リソース・プロンプト）あり、このサーバーはツールとリソースを提供します（プロンプトは無し）。中心はツールで、「AIが自分の判断で呼ぶ関数」です。リソースは次の節で扱います。

→ 見つからない名前（ツールのエラー。ObjectResolverが文言を作る）
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_table","arguments":{"table":"employe"}}}
←
{"jsonrpc":"2.0","id":4,"result":{"isError":true,"content":[{"type":"text",
  "text":"テーブルemployeが見つかりません。名前の似たテーブル: testdb:sample.employee, testdb:sample.employee_directory_view, …"}]}}

→ 存在しないツール（プロトコルのエラー。SDKが返す）
{"jsonrpc":"2.0","id":22,"method":"tools/call","params":{"name":"no_such_tool","arguments":{}}}
←
{"jsonrpc":"2.0","id":22,"error":{"code":-32602,"message":"Unknown tool: invalid_tool_name","data":"Tool not found: no_such_tool"}}

リソース：利用者が会話に添付するもの

ツールが「AIが呼ぶもの」なのに対し、リソースは利用者（またはクライアント）が選んで会話に載せるデータです。Claude Codeのターミナル版なら@、VS Codeなら「コンテキストの追加…」→「MCP リソース」の候補に並び、利用者が選ぶと中身がそのまま会話に添付されます。AIの判断に依らず、利用者が指名したテーブルの定義を確実に載せられるのが利点です。

このサーバーは、スナップショットの全テーブル（ビューを含む）を1つずつ具体的なリソースとして列挙します（URIテンプレートは使いません。理由はdocs/architecture/mcp-server.mdの「URIテンプレートと補完を出さない理由」）。読むと、get_tableを絞り込み無しで呼んだ場合と同じJSONが返ります。

→ 一覧（テーブルの数だけ並ぶ。先頭の2件）
{"jsonrpc":"2.0","id":3,"method":"resources/list"}
←
{"jsonrpc":"2.0","id":3,"result":{"resources":[
  {"uri":"dbxray://testdb/sample/department","name":"sample.department","title":"sample.department",
   "description":"sample.department / testdb / table / 社内の組織単位を管理するマスタテーブル。 従業員（employee）は必ずいずれか1つの部署に所属する。",
   "mimeType":"application/json"},
  {"uri":"dbxray://testdb/sample/employee","name":"従業員 (sample.employee)","title":"従業員 (sample.employee)",
   "description":"従業員 (sample.employee) / testdb / table","mimeType":"application/json"}, …]}}

→ 読み出し（textはget_tableと同じJSONの文字列）
{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"dbxray://testdb/sample/employee"}}
←
{"jsonrpc":"2.0","id":4,"result":{"contents":[{"uri":"dbxray://testdb/sample/employee","mimeType":"application/json",
  "text":"{\"schema\":\"sample\",\"name\":\"employee\",\"logicalName\":\"従業員\",\"type\":\"table\",\"columns\":[…]…}"}]}}

→ 一覧に無いURI（プロトコルのエラー。SDKが返す）
{"jsonrpc":"2.0","id":14,"method":"resources/read","params":{"uri":"dbxray://testdb/sample/nope"}}
←
{"jsonrpc":"2.0","id":14,"error":{"code":-32002,"message":"Resource not found","data":{"uri":"dbxray://testdb/sample/nope"}}}

• nameは論理名 (スキーマ名.物理名)（論理名が無ければスキーマ名.物理名）。クライアントの絞り込みはname・description・URIが対象で、titleは対象外のため、論理名・物理名のどちらでも探せるようnameに両方を入れています。
• descriptionの先頭にもnameを入れるのは、Claude Codeの候補がURIを途中で切り、nameよりdescriptionを優先して表示するためです（120文字で切り詰め）。
• URIの各区間（DB名・スキーマ名・テーブル名）はパーセントエンコードします。DB由来の名前は/・空白・日本語を含み得るためです。name・descriptionも、制御文字・改行・書字方向を変える制御文字を空白に置き換えて1行にします。

MCPの概念と、このリポジトリでの実体

2事前知識：MCP Java SDK（mcp-core 2.0.1）

使っているモジュールと、選んだ理由

サーバーの組み立て方

SDKのサーバーはBuilderで組み立てます。このリポジトリでSDKのサーバーAPIに触るのは、McpServerMain.startのこの部分だけです。

final McpJsonMapper jsonMapper = new JacksonMcpJsonMapper(new ObjectMapper());
McpServer.sync(new StdioServerTransportProvider(jsonMapper))   // 同期版のBuilder。stdioで1セッション
    .serverInfo(SERVER_NAME, version())
    .instructions(INSTRUCTIONS)
    .capabilities(ServerCapabilities.builder().tools(false).resources(false, false).build())
    .jsonMapper(jsonMapper)
    .tools(new TableDefinitionTools(catalog).specifications())          // List<SyncToolSpecification>
    .resources(new TableDefinitionResources(catalog).specifications())  // List<SyncResourceSpecification>
    .immediateExecution(true)                                   // 2.4節
    .build();                                                   // ここで標準入力の読み取りが始まる

ツール1つはSyncToolSpecificationで表します。中身は「ツールの定義（Tool）」と「呼ばれたときの処理（callHandler）」の組です。callHandlerの型は(McpSyncServerExchange, CallToolRequest) → CallToolResultで、exchangeはクライアントへ逆に問い合わせるための窓口ですが、このサーバーは使いません。リソース1つも同じ形のSyncResourceSpecificationで、「リソースの定義（Resource）」と「読まれたときの処理（(exchange, ReadResourceRequest) → ReadResourceResult）」の組です。

SDKの中で起きること

• 同期APIは非同期実装の包みです。McpServer.sync(...)で作るMcpSyncServerは内部でMcpAsyncServerを持ち、同期のハンドラをMono.fromCallable(...)で包んで登録します。
• stdioは専用スレッド2本で動きます。StdioServerTransportProviderはbuild()の時点でセッションを1つ作り、標準入力を1行ずつ読むstdio-inboundスレッドと、標準出力へ書くstdio-outboundスレッド（それぞれ単一スレッドのExecutor）を起動します。
• main()はすぐ戻ります。build()の後にmain()は終わりますが、上の2本はデーモンでないスレッドなのでJVMは動き続けます。標準入力がEOFになると読み取りが終わり、スレッドが片付いてプロセスが終了します。
• 要求の振り分けはSDKのMcpServerSessionがmethod名で行います。tools/callなら、名前でツールを探し、2.5節の入力検証をしてから、登録したcallHandlerを呼びます。resources/readなら、URIが完全一致するリソースを探して読み出しのハンドラを呼び、無ければ-32002 Resource not foundを返します。

immediateExecution(true) の理由

修正はSDKのmainに入っていて未リリース（docs/architecture/mcp-server.mdの記述）。修正版が出たらimmediateExecutionを残すかを判断する、とされています。

SDKが先に行う入力検証

SDKはcallHandlerを呼ぶ前に、argumentsをinputSchema（JSON Schema）で検証します（ToolInputValidator。validateToolInputsの既定はtrue）。型・enum・minimum/maximum・required・additionalProperties:falseに反すると、ハンドラは呼ばれず、SDKが英語の文言でisError: trueを返します。

→ get_related_tables の depth は inputSchema で maximum 3
{"name":"get_related_tables","arguments":{"table":"employee","depth":4}}
← SDKが返す（ToolArgumentsの「1〜3の整数を指定してください」には届かない）
{"isError":true,"content":[{"type":"text","text":"Tool (get_related_tables) input validation failed: Validation failed: JSON schema validation errors: [/depth: must have a maximum value of 3]"}]}

引数の検証は役割分担です。型・範囲・enum・未知の引数はSDKが入力スキーマで検証し、これを正とします。自前のToolArgumentsは、スキーマで表せない検証（空白を除いた後の空、件数の上限、大文字小文字を区別しない選択肢の照合など）だけを行います。

ServiceLoader と shadowJar

SDKは既定のJSON実装（McpJsonMapperとJsonSchemaValidator）をjava.util.ServiceLoaderで探します。マッパーはMcpServerMainが明示的に渡していますが、入力検証器は渡していないため、mcp-json-jackson2のjarのMETA-INF/services/…JsonSchemaValidatorSupplierから見つけています。見つからなければ起動時にServiceConfigurationErrorで失敗します。

配布用の1つのjar（shadowJar）に依存を詰めると、同名のMETA-INF/servicesファイルが上書きされて登録が消えることがあります。build.gradleのmergeServiceFiles()はそれを防ぐ設定で、McpServerProcessTestが実物のjarを子プロセスで起動して確かめています。

3全体像と読む順

パッケージは5つです。依存の向きはtool → catalog ← snapshot・catalog ← insightで、検索と関連のたどりを持つcatalogはSDKにもJSONライブラリにも依存しません。cliのpresentation → application → domain ← infrastructureと同じ考え方で、中心のロジックを単体テストしやすくするためです。

おすすめの読む順

上から順に読むと、外側（起動とMCP）から内側（ルール）へ進めます。

1. McpServerMain：何をどの順で組み立てるか。INSTRUCTIONSでツールの全体像もつかめます。
2. TableDefinitionTools：ツールクラス12の並び＝クライアントに見える順。
3. ToolSpecifications.readOnlyTool：全ツール共通の包み。引数の誤りがisErrorになる場所です。
4. SchemaTools：小さなツールクラスで「型」をつかみ、続けて一番大きいTableTools。get_tableの結果の加工はTableOutputBuilderに分かれています。
5. ToolArguments・ObjectResolver・Page：ツールクラスが共通で使う部品。
6. SchemaCatalog：組み立てと、関心ごとの窓口（tables()・functions()・sequences()・types()・viewpoints()・functionTableUsages()・relations()・junctions()）の一覧です。続けてTableCatalog・ObjectCatalog・ViewpointCatalogの公開メソッドを見ると、ツールから見たcatalogの全機能がつかめます。
7. TableFilter・SearchQuery・RelationGraph：テーブルの絞り込み、点数づけ、幅優先探索。7章の図と合わせて読むと速いです。
8. SnapshotDirectoryReader：ファイルからEntryができるまで。6章参照。
9. DiagramTools・MermaidErDiagram、TableDefinitionResources：ツールの型から外れる2つ。結果にMermaidの記述を入れるER図（7.9節）と、AIではなく利用者が選ぶリソース（1章）です。
10. JunctionDetector・SimilarTableFinder・ImpactAnalyzer：スナップショットに無い値を導く・既存の窓口をまとめる、後から足された3つ。中間テーブルの判定（7.11節）、構造の似たテーブルの探索（7.12節）、テーブルの影響範囲の集約（7.13節）です。

4起動の流れ

McpServerMain.mainは次の順に進みます。利用者が直せる誤りはすべてUserCorrectableExceptionで表し、mainの1箇所で捕まえて終了コード2で終わります（cliと同じ方針。ただしcliのクラスとは別物で、mcpパッケージに自前で持っています）。

1. 標準エラーをUTF-8に固定：System.setErr(new PrintStream(…, UTF_8))。実行環境のロケールで日本語が化けないようにするためです。
2. 起動引数の解釈：ServerArguments.parse。受け付けるのは--snapshot=<ディレクトリ>1つだけで、未知の引数・重複・空・未指定はすべて誤りです。
3. 参考情報の読み込み：InsightsDirectoryReaderのreadViewpoints（観点）とreadFunctionTableUsages（関数の利用テーブル。cliを--previewで実行した場合だけある。7.10節）。--snapshotの親の兄弟のinsights/を自分で求めて読みます。ディレクトリ・ファイルが無ければ0件で、誤りにはしません。
4. スナップショットの読み込み：SnapshotDirectoryReader.readがSchemaCatalogを返します。ディレクトリが無い、database.jsonが1つも無い、新しすぎるformatVersion、JSONとして読めない行、schema・nameの無い行は誤りです（メッセージにファイル名と行番号が入ります）。
5. 参考情報の合成：catalog.withViewpoints(viewpoints).withFunctionTableUsages(functionTableUsages)。SchemaCatalogは不変なので、観点・関数の利用テーブルを加えた新しいインスタンスを作ります。
6. 読み込み件数の表示：標準エラーへ[info]:15テーブルを読み込みました。 [snapshot=…]。
7. SDKの起動：start(catalog)。2章のBuilderでツールとリソース（全テーブル分）を登録して組み立て、build()した時点で標準入力の待ち受けが始まり、mainは戻ります。

I/Oの失敗（UncheckedIOException）は利用者が直せる誤りではないため捕まえません。スタックトレースが標準エラーに出て、終了コードは1になります。

51回のツール呼び出しの流れ

get_tableを例に、標準入力の1行が標準出力の1行になるまでをたどります。灰色の枠がSDK、色の付いた枠がこのリポジトリのコードです。右側は途中で抜ける経路です。

全ツールを包むreadOnlyToolの核心はこの部分です。InvalidToolArgumentExceptionだけを捕まえてisErrorに変え、それ以外の例外はSDKへそのまま投げます。

.callHandler((exchange, request) -> {
  try {
    return handler.apply(new ToolArguments(request.arguments()));
  } catch (InvalidToolArgumentException e) {
    return CallToolResult.builder().addTextContent(e.getMessage()).isError(true).build();
  }
})

どこで止まり、何が返るか

6データの持ち方

1行を2通りに持つ

このサーバーを理解するうえで一番効く事実です。スナップショットの1行は、読み込み時に「検索に使う型付きの項目」と「元の1行の文字列（json）」の両方として保持されます。

この設計から、次のことが言えます。

• 検索に新しい項目を使いたいときだけ、*Lineと*Entryの両方にフィールドを足します。
• get_tableのsectionsで削れるのはTableSectionのenumに並ぶ9項目（columns・indexes・constraints・foreignKeys・logicalRelations・triggers・definition・referencedTables・referencedByViews）だけです。それ以外（name・logicalName・partitionKeyや将来の項目）は常に残ります。
• 観点（viewpoints）はスナップショットの項目ではないため、get_tableの結果に後から足されます。sectionsでの絞り込みの対象外です。
• 関数が利用しているテーブル（tableUsage）も、スナップショットの項目ではなく、参考情報からget_functionの結果に後から足されます。cliを--previewで実行して参考情報がある場合だけで、定義本体のハッシュが一致するときに限ります（7.10節）。
• 中間テーブルの区分（erRole）・つなぐテーブル（junctionOf）・多対多の相手（manyToMany）も、スナップショットの項目ではなく、主キー・外部キーの構成から組み立て時に導いた値をget_tableの結果に後から足します（7.11節）。観点と同じくsectionsでの絞り込みの対象外で、該当すれば常に返します。
• テーブルのリソースの中身は、get_tableと同じTableOutputBuilderで組み立てます（sections・columnsの絞り込み無し）。get_tableの結果に項目を足せば、リソースにも同じ項目が載ります。
• テーブルを参照しているビュー（referencedByViews）もスナップショットの項目ではなく、他のビューのreferencedTablesから逆引きして後から足します（7.5節）。こちらはTableSectionに入っているため、sectionsで選べます。

catalogのrecord（Entry）一覧

出力のrecordはそのままAPI

各ツールクラスの中にあるListTablesOutput・RelatedTablesOutput等のrecordは、Jacksonがrecordのコンポーネント名をキーにしてJSON化します。コンポーネント名を変えると、AIから見える結果の項目名が変わります。リファクタリングで改名するときは、ツールのAPIを変えることと同じです。

7catalogの中心ロジック

catalogの各窓口（TableCatalog・ObjectCatalog・ViewpointCatalog）は全オブジェクトをListで持ち、要求のたびに先頭から絞り込みます。あらかじめ作る索引は、RelationGraphの「参照先・参照元」の2つのMapとそこから求めたテーブルごとの関連の数（RelationCounts）、JunctionTablesの中間テーブルの判定結果と多対多の相手（7.11節）、SimilarTableFinderの正規化したカラム名とDBごとのカラム名の数（7.12節）だけです。どれも呼び出しのたびに求め直すと重い、またはスナップショットだけで決まる値です。スナップショットは数百テーブル規模なので、線形の走査で十分という割り切りです。

7.1 名前の解決（get_* と関連ツールの入口）

1. ObjectReference.of(database, schema, name)：schemaが未指定で名前がsample.employeeの形なら、最初の.で分けてスキーマ修飾とみなします。
2. ObjectCatalog.lookup<E extends SchemaObject>：DB・スキーマ・名前を大文字小文字を区別せず完全一致で比べます。テーブル・関数・シーケンス・型の4種類がSchemaObjectを実装しているので、この1つの汎用メソッドを共有できます（関数・シーケンス・型はObjectCatalogの窓口から、テーブルは候補の求め方だけを差し替えてTableCatalog.lookupから呼びます）。
3. 結果は封印インタフェースLookupの3通り：Found（1件）・Ambiguous（複数。キー順）・NotFound（候補付き）。
4. ObjectResolver.resolveがswitchのパターンマッチで分岐し、Found以外は候補を含む文言でInvalidToolArgumentExceptionを投げます。

見つからないときの候補の求め方は、種類で違います。テーブルは「その名前でsearch_tablesした上位5件」なので、カラム名の一致も候補に入ります（employeにattendanceが出るのはemployee_idカラムがあるため）。関数・シーケンス・型は「名前の部分一致の先頭5件」です。どちらもDB・スキーマの絞り込みを外して探します。

7.2 テーブル検索の点数（SearchQuery）

検索語をNFKC正規化と小文字化（TextValues.normalize）してから空白で区切ります。全角空白もNFKCで半角になるため区切りとして効きます。形態素解析はしません。

• AND：どの項目にも含まれない語が1つでもあれば、そのテーブルは一致しません。
• 語ごとに最大点：1語について、一致した項目の点数の最大値を取り、語ごとの最大値を合計します。
• 同点：DB名・スキーマ名・テーブル名の順。

サンプルで従業員を検索すると、employee（論理名「従業員」の完全一致で80点）、employee_history（論理名「従業員履歴」の部分一致で30点）、department（説明に「従業員」を含み8点）の順になります。

{"total":3,"tables":[
  {"database":"testdb","schema":"sample","name":"employee","logicalName":"従業員","type":"table",
   "matchedIn":["logicalName","column:employee_id","column:employee_code","column:employee_name","column:manager_id"]},
  {"database":"testdb","schema":"sample","name":"employee_history","logicalName":"従業員履歴","type":"table","matchedIn":["logicalName"]},
  {"database":"testdb","schema":"sample","name":"department","type":"table","description":"社内の組織単位を…","matchedIn":["description"]}]}

totalはlimitで切る前の件数です。

一覧・検索の対象の絞り込み（DB・スキーマ・区分・観点・ER上の区分）は、ツール側でTableFilterとして1回組み立ててからTableCatalogへ渡し、catalogは各テーブルをmatchesで問い合わせるだけです。絞り込みは検索と並べ替えより前に行うため、観点・中間テーブルを指定しても総数とlimitが正しくなります。中間テーブルだけに絞る条件（withJunctionsOnly）は、判定結果の窓口JunctionTablesを受け取って問い合わせます。区分の値（table・view・materialized_view）はTableTypeの1か所にあり、list_tablesの入力スキーマのenumもここから作ります。

7.3 カラムの逆引き（ColumnQuery・find_columns）

強さは「物理名の完全一致 4 ＞ 論理名の完全一致 3 ＞ 物理名の前方一致 2 ＞ 物理名か論理名の部分一致 1」です。match: exact（既定）では3以上だけが残ります。各カラムには、そのカラムが外部キー・論理リレーションで指している先（複合キーなら同じ位置の相手カラム）をreferencesとして添えます。

7.4 関連のグラフ（RelationGraph）

テーブルを頂点、外部キーと論理リレーションを辺とするグラフです。スナップショットには「自分が参照している先」しか書かれていないため、組み立て時に全テーブルを1周して「自分を参照している元」（incoming）の索引を作ります。辺の向きは常に参照元（外部キーを持つ側）→ 参照先です。

← find_join_path(from: attendance_note, to: project) の text（joinsは省略）
{"from":"sample.attendance_note","to":"sample.project","paths":[{
  "tables":["sample.attendance_note","sample.attendance","sample.employee","sample.project_assignment","sample.project"],
  "joins":[ {"from":"sample.attendance_note","fromColumns":["attendance_id","work_date"],"to":"sample.attendance",…}, … ]}]}

組み立て時には、テーブルごとの関連の数（RelationCounts）も1回だけ求めます。list_tablesが各行に添え、orderByでの並べ替えに使います。どれも自己参照とスナップショットに無いテーブルを除き、同じテーブルとの複数の関連は1つと数えます。

• incoming：自テーブルを参照しているテーブルの数。多いほど中心のマスタ（サンプルのemployeeは5）。
• outgoing：自テーブルが参照しているテーブルの数。多いほどトランザクションや中間テーブル（project_assignmentは2）。
• impact：参照元をRelationCounts.IMPACT_DEPTH（3）段まで幅優先でたどって届くテーブルの数（変更の影響範囲）。被参照の少ない根っこのマスタも拾える（departmentは被参照1だがemployee経由で7）。段数を無制限にすると、大きなDBでは共通のマスタ経由で大半のテーブルに届いて差が出なくなるため打ち切る。

joinsの各要素のfrom・toは関連そのものの参照元・参照先で、たどる向きとは限りません。AIがJOINの条件を書くときはfromColumnsとtoColumnsを同じ位置同士で結びます。グラフの頂点の照合はObjectKeyのequals（大文字小文字を区別する）で、cliが同じ表記で出力する前提に立っています。

7.5 オブジェクト間の相互参照（SqlNames）

スナップショットには「このシーケンスをどのカラムが使うか」のような逆向きの情報がありません。そこで呼び出しのたびに全カラム・全トリガーを走査し、文字列からオブジェクトの名前を取り出して比べます。手順はどれも同じ3段です。

1. 切り出す：カラムのデフォルト値・型、トリガーの関数名から、名前の部分だけを取り出す（種類ごとに方法が違う。下の表）。
2. キーにする：qualifyでObjectKeyにする。二重引用符を外し、スキーマ修飾が無ければ参照元テーブルのスキーマを補う。
3. 比べる：sameObjectで、調べたいオブジェクトのキーと大文字小文字を区別せずに比べる。

型の切り出しの例。スナップショットのカラムの型（type）は、cliのmapperがPostgreSQLのformat_typeで取得した文字列です。ユーザー定義型を使うカラムには型名がそのまま入り、その型の配列を持つカラムには末尾に[]が付きます。typeOfColumnは末尾の[…]（正規表現(\[\d*])+$）を除いてから比べるので、配列のカラムも「その型を使うカラム」としてusedByColumnsに入ります。

PostgreSQLは配列の宣言時の大きさ（integer[3]）を保持せず、format_typeもinteger[]と表すため、数字入りの[3]は実際の出力には現れません。正規表現は[3]や多次元の[][]も除ける形で書かれています。サンプル（docs/sample/postgres）には配列のカラムが無いため、上の表の配列の行は仮の例です。

サンプルでget_typeを呼んだ実際の結果です。ビューの同名カラムも数えられています。

{"schema":"sample","name":"employee_status_enum","category":"ENUM","definition":"ACTIVE, ON_LEAVE, RETIRED",
 "usedByColumns":["sample.employee.status","sample.employee_directory_view.status"]}

参照しているビューの逆引き。get_tableのreferencedByViewsも、逆向きの情報を呼び出しのたびに求める相互参照です。ただし、cliがDBの依存関係から取得した参照先（ビューのreferencedTables。スキーマ名・名前）が構造化されて届くため、文字列の切り出しは要りません。viewsReferencingは、全テーブルのうちreferencedTablesに調べたいテーブルのObjectKeyを含むものをキー順に返します。比較はObjectKeyのequals（大文字小文字を区別する）で、関連のグラフと同じくcliが同じ表記で出力する前提です。サンプルでemployeeを引いた結果です（sectionsで絞っています）。

{"schema":"sample","name":"employee","logicalName":"従業員","type":"table",
 "referencedByViews":[{"schema":"sample","name":"employee_directory_view","type":"view"}],
 "viewpoints":[{"id":"personnel","name":"人事管理"},{"id":"project","name":"プロジェクト管理"}],
 "manyToMany":[{"table":"sample.project","via":"sample.project_assignment"}]}

末尾のmanyToManyは、sectionsに関わらず足される多対多の相手です（7.11節）。

ビューの側のreferencedTablesには、出力対象外のスキーマのテーブルも事実として残ります（サンプルのattendance_monthly_viewはsample_archive.departmentを参照）。スナップショットに無いテーブルはget_tableで引けないため、逆引きの結果にも現れません。

7.6 関数のオーバーロードと定義本体

• SchemaCatalogの組み立て時に、同じObjectKeyのFunctionEntryをFunctionOverloadsへ束ねます（出現順を保つLinkedHashMap）。名前の解決はこの束が単位です。
• get_functionは既定で定義本体（definition）を除きます。includeDefinition: trueのとき、全オーバーロードの本体が同じなら（Oracleのパッケージ内サブプログラム等）1つにまとめて上位に置き、違えば各オーバーロードに残します。どちらも4,000文字を超えると切り詰め、全体の文字数を書き添えます。getFunctionの中で、共通の本体を求めるsharedDefinitionと、各オーバーロードを切り詰めるtruncateDefinitionOfを順に呼んでいます。
• オーバーロードごとに、参考情報があれば利用しているテーブル（tableUsage）を足します（catalog.functionTableUsages().find(entry)。7.10節）。定義本体を除いても、FunctionEntry.definitionHashは読み込み時に求めてあるため、照合できます。

7.7 一覧の範囲（Page）

一覧系のツールはまず全件を求めてから、Page.applyでoffsetからlimit件を切り出します。totalは全件数、続きがあればnextOffset = offset + limitを返し、無ければnull（出力されない）です。offsetが全件より大きくても例外にはならず、空のリストになります。件数の既定値100・上限500はPage.DEFAULT_LIMIT・Page.MAX_LIMITにあり、固有の値を持つツール（search_tables・find_columns）以外はこれを使います。

7.8 関連のまとまり（ClusterDetector・list_table_clusters）

観点が宣言されていない範囲で、業務のまとまりの見当を付けるための推測です。使うのは外部キー・論理リレーションのつながりだけで、行数等の統計やテーブル名の接頭辞は使いません。

1. 範囲を決める：database・schemaで絞り、excludeViewpointTables: trueならいずれかの観点に所属するテーブルを除きます。範囲外のテーブルとの関連は無いものとみなします（RelationGraph.adjacentTablesの結果を範囲で切る）。
2. 関連の無いテーブルを外す：範囲内に隣が1つも無いテーブルは、まとまりに含めずunrelatedTablesの数だけを返します。
3. 連結成分に分ける：向きを問わずつながるテーブルの組を1つのまとまりとします。
4. 大きすぎれば分け直す：maxClusterSize（既定30）を超えるまとまりは、被参照の最も多いテーブルをハブとして除き、残りを連結成分に分け直します。これを繰り返します。ただし、そのテーブルの被参照がTableClusters.HUB_MIN_INCOMING（3）未満なら、一続きの関連を切るだけになるため分けずに残します。
5. ハブだけとつながるテーブルを寄せる：ハブを除いて1テーブルだけになったものは、被参照の最も多い隣のハブごとに1つのまとまりへ集めます。

まとまりはテーブルの多い順、同数なら代表（被参照の最も多いテーブル）の順に並べます。サンプルでmaxClusterSize: 4にすると、employee（被参照5）がハブとして除かれ、10テーブルのまとまりが3つに分かれます。

{"total":4,"unrelatedTables":3,
 "hubs":[{"database":"testdb","name":"sample.employee","logicalName":"従業員","incoming":5}],
 "clusters":[
  {"database":"testdb","representative":"sample.department","size":5,
   "tables":[{"name":"sample.department"},{"name":"sample.parking_spot"},{"name":"sample.audit_log"},
             {"name":"sample.employee_history","logicalName":"従業員履歴"},{"name":"sample.employee_profile"}],
   "hubs":["sample.employee"],"viewpoints":["personnel"]},
  {"database":"testdb","representative":"sample.attendance","size":2,…,"hubs":["sample.employee"]},
  {"database":"testdb","representative":"sample.project","size":2,…,"hubs":["sample.employee"],"viewpoints":["project"]},
  {"database":"testdb","representative":"sample.warehouse_zone","size":2,…,"viewpoints":["logistics"]}]}

最初のまとまりの5テーブルは互いに関連を持たず、どれもハブのemployeeとだけつながっているため、5の手順で寄せられたものです。既定のmaxClusterSize（30）では分け直さず、employeeを代表とする10テーブルと、warehouse_zone・shipmentの2つになります。結果のviewpointsは、まとまりのテーブルを1つでも含む観点です。

7.9 ER図の範囲と記法（DiagramScope・MermaidErDiagram・get_er_diagram）

get_er_diagramは2段に分かれます。catalogが何を描くか（DiagramScope：テーブル・関連・スナップショットに無いテーブル）を決め、toolのMermaidErDiagramがどう書くか（MermaidのerDiagramの文字列）を受け持ちます。catalogにMermaidの知識を持ち込まないための分け方です。

箱として描くのはDiagramScope.nodes()で、範囲のテーブルの後に、関連の参照先のうちスナップショットに無いテーブルを足したものです（カラムの無い箱になります）。これがDiagramTools.MAX_NODES（80。cliのerDiagramMaxNodesの既定値）を超えるとツールのエラーにします。

MermaidErDiagramの表記は、cliのER図（MermaidSupport）に揃えています。mcp-serverはcliのコードに依存できないため同じ規則を別に持ち、ずれはSampleErDiagramContractTestがcliの観点ページのER図（ベースライン）と突き合わせて検知します。

サンプルで観点personnelを描いた実際の結果です。employeeの自己参照（manager_id）も描かれ、employee_profile.employee_idは主キーかつ外部キーなのでPK, FKになります。

← get_er_diagram(viewpoint: personnel) の text（mermaidは改行を戻して表示）
{"viewpoint":"personnel","mermaid":"…",
 "tables":["sample.department","sample.employee","sample.employee_history","sample.employee_profile","sample.parking_spot"]}

erDiagram
    sample_department["department"]
    sample_employee["employee（従業員）"]
    sample_employee_history["employee_history（従業員履歴）"]
    sample_employee_profile["employee_profile"]
    sample_parking_spot["parking_spot"]
    sample_department ||--o{ sample_employee : "employee_department_id_fkey"
    sample_employee |o--o{ sample_employee : "employee_manager_id_fkey"
    sample_parking_spot |o--o| sample_employee : "employee_parking_spot_id_fkey"
    sample_employee ||--o{ sample_employee_history : "employee_history_employee_id_fkey"
    sample_employee ||--o| sample_employee_profile : "employee_profile_employee_id_fkey"
    sample_department {
        integer department_id PK
    }
    sample_employee {
        integer employee_id PK "従業員ID"
        integer department_id FK "所属部署ID"
        integer manager_id FK "上長の従業員ID"
        integer parking_spot_id FK "駐車場ID"
    }
    sample_employee_history {
        integer employee_id FK
    }
    sample_employee_profile {
        integer employee_id PK, FK
    }
    sample_parking_spot {
        integer parking_spot_id PK
    }

関連が1つも無い範囲ではmessage（「図に描くテーブルの間に、外部キー・論理リレーションはありません。」）を添えます。AIには、mermaidの値を手を加えずに```mermaidのコードブロックに入れて示すよう、ツールの説明で指示しています。

7.10 関数が利用しているテーブル（FunctionTableUsages・get_function の tableUsage）

cliを--previewで実行すると、関数・プロシージャが利用しているテーブルと操作（C・R・U・D）を、定義本体から機械的に抽出した参考値として、参考情報の{DB名}/{スキーマ名}/functionTableUsages.jsonへ出力します（cli 読解ガイドの9.9節）。DBが持つ事実ではなく精度にリスクがあるため、プレビューの機能（互換性の対象外）です。mcp-serverはこれを読み、get_functionがオーバーロードごとにtableUsageとして返します。観点と同じく、スナップショットとは別のファイルを、読み込みの後に合成する情報です。

• 読み込み：InsightsDirectoryReader.readFunctionTableUsagesが、insights/{DB}/{スキーマ}/functionTableUsages.jsonをすべて読みます。無ければ0件で、誤りにはしません。formatVersionの上限は観点と同じ1（SUPPORTED_FORMAT_VERSION）、未知の項目は無視します。DB名・スキーマ名は、ディレクトリ名（パスに使えない文字を置き換えたもの）ではなく、ファイルの中のdatabase・schemaを使います（ファイルにDB名が無い場合だけ、DBのディレクトリ名）。:や/を含むDB名でも、スナップショットの関数と対応付けられるようにするためです。
• 定義本体のハッシュ：FunctionEntry.definitionHashは、読み込み時にSnapshotDirectoryReaderが求めます。求め方（UTF-8のSHA-256の小文字の16進）は、cliのFunctionTableUsagesInsightと同じで、片方だけを変えると、すべての関数で参考情報が返らなくなります。Oracleのパッケージのサブプログラムは、どれも定義にパッケージ全体を持つため、直前と同じ定義本体ならハッシュを使い回します。definitionHashを持たない参考情報を、定義本体のある関数に対応付けることはしません。
• 返す形：FunctionTools.tableUsageが、AIが読みやすい形に整えます。テーブルはスキーマ名.テーブル名、操作はCRUDの順に1つの文字列（RD等）です。解析した結果は、利用しているテーブルが無くてもtablesを空の配列で返します（参考情報が無い場合の「tableUsageの項目ごと無い」と区別するため）。解析しなかった場合（unsupported_language等）はstatus（とlanguage）だけです。動的SQL・読み切れなかった・オーバーロードをまとめた場合だけ、dynamicSql・incomplete・overloadsMergedを足します。
• スキーマが決まらない名前：tableにスキーマを付けず、schemaResolution（search_path・current_user・synonym）と、同じ名前のテーブルがあるスキーマschemaCandidatesを返します。ツールの説明に「候補が1つでもそのスキーマに決めつけないこと」「出力対象のテーブルだけを返すため、tablesが空でもテーブルに触れないとは限らない」と書き、参考値であることをAIに伝えます。
• 逆引きと参考情報の状態：findは、参考情報が無い場合と、ハッシュが異なる古い場合の両方で空を返します。利用者がすべきことが違う（無ければcliを--preview付きで実行し、古ければ出力し直す）ため、freshnessOfがCURRENT・STALE・ABSENTを区別して返します（findとget_functionの振る舞いは変えません）。UsedTable.matchesは、利用しているテーブルが指定したテーブルを指すかをCONFIRMED（スキーマが決まった名前の一致）・CANDIDATE（スキーマが決まらない名前で、候補に指定したテーブルのスキーマが含まれる）・NONEで返します。参考情報はカタログ上の名前で出力されるため、大文字小文字は区別して比べます。これらを使った「テーブルを使う関数」の逆引きは7.13節です。

get_functionの結果（tableUsageの部分）です。サンプルのclose_project（スキーマが決まる例）と、count_rows（動的SQLを含み、スキーマが決まらない例）を、既定のベースラインのスナップショット（docs/sample/postgres/output/snapshot）に、--previewの差分のベースラインの参考情報（docs/sample/postgres/output-preview/insights）を重ねたディレクトリをビルドしたjarに読ませて採取しました。

{"database":"testdb","schema":"sample","name":"close_project",
 "overloads":[{"kind":"PROCEDURE","arguments":"IN p_project_id integer","language":"plpgsql",
   "tableUsage":{"tables":[
     {"table":"sample.audit_log","operations":"CR"},
     {"table":"sample.employee","operations":"U"},
     {"table":"sample.project","operations":"R"},
     {"table":"sample.project_assignment","operations":"RD"}]}}]}

{"database":"testdb","schema":"sample","name":"count_rows",
 "overloads":[{"kind":"FUNCTION","arguments":"p_table_name text","result":"bigint","language":"plpgsql",
   "tableUsage":{
     "tables":[{"table":"employee","schemaResolution":"search_path",
                "schemaCandidates":["sample"],"operations":"R"}],
     "dynamicSql":["EXECUTE"]}}]}

7.11 中間テーブルと多対多（JunctionDetector・JunctionTables・erRole・manyToMany）

多対多の関係は、DBには「中間テーブルからの2本の外部キー」という形でしか現れません。AIがprojectとemployeeの関係を知るには、project_assignmentを見つけて2本の外部キーを読む必要があります。そこで、主キー・外部キーの構成から中間テーブルを機械的に判定し、テーブルのER上の区分（erRole: junction）と、中間テーブルを介した多対多の相手（manyToMany）として返します。ClusterDetector（7.8節）と同じく、DBの事実ではなく推測です。

JunctionDetector.detectは1テーブルについて次の順に判定します。

1. 区分がtableのテーブルだけを対象にする（ビュー・マテリアライズドビューは外す）。
2. 候補を集める：参照元の列がすべて主キーに含まれる関連（RelationGraph.outgoing。外部キー、論理リレーションの順）を集める。同じ列の組の関連は1本とみなし、先に現れる外部キーを残す。そのうえで、多重度がONE_TO_ONE・OPTIONAL_ONE_TO_ONEの関連（Relation.isOneToOne）を外す。列名は大文字小文字を区別せずに比べる。
3. 候補が多すぎれば諦める：候補がMAX_CANDIDATES（12）を超えると判定しない。組み合わせを総当たりするため、2のべき乗で増えるのを抑える。
4. 組み合わせを総当たりする：主キーの列を過不足なく覆い、かつどの関連にも他の関連に無い列がある（外すと覆えなくなる）組み合わせのうち、関連の数が最も多いものを採る。同数なら候補の並びで先のもの。
5. 2本以上なら中間テーブル：採った組み合わせがMIN_LINKS（2）本以上なら、JunctionTable（テーブルと構成する関連）を返す。

この「外すと覆えなくなる組み合わせのうち最も多いもの」という決め方で、次のような形も扱えます。

JunctionTablesは、SchemaCatalog.ofの組み立て時に全テーブルを1回だけ判定し、結果を2つのMapに持ちます。主キー・外部キーの構成から導ける値なので、スナップショットには入れません（RelationCountsと同じ考え方）。

• find(table)・roleOf(table)：中間テーブルの構成と区分。list_tables・search_tablesの各行のerRole、erRole引数での絞り込み（TableFilter.withJunctionsOnly）、get_tableのerRole・junctionOfに使います。junctionOf（JunctionTable.parents）には、スナップショットに無い親も残します。
• manyToMany(table)：中間テーブルごとに、つなぐ親どうしを互いの相手として集めたもの（相手・中間テーブルの順）。スナップショットに無い親は、起点にも相手にもしません（get_tableで引けないため）。自己多対多は、テーブルではなく関連の位置で比べて、自分自身を相手にします。

TableOutputBuilderは、manyToManyをMAX_MANY_TO_MANY（20）件までにし、超えると全体の件数をmanyToManyTotalで示します。ほぼすべての中間テーブルの親になる共通のテーブル（テナント等）の結果が膨らむのを防ぐためです。サンプルの実際の結果です（sectionsで絞っています）。

← get_table(table: project_assignment, sections: [foreignKeys]) の text（foreignKeysは省略）
{"schema":"sample","name":"project_assignment","type":"table","foreignKeys":[…],
 "viewpoints":[{"id":"project","name":"プロジェクト管理"}],
 "erRole":"junction","junctionOf":["sample.employee","sample.project"]}

← get_table(table: project, sections: [columns], columns: [project_id]) の text（columnsは省略）
{"schema":"sample","name":"project","logicalName":"プロジェクト","type":"table","columns":[…],
 "viewpoints":[{"id":"project","name":"プロジェクト管理"}],
 "manyToMany":[{"table":"sample.employee","via":"sample.project_assignment"}]}

← list_tables(erRole: junction) の text
{"total":1,"tables":[{"database":"testdb","schema":"sample","name":"project_assignment","type":"table",
  "erRole":"junction","incoming":0,"outgoing":2,"impact":0}]}

区分の値はErRoleのenumにあり、list_tables・search_tablesの入力スキーマのenumもここから作ります。今の値はjunctionだけで、通常のテーブルは区分を持ちません（erRoleの項目ごと出ません）。

7.12 構造の似たテーブル（SimilarTableFinder・find_similar_tables）

新しいテーブルを作る前に同じ目的の既存テーブルが無いか確かめる、履歴・バックアップ・複製のテーブルを見つける、といった用途のためのツールです。比べるのはカラム名の集合だけで、説明文の近さのような意味の類似は扱いません（呼び出したAIがget_tableで判断します）。基準は既存のテーブル（table）か、設計中のカラム名の並び（columns）のどちらか一方で、SimilarTableQuery.ofTable・ofColumnsが条件を組み立てます。

1. 比べる相手：範囲（TableFilter。DB・スキーマ・観点）内の、区分がtableのテーブル。基準自身は除く。tableを指定した場合は、基準と同じDBに限る。
2. カラム名を正規化する：NFKC＋小文字（TextValues.normalize）。正規化で同じ名前になるカラムは先のものを使う。相手のテーブルの正規化は、TableCatalogの組み立て時にSimilarTableFinderが1回だけ行う。
3. 重みを付ける：カラム名ごとにln((N+1) / そのカラム名を持つテーブルの数)。Nと数は、範囲のDBの区分がtableの全テーブル（基準自身を除く）で数える。範囲内のどのテーブルも持たないカラム名は、1テーブルだけが持つ場合と同じ重みにする。
4. 重み付きJaccard係数：共通のカラムの重みの合計 ÷（共通＋基準にだけある＋相手にだけある カラムの重みの合計）を百分率にする。カラムが同じ場合（identical）だけを100とし、それ以外は丸めても99にする。
5. 下限で絞り、並べる：共通のカラム数がminShared（既定3）以上、類似度がminSimilarity（既定50）以上のものを、類似度の高い順・共通のカラムの多い順・名前の順に並べ、limit件を返す。

サンプルでemployeeを基準にした場合の計算です。区分がtableのテーブルは12あり、基準を除くとN=11です。

共通の11カラムの重みは1.10＋1.79×2＋2.48×8≒24.56、相手にだけある3カラムは2.48×3≒7.46で、類似度は24.56÷(24.56＋7.46)≒77%です。基準にだけあるカラムが無く、相手にだけあるカラムがあるので、種別はsuperset（相手が基準の全カラムを持ち、追加がある。履歴・拡張の疑い）になります。

← find_similar_tables(table: employee) の text
{"base":"sample.employee","total":1,"tables":[{"database":"testdb","name":"sample.employee_history","logicalName":"従業員履歴",
  "similarity":77,"kind":"superset","sharedColumns":11,"onlyInOther":["history_id","valid_from","valid_to"],
  "typeMismatches":[{"column":"employee_name","base":"character varying(50)","other":"character varying(100)","difference":"size"}],
  "relatedToBase":true}]}

← find_similar_tables(columns: [attendance_id, work_date, note, employee_id]) の text
{"total":1,"tables":[{"database":"testdb","name":"sample.attendance_note","similarity":64,"kind":"overlap","sharedColumns":3,
  "onlyInBase":["employee_id"],"onlyInOther":["note_id"]}]}

← find_similar_tables(columns: [attendance_id, work_date]) の text（基準のカラムがminSharedに満たない）
{"total":0,"message":"基準のカラムは2個で、minShared（3）に満たないため、条件を満たすテーブルはありません。minSharedを2以下にしてください。"}

tableを指定した場合、引数schemaは探す範囲の絞り込みに使い、基準の特定には使いません。そのため、同名のテーブルが複数のスキーマにあるときはスキーマ名.テーブル名の形で指定させます。ObjectResolver.resolveには、複数に当てはまる場合の案内（ambiguityHint）を差し替えられる形があり、SimilarTableToolsはそれを使ってこの形を案内します。

7.13 テーブルの影響範囲（ImpactAnalyzer・get_impact）

テーブルを変更・削除する前に「何が壊れうるか」を調べるためのツールです。参照元のテーブル・ビュー・トリガー・関数は別々の窓口が持つため、これまではget_related_tables・get_table・get_function・list_triggersを組み合わせて調べる必要がありました。しかも「このテーブルを使う関数」は、tableUsageが関数からテーブルの向きしか返さないため、引く手段がありませんでした。get_impactは、これらをテーブルを起点に1回で集めます。

集めるだけで、スナップショットに無い値は足しません。複数の窓口にまたがるため入口はSchemaCatalog.impactOfで、集め方の規則はImpactAnalyzer（package-private。ClusterDetectorと同じ）が持ち、結果はTableImpact（record）に入ります。呼び出しのたびに求めます。

集め方は5つに分かれ、それぞれ結果の1つのキーになります。

1. 参照元（affected.referencedBy）：RelationGraph.relatedTables(table, 3, INCOMING)は、テーブルではなく関連を段数つきで返します。段1の関連をdirect（自己参照を含む。参照元のテーブル・種別・関連名の順）に、段1に現れないテーブルをindirect（最小の段数と、その段で見つけた関連の参照先via。段数・テーブルの順）に分けます。同じテーブルが段1と段2の両方に現れる場合はdirectだけに載せ、自テーブルはindirectに含めません。そのため、directの参照元（自テーブルを除く）とindirectを重複なく合わせた数は、list_tablesのimpactと一致します。
2. ビュー（affected.views）：TableCatalog.viewsReferencingを、ビューを参照するビューまで段ごとに繰り返します。同じビューは1度しか数えないため、循環していても止まります。経由したビューをviaで示します。
3. トリガー（affected.triggers）：自テーブルのtriggers()です。ビューを調べた場合は、INSTEAD OFトリガーが入ります。
4. 関数（affected.functions）：同じDBの全関数を関数名（FunctionOverloads）ごとに見て、オーバーロードの参考情報（FunctionTableUsages.find）のUsedTableが、自テーブルまたは2.で集めたビューを指すかをUsedTable.matchesで判定します。一致しなかったオーバーロードのうち、参考情報はあるが確かめきれないもの（動的SQL・読み切れなかった・解析不可）は、functions.unverifiedに理由とともに挙げます。
5. 依存先（dependsOn）：自テーブルのカラムについて、デフォルト値のnextvalが使うシーケンス（SqlNames.sequenceOfDefault）と、型に使われているスナップショットにあるユーザー定義型（SqlNames.typeOfColumn）を、使うカラムとともにまとめます。

関数の逆引きは、次の規則で求めます。

• 完全一致：参考情報は出力対象のカタログ上の名前で出力されるため、大文字小文字を区別して比べます（PostgreSQLでは、二重引用符で囲んだ"Employee"とemployeeが別のテーブルになり得ます）。ビューの逆引き（viewsReferencing）と揃えています。
• 確定と候補：スキーマが決まった名前は確定です。スキーマが決まらない名前（search_path等）は、候補のスキーマに自テーブルのスキーマが含まれる場合だけ候補とし、結果ではmatch: possibleとschemaResolutionで示します。1つのオーバーロードの中で同じテーブルへの一致が確定と候補にまたがる場合は、確定を採ります。
• 出力の単位は関数と経路：1行は関数名と経路（自テーブルか、使っているビューか）の組で、自テーブルとビューの両方を使う関数は2行になります（moreの総数もこの行数です）。同名のオーバーロードは1行にまとめ、一致したオーバーロードの引数をoverloadsに並べ、operationsは合算します。Oracleのパッケージで本体をまとめて抽出した場合（overloadsMerged）に、同じ内容が重複して並ぶのを防ぎます。候補になるのは、一致したすべてのオーバーロードが候補でしか一致しなかった場合です。確定のオーバーロードと候補のオーバーロードが混ざる場合はpossibleにならず、候補のオーバーロードの操作もoperationsに合算されるため、確定のように見えます（既知の制約で、FunctionUse.possibleのJavadocに書いてあります）。
• ビュー経由：参考情報には関数が使うビューも載るため、ビューだけを読む関数も拾います。その行には、使っているビューをviaで付けます。
• 実行するトリガー：TableCatalog.triggersCallingで、関数を実行するトリガーをcalledByTriggersに付けます。ビューのINSTEAD OFトリガー経由で書き込む関数が、ここで分かります。

参考情報は、動的SQL・呼び出している関数の中・出力対象外のテーブルを含みません。載っていないことが使われていないことを意味しないため、functions.coverageで調べがついた範囲を数えます。同じDBの関数・プロシージャを、参考情報の状態で分けます。

totalは、analyzed・unsupported・noInsight・staleの合計です。この区別は、結果のnotes（参考情報が無い・古い関数がある場合と、関数名を持たないトリガーがある場合に、対応を示す固定文）にも反映されます。

functions.unverifiedは、coverageのunsupportedと、analyzedの内数（withDynamicSql・incomplete）のうち、usagesに載らなかったオーバーロードを、function・arguments・reason（dynamicSql・incomplete・unsupported。複数当てはまる場合はこの順で先のものを採る）で返します。参考情報からは、自テーブルを使うかどうかを確かめきれない関数なので、AIはget_functionで定義本体を確かめます。テーブルとの関係は分からないため、同じDBの該当する関数をすべて挙げます。

サンプルのemployeeの結果です（既定のベースラインのスナップショットに、--previewの差分のベースラインの参考情報を合わせたもの。direct・triggers・usagesは一部を省略しています）。

← get_impact(table: employee) の text
{"table":"sample.employee","database":"testdb","type":"table",
 "affected":{
  "referencedBy":{
   "direct":[{"table":"sample.attendance","kind":"foreignKey","columns":["employee_id"],"referencedColumns":["employee_id"],"cardinality":"ONE_TO_MANY"},
             {"table":"sample.employee","kind":"foreignKey","columns":["manager_id"],…},  ← 自己参照
             …],
   "indirect":[{"table":"sample.attendance_note","depth":2,"via":"sample.attendance"}],"indirectTotal":1},
  "views":[{"view":"sample.employee_directory_view","type":"view"},
           {"view":"sample.attendance_monthly_view","type":"view","via":"sample.employee_directory_view"}],
  "triggers":[{"name":"trg_employee_audit","timing":"AFTER","events":["INSERT","DELETE","UPDATE"],"function":"sample.log_employee_change"},…],
  "functions":{"preview":true,
   "coverage":{"total":11,"analyzed":11,"unsupported":0,"noInsight":0,"stale":0,"withDynamicSql":1,"incomplete":0,"triggersWithoutFunction":0},
   "usages":[{"function":"sample.close_project","kind":"PROCEDURE","overloads":["IN p_project_id integer"],"operations":"U"},
             {"function":"sample.count_rows",…,"operations":"R","match":"possible","schemaResolution":"search_path","dynamicSql":["EXECUTE"]},
             {"function":"sample.employee_directory_insert",…,"operations":"C",
              "calledByTriggers":["sample.employee_directory_view.trg_employee_directory_insert"]},…]}},
 "dependsOn":{"sequences":[{"sequence":"sample.employee_employee_id_seq","columns":["employee_id"]}],
              "types":[{"type":"sample.employee_status_enum","category":"ENUM","columns":["status"]}]},
 "notes":[…]}

count_rowsは、動的SQL（EXECUTE）を含み、スキーマが決まらない名前（search_path）でしかemployeeに一致しないため、候補（possible）として示されます。Oracleのサンプルでは、EMPLOYEE_DIRECTORY_VIEWのINSTEAD OFトリガーがEMPLOYEEへINSERTしますが、トリガーの本体の中の参照は参考情報の対象外のため、functionsには現れません（SampleOracleImpactContractTestが確かめています）。PostgreSQLのサンプルのemployeeでは、確かめきれない関数が無いためunverifiedは出力されません。Oracleのサンプルでは、動的SQLを含むPROJECT_OPS.PURGE_AUDIT_LOGがreason: dynamicSqlとして挙がります。

sectionを指定しない概要では、各リスト（direct・indirect・views・triggers・usages・unverified）をImpactTools.MAX_LISTED（50）件までを決まった順で返します。超えたリストは、総数と続きの取り方をmore（section・total・nextOffset）だけで示します。共通のマスタ等では参照元がすぐに50件を超えるため、間接参照の総数indirectTotalは常に返します。

続きは、同じツールにsection（概要でそのリストを持つキーの名前。direct・indirect・views・triggers・usages・unverified）とoffset・limit（既定100、最大500）を指定して読みます。結果はsection・total・nextOffset・itemsで、itemsの形は概要の各リストと同じです。offset・limitだけを指定した場合は、無視せずエラーにします（sectionの指定漏れで、先頭のページを返してしまわないため）。

8ツールとソースの対応

ツールクラスの型

12のツールクラスはすべて同じ形をしています。1つ読めば残りは差分を見るだけです。

final class XxxTools {
  static final String GET_XXX = "get_xxx";      // ツール名。他クラスの案内文からも参照される
  private final SchemaCatalog catalog;

  List<SyncToolSpecification> specifications() {
    return List.of(readOnlyTool(GET_XXX, "表示名", "AIが読む説明",
        objectSchema(Map.of(/* 引数名 → JSON Schema */), List.of(/* 必須の引数 */)),
        this::getXxx));
  }

  private CallToolResult getXxx(ToolArguments arguments) {
    // 1. arguments から読む（一覧なら Page.read(arguments, Page.DEFAULT_LIMIT)。誤りは InvalidToolArgumentException）
    // 2. catalog に問い合わせる（名前なら ObjectResolver.resolve 経由）
    // 3. 出力 record を ToolResults.json(...) で返す
  }

  record GetXxxOutput(…) {}  // コンポーネント名がそのまま結果のJSONのキー
}

19ツールの対応表

件数・段数の上限

どれもAIのコンテキストを圧迫しないための上限です。上限はinputSchemaのmaximumだけに書かれ、範囲外はSDKが止めます（ToolArguments.optionalIntは範囲を検査しません）。

9ソースごとの役割

main配下のクラスと、テストの一覧です。

catalogには単体テストのカバレッジの最低基準（line 95%・branch 85%）があり、./gradlew buildで検査されます。E2Eは子プロセスで動くため計測の対象外です。

10変更するときの道しるべ

ツールを1つ足すとき

1. 関心が合う*ToolsクラスにreadOnlyTool(…)を足す。無ければクラスを作り、TableDefinitionTools.specifications()に並べる（並び順はクライアントに見える順）。
2. 検索・たどりのルールはcatalogの該当する窓口（TableCatalog・ObjectCatalog・ViewpointCatalog・RelationGraph）に置き、その窓口のテスト（TableCatalogTest等）で確かめる（カバレッジ基準の対象）。オブジェクトの種類を足すときはObjectCatalogを使い、SchemaCatalogには窓口を返すメソッドだけを足す。catalogにSDKやJacksonの型を持ち込まない（ArchitectureTestが検出する）。
3. 型・範囲（minimum/maximum）・enumはinputSchemaに書く。SDKがそれを検証するので、ToolArgumentsでは同じ検査を重ねず、スキーマで表せない検証だけを書く。検証の挙動はMcpServerProcessTestで確かめる（ハンドラを直接呼ぶテストではSDKの検証を通らない）。
4. 結果は*Outputのrecordにする。コンポーネント名がそのまま結果のキーになる。
5. McpServerMain.INSTRUCTIONSに使い分けを書き足す。
6. McpServerProcessTestのツール一覧、TableDefinitionToolsTest、docs/architecture/mcp-server.mdとdocs/usage/mcp-server.mdのツールの表を更新する。

スナップショットの形式が変わるとき

• 項目の追加は互換です。未知の項目は読み込みで無視され、get_*は元の1行を返すので、何もしなくてもAIに届きます。検索・逆引きに使うときだけ*Lineと*Entryに足します（例：referencedByViewsの逆引きのため、ビューのreferencedTablesをViewReferenceLine・TableEntryに足した）。古いcliのスナップショットには無い項目なので、nullや空を許して読みます。
• 互換性の無い変更は、cliのDatabaseSnapshot.FORMAT_VERSIONを上げ、SnapshotDirectoryReader.SUPPORTED_FORMAT_VERSIONを追従させます。観点ならViewpointsInsight.FORMAT_VERSIONとInsightsDirectoryReader.SUPPORTED_FORMAT_VERSIONです。
• cliのベースラインを出し直すと、SampleSnapshotContractTest・SampleInsightsContractTestが追従漏れを検知します（./gradlew :mcp-server:test）。

関数の利用テーブル（プレビュー）の参考情報が変わるとき

• 項目の追加は互換です。InsightsDirectoryReaderは未知の項目を無視します。get_functionの結果に出したいときだけ、FunctionTableUsageLine・FunctionTableUsageEntryに足し、FunctionTools.tableUsageで組み立てます。互換性の無い変更は、cliのFunctionTableUsagesInsight.FORMAT_VERSIONを上げ、InsightsDirectoryReader.SUPPORTED_FORMAT_VERSION（観点と共通）を追従させます。
• 定義本体のハッシュの求め方（UTF-8のSHA-256の小文字の16進）は、cliのFunctionTableUsagesInsightとmcp-serverのSnapshotDirectoryReaderに、同じものが1つずつあります。片方だけを変えると、すべての関数でtableUsageが返らなくなります。
• cliの--previewの差分のベースライン（docs/sample/postgres/output-preview）を出し直すと、SampleFunctionTableUsagesContractTestが追従漏れを検知します（./gradlew :mcp-server:test）。ベースラインのスナップショットは既定のoutput/snapshotから読みます。
• プレビューの機能なので、互換性の対象外です。tableUsageの説明（ツールの説明）に、参考値であることと、候補のスキーマに決めつけないことを書き続けます。

中間テーブルの判定・構造の類似の規則を変えるとき

• どちらも判定・計算の規則はcatalogの1クラス（JunctionDetector・SimilarTableFinder）にあり、結果を表すrecord（JunctionTable・SimilarTable）は規則を持ちません。規則を変えたらJunctionDetectorTest・SimilarTableFinderTestに場合を足します（カバレッジ基準の対象）。
• サンプルでの判定・結果はSampleSnapshotContractTestが確かめています。サンプルのDDLにテーブルを足すと、中間テーブルの判定・多対多の相手・類似の結果が変わることがあるため、このテストとガイドの例を見直します（employee_historyを足したときは、検索・関連の数・まとまり・ER図の例が変わった）。
• 判定の条件・結果の項目はツールの説明（TableTools・SimilarTableTools）とdocs/usage/mcp-server.mdにも書いてあるため、合わせて直します。どちらもスナップショットに入れない導出した値なので、cliの形式は変わりません。
• 中間テーブル以外のER上の区分を足すときは、ErRoleに値を足します。入力スキーマのenumはここから作られ、TableTools.tableFilterのswitchが網羅していないとコンパイルが通りません。

影響範囲の集め方を変えるとき

• 集め方の規則はcatalogのImpactAnalyzerにあり、結果を表すrecord（TableImpact・FunctionUse・FunctionCoverage）は規則を持ちません。ツール側（ImpactTools）は、record・JSONの形と上限、固定文のnotesだけを持ちます。
• affected.functionsは、cliの--previewの参考情報に依存するため、互換性の約束の対象外です。ツールの説明・結果のfunctions.preview・notes・docs/usage/mcp-server.mdの4か所に「参考値であり、載っていなくても使われていないとは限らない」ことを書き続けます。
• サンプルでの結果はSampleFunctionTableUsagesContractTest（PostgreSQL）とSampleOracleImpactContractTest（Oracle）が確かめています。サンプルのDDLに関数・トリガー・ビューを足すと、employeeの影響範囲が変わることがあるため、ベースラインを出し直したら、これらのテストを見直します（./gradlew :mcp-server:test）。
• direct・indirectの分け方を変えるときは、list_tablesのimpact（RelationGraph）との整合を保ちます。ImpactAnalyzerTestと契約テストが、自己参照を含めて確かめています。
• 関数の参考情報の状態を足すときは、FunctionTableUsages.FreshnessとFunctionCoverageの項目、ImpactToolsのCoverage・notesを合わせて直します。定義本体を読めば確かめられる状態なら、UnverifiedFunction.ReasonとUnverifiedRefにも足します。
• リストを足す・分けるときは、ImpactTools.Section（sectionの値とitems）、概要の上限（Affected・Functionsのhead）、moreの順を揃えます。sectionの値は、概要でそのリストを持つキーの名前と同じにします。sectionの値は、ツールの入力スキーマのenumに使われるため、変えると呼び出し側が壊れます。

ER図の表記・リソースを変えるとき

• ER図の表記（多重度の端点・線種・箱のカラム・エスケープ）は、cliのMermaidSupportとmcp-serverのMermaidErDiagramの両方にあります。片方だけを変えるとSampleErDiagramContractTestが失敗します。cliを変えたらベースラインを出し直してから、こちらを追従させます。
• リソースの中身はTableOutputBuilderをget_tableと共有しているため、get_tableの結果を変えるとリソースも変わります。リソースだけを変えたいときはTableDefinitionResourcesで分けます。
• リソースのname・description・URIの形は、MCPクライアントの絞り込み・表示の挙動に合わせて決めています。変えるときはdocs/architecture/mcp-server.mdの「リソース」の確認結果を読み、実機で確かめます。

やってはいけないこと

• System.outへの出力や、標準出力へ出すログ設定の追加。プロトコルが壊れます（System.out等への書き込みはArchitectureTestが検出しますが、ログの設定は検出しません）。
• immediateExecution(true)の削除。SDKの修正版が出るまでは、並行呼び出しで応答が止まります。
• cliのコードへの依存。両者の接点は、スナップショットと参考情報（insights/）の形式だけです。
• 関数の参考情報を、定義本体のハッシュで照らさずに返す。片方だけが出力し直された後の、古い抽出結果を最新のものとして答えてしまいます。

11用語集

スナップショット

cliがDBから取得した定義を、機械可読なJSON Linesで出力したもの。{output.path}/snapshot/{DB名}/に置かれる。mcp-serverの唯一の主な入力。

参考情報（insights）

スナップショットとは別に{output.path}/insights/へ出力される補助情報。観点と、関数が利用しているテーブル（cliを--previewで実行した場合だけ）。

観点（viewpoint）

業務ドメイン別にテーブルをまとめる切り口（例：人事管理）。1つのテーブルが複数の観点に所属できる。DB単位でスキーマを持たない。

利用しているテーブル（tableUsage）

関数・プロシージャの定義本体から、cliが機械的に抽出した、利用している出力対象のテーブルと操作（C・R・U・D）。get_functionがオーバーロードごとに返す参考値で、呼び出している関数・動的SQLの中の参照は含まない。

定義本体のハッシュ（definitionHash）

定義本体のSHA-256（小文字の16進）。参考情報が、今のスナップショットと同じ定義本体から抽出したものかを照らすために使う。

プレビューの機能

cliの--previewを付けたときだけ動く、精度・出力の形を固めている途中の機能。出力は互換性の対象外。

スキーマが決まらない名前

スキーマ修飾が無く、定義からは決まらないテーブル名。schemaResolution（search_path・current_user・synonym）と、候補のスキーマ（schemaCandidates）で返す。

中間テーブル（junction）・ER上の区分（erRole）

多対多をつなぐテーブル。主キーの列を、外すと覆えなくなる2本以上の外部キー・論理リレーションで過不足なく覆えるテーブルを、mcp-serverが機械的に判定する（推測）。erRole: junctionで表し、通常のテーブルは区分を持たない。

多対多（manyToMany）

中間テーブルを介してつながる2つのテーブルの関係。get_tableが相手のテーブルと中間テーブル（via）の組で返す。

構造の似たテーブル・類似度

カラム名の集合が似ているテーブル（find_similar_tables）。類似度は、汎用のカラムほど重みを下げた重み付きJaccard係数（%）で、100はカラムが同じ場合だけ。意味の類似ではない。

関連のまとまり（cluster）・ハブ

関連のつながりだけから推測したテーブルの組（list_table_clusters）。人が宣言する観点とは別物。ハブは、大きなまとまりを分けるために除いた、多くのテーブルから参照される共通のテーブル。

外部キー（foreignKey）

DBに実在する制約。関連の由来の1つ。

論理リレーション（logicalRelation）

DBに制約は無いが、サイドカーYAMLで宣言された関連。グラフでは外部キーと同じ辺として扱う。

参照するテーブル（referencedTables）

ビュー・マテリアライズドビューが参照するテーブル（ビューを含む）。cliがDBの依存関係から取得し、ビューの行にだけ入る。逆向きの「参照しているビュー」（referencedByViews）はmcp-serverが逆引きして求める。

メジャーバージョン（majorVersion）

DBMSの版の先頭の数字（例：PostgreSQLの16）。list_schemasが返し、AIが書けるSQLを判断する手がかりにする。古いcliのスナップショットには無い。

多重度（cardinality）

ONE_TO_MANY等。参照先（親）1行に対する参照元（子）の行数を表す。

オーバーロード

同じスキーマ・同じ名前で引数が異なる関数。FunctionOverloadsに束ねる。

ObjectKey・修飾名

DB名・スキーマ名・名前の組。結果ではスキーマ名.名前（qualifiedName）、候補の文言ではDB名:スキーマ名.名前で表す。

ホスト／クライアント／サーバー

MCPの3者。AIアプリ、その中の接続担当、道具の提供側。

トランスポート

メッセージの運び方。このサーバーはstdio（標準入出力）。

inputSchema

ツールの引数のJSON Schema。AIが引数を組み立てる手がかりであり、SDKの入力検証の基準でもある。

リソース

MCPでサーバーが出すデータ。このサーバーでは1テーブルが1リソース（dbxray://…）。AIが呼ぶツールと違い、利用者が@等で選んで会話に添付する。

Mermaid（erDiagram）

テキストで図を書く記法。cliの定義書のER図とget_er_diagramが同じ表記で出力する。

isError

ツールとしての失敗。AIが読んで直せる。JSON-RPCのerrorとは別物。

instructions

初期化の応答でサーバーがAIへ渡す使い方の説明。

immediateExecution

SDKのBuilderの設定。trueでツールを受信スレッド上で直列に実行する。