3gpp-mcp

3gpp-mcp

3GPP 仕様を LLM から利用できるようにする MCP（Model Context Protocol）サーバーです。

背景

3GPP 仕様は、モバイル通信や電気通信のエンジニアリングに欠かせない参考資料ですが、LLM が効果的に扱うのは困難です。

• 文書が多すぎる — 複数のシリーズにわたって数千もの仕様が存在するため、適切なものを見つけるのが困難です。
• 個々の文書が大きすぎる — 多くの仕様は数百ページに及び、一般的なコンテキストウィンドウの上限を大幅に超えます。
• Word ファイルで配布される — 仕様は .docx / .doc 形式で公開されており、テキスト処理には変換が必要です。
• 相互参照が多い — 仕様同士が頻繁に参照し合うため、単一の文書だけを読むと全体像を把握できません。
• 表や図に情報が詰め込まれている — 複雑な表やフロー図には重要な詳細が含まれています。このツールは表を Markdown に変換し、埋め込み画像を抽出して LLM が見られるようにします。
• バージョンが複雑 — 同じ仕様が複数の 3GPP リリースに存在するため、適切なバージョンを特定することが重要です。

このツールは .docx ファイルを解析し、セクションごとに内容を構造化して、全文検索（FTS5）に対応した SQLite データベースに格納することで、こうした課題に対処します。MCP サーバーは、検索、セクションの閲覧、相互参照の追跡を行うツールを公開し、エンジニアと同じように LLM が仕様を探索できるようにします。

なぜ RAG ではないのですか？

埋め込みベースの RAG は、文書に関する Q&A の精度を高める一般的な方法であり、3GPP 文書に特化した RAG システムも存在します（Telco-RAG、TelcoAI）。このツールは、よりシンプルな方法を採用しています。モデルの前段に検索パイプラインを構築する代わりに、検索とナビゲーションのツールをモデルに提供し、エンジニアと同じように仕様を探索させます。つまり、まず全文検索を行い、次にセクション階層と相互参照をたどります。検索は構造化されたセクションに対する単純な FTS5 検索なので、実行する埋め込みモデルやベクターデータベースは不要で、すべてが単一の SQLite ファイルに収まります。

TeleQnA で測定したところ、3 つのモデルファミリー全体で、3GPP 標準に関する質問の精度が 6.5～12.0 パーセントポイント向上しました。その大部分は、テキストが利用できることによるものです。同じデータベースに対する単一の BM25 クエリだけで、そのうち +7.8～+9.6 ポイントを達成します。ツール独自の検索が差を生むのは、回答が最初に取得された文章から 1 回以上の参照をたどった先にある質問です。仕様自体から生成したタスク（プロトコルコード、ASN.1 構造、5G SBI スキーマ）では、88～100% の割合で回答に成功し、正確な引用も行います。これは、すべてのタスクタイプとすべてのモデルで、同じ BM25 ベースラインを +26～+88 ポイント上回ります。BENCHMARK.md を参照してください。

はじめに

1. インストール

# Homebrew
brew install higebu/tap/3gpp-mcp

# ...or with Go 1.26+
go install github.com/higebu/3gpp-mcp/cmd/3gpp-mcp@latest

ビルド済みバイナリはリリースページからも入手できます。LibreOffice はオプションです（.doc から .docx への変換、および EMF/WMF 画像から PNG への変換に必要です）。

2. データベースを構築する

仕様をダウンロードしてデータベースに取り込みます。一時ファイルは各仕様の処理後に削除されるため、ディスク使用量を最小限に抑えられます。

# Download and import the latest version of every spec (all releases)
3gpp-mcp build --latest --db data/3gpp.db --convert-doc --convert-image

# ...or restrict to a single release
3gpp-mcp build --release 19 --db data/3gpp.db --convert-doc --convert-image

これにより、3GPP FTP アーカイブをスクレイピングし、ZIP ファイルをダウンロードして、.docx ファイルを展開・解析し、構造化されたコンテンツを SQLite データベースに挿入します。

3. MCP クライアントに登録する

Claude Code

claude mcp add --scope user 3gpp -- 3gpp-mcp serve --db /path/to/data/3gpp.db

VS Code / GitHub Copilot

code --add-mcp '{"name":"3gpp","command":"3gpp-mcp","args":["serve","--db","/path/to/data/3gpp.db"]}'

GitHub Copilot CLI

~/.config/github-copilot/cli-mcp.json に追加します（存在しない場合は作成してください）。

{
  "mcpServers": {
    "3gpp": {
      "command": "3gpp-mcp",
      "args": ["serve", "--db", "/path/to/data/3gpp.db"]
    }
  }
}

Codex CLI

codex mcp add --name 3gpp --command 3gpp-mcp --args serve --db /path/to/data/3gpp.db

Claude Desktop

設定ファイルに追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）。

{
  "mcpServers": {
    "3gpp": {
      "command": "3gpp-mcp",
      "args": ["serve", "--db", "/path/to/data/3gpp.db"]
    }
  }
}

4. ウェブビューアー（任意）

HTTP トランスポートに --web を追加すると、ブラウザーで仕様を閲覧できます。

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080 --web
# MCP endpoint: http://localhost:8080/mcp/
# Web viewer:   http://localhost:8080/

機能：フィルタリング付き仕様一覧、TOC サイドバー付きセクションビューアー、ページネーション付き全文検索、過去のバージョンの閲覧（バージョンは仕様ごとに一覧表示され、MCP ツールと同様に必要に応じてダウンロードされます）、バージョン比較（構造の概要とセクションごとの差分）、埋め込み画像、/meetings と /tdocs で必要に応じて取得される会議一覧とドキュメント（TDocs）、相互参照リンク、構文強調表示付き OpenAPI 定義、コンバーターが出力する LaTeX 数式 の KaTeX レンダリング、ダークモード、レスポンシブデザイン。コードブロックは記法に応じて構文強調表示されます（ASN.1、Diameter、SIP/RTSP、SDP、XML。コードブロックを参照）。

WebMCP

ブラウザーが W3C WebMCP API（document.modelContext。2026 年時点では Chrome のオリジントライアル）を提供している場合、ビューアーはページの読み込み時にすべての MCP ツールをブラウザーに登録します。これにより、ブラウザー内のエージェントが仕様データベースを直接検索できます。登録は /mcp/ エンドポイントへの同一オリジンの簡易パススルーであり、サーバー側の設定は不要です。また、この API を備えていないブラウザーには影響しません。オリジントライアル中は、Chrome のフラグ（chrome://flags）でローカルに有効にするか、共有環境にデプロイする場合は、フロントプロキシから Origin-Trial ヘッダーを配信してください。

デプロイ

Streamable HTTP

HTTP トランスポートはステートレスです。MCP プロトコルバージョン 2026-07-28（initialize ハンドシェイクなし、Mcp-Session-Id なし）をサポートし、古いクライアント（2024-11-05 から 2025-11-25）もリクエストごとのセッションを通じて引き続き動作します。

HTTP トランスポートでサーバーを起動します。

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

任意で Bearer トークン認証を有効にできます。

export THREEGPP_MCP_BEARER_TOKEN=$(openssl rand -hex 32)
3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

次に、HTTP 経由で接続するようクライアントを設定します。

{
  "mcpServers": {
    "3gpp": {
      "url": "http://your-server:8080",
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_TOKEN"
      }
    }
  }
}

--web を使用すると、MCP エンドポイントは /mcp/ に移動します。

systemd を使用した本番環境へのデプロイについては、examples/systemd/ を参照してください。

Docker

Dockerfile はマルチステージ構成で、リリース用のデータベースを直接ビルドします。SQLite データベース（セクション、OpenAPI 定義、埋め込み画像）を含む自己完結型のイメージが生成されます。ビルドコンテキストにビルド済みデータベースを用意する必要はありません。

# Build an image with the latest version of every spec baked in (default)
docker build -t 3gpp-mcp:latest .

# ...or restrict the database to a single release
docker build --build-arg RELEASE=19 -t 3gpp-mcp:rel19 .

# ...or cap the newest release, keeping specs that have no version in it
docker build --build-arg MAX_RELEASE=19 -t 3gpp-mcp:max-rel19 .

# stdio transport (Claude Code / IDE integration)
docker run --rm -i 3gpp-mcp:latest

# HTTP transport
docker run --rm -p 8080:8080 3gpp-mcp:latest serve --db /3gpp.db --transport http --addr :8080

RELEASE のデフォルト値は latest で、すべてのリリースにおける各仕様の最新バージョンが組み込まれます。--build-arg RELEASE=<n>（例：19）を設定すると、データベースを単一のリリースに限定できます。または --build-arg MAX_RELEASE=<n> を設定すると、そのリリースにバージョンがない仕様を除外せずに、最新リリースの上限を指定できます。この 2 つを併用することはできません。

Cloud Run

Cloud Run で実行する方法については、cloudbuild.yaml（ビルド＋プッシュ＋デプロイ）と service.yaml（Cloud Run サービス仕様）を参照してください。

ツール

以下の各ツールには、シェルでの利用やスクリプト作成に使える CLI 版もあります（list_specs → 3gpp-mcp list-specs など）。コマンドリファレンスのクエリーコマンドを参照してください。

仕様の閲覧

ツール	説明	主なパラメーター
list_specs	利用可能な仕様を一覧表示します（ページネーション対応）	series（任意）：シリーズ番号で絞り込みます。例："23"。query（任意）：仕様 ID のプレフィックス。例："38.21"。limit、offset
list_versions	仕様のバージョンと、それぞれの参照先を一覧表示します	spec_id（必須）：例："TS 23.501"
get_toc	仕様の目次を取得します	spec_id（必須）、version
get_section	セクションの内容を取得します（ページネーション対応）	spec_id、section_number（必須）、version、include_subsections、offset、max_lines、max_chars
compare_versions	仕様の 2 つのバージョンを比較します。構造の要約、またはセクションのテキスト差分を取得できます	spec_id、old_version（必須）、new_version、section_number、include_subsections、context_lines、offset、max_lines、max_chars

get_toc、get_section、search の結果には、ページネーションされたレスポンスのすべてのページで、対象の仕様とそのバージョンが示されます。

過去のバージョン

データベースには、仕様ごとに 1 つのバージョンが格納されています。別のバージョンを参照するには、get_section または get_toc に version を渡します。version には、ドット区切り形式（15.8.0）、アーカイブトークン（f80）、リリース指定子（Rel-15 または 15。該当するリリース内で最新のバージョンが選択されます）、または latest を指定できます。リリース指定子と latest は 3GPP アーカイブを参照して解決されるため、オンデマンドの取得が必要です（--no-fetch では機能しません）。compare_versions の old_version と new_version も同じ形式を受け付けます。new_version の既定値はデータベース内のバージョンです。

データベースにないバージョンは、初回使用時に 3GPP アーカイブからダウンロードされ、変換されます。大規模な仕様では数分かかることがあります。呼び出しの予算時間内に処理が完了しない場合、ツールはその旨を通知し、後で同じ呼び出しを再実行すると内容が返されます。結果はサイズ制限付きのキャッシュ（serve を参照）に保存され、メインデータベースとは分離されています。そのため、次の制限があります。

• search の対象はデータベース内のバージョンのみです。リリースをまたいだ全文検索には対応していません
• get_references がデータを持つのはデータベース内のバージョンのみです。アーカイブされたバージョンから読み取ったセクションには、その旨がヘッダーに示されます
• get_image と list_images も version を受け付けます。アーカイブされたバージョンの画像は、初回使用時に個別にダウンロードされます（バージョンごとに追加のアーカイブダウンロードが 1 回必要で、同じ再試行動作が適用されます）。サーバーに LibreOffice がインストールされている場合、EMF/WMF の図は PNG に変換されます
• セクション番号はリリース間で変わることがあります。古いバージョンのセクションを読む前に get_toc で確認してください

検索

ツール	説明	主なパラメーター
search	すべての仕様を対象に全文検索します	query（必須）、spec_ids（任意）、limit、offset

search ツールは SQLite FTS5 のクエリ構文に対応しています。

• フレーズ検索："service based interface"
• 論理演算子：AMF AND UE、AMF OR SMF、NOT deprecated
• 正の語句の後に除外条件を指定：handover -conditional
• 前方一致：handov*
• 列フィルター：title:authentication、content:handover
• 近接検索：NEAR(AMF UE, 5)

ハイフンまたはドットを含む語句（IMS-AKA、38.101）は自動的に引用符で囲まれるため、手動でエスケープする必要はありません。

相互参照

ツール	説明	主なパラメーター
get_references	仕様間および RFC 間の相互参照を取得します	spec_id（必須）、section_number（"outgoing" の場合は必須）、direction（"outgoing" または "incoming"）、include_subsections、offset

OpenAPI 定義

ツール	説明	主なパラメーター
list_openapi	利用可能な OpenAPI 定義を一覧表示します	spec_id（任意）：仕様で絞り込みます。例："TS 29.510"
get_openapi	OpenAPI 定義を取得します（ページ分割）	spec_id、api_name（必須）、path、schema、offset、max_lines
search_openapi	OpenAPI 定義を全文検索します	query（必須）、spec_ids、api_name、kind（"schema" または "operation"）、include_body、limit、offset

search_openapi は、search が使用するものとは別の独自の FTS5 インデックスを使用します。 search は仕様の条項テキストを対象とし、OpenAPI コンテンツは返しません。 search_openapi は OpenAPI コンテンツのみを対象とします。1件の検索結果は1つのドキュメントではなく、1つの定義です。つまり、components.schemas のスキーマ、または1つのパスに対する1つの HTTP メソッド（PUT /nf-instances/{nfInstanceID} のような名前）です。そのため、どの API ドキュメントで定義されているかが分からなくても、データ型やエンドポイントを見つけてから、get_openapi で全体を読み取ることができます。クエリが単一の装飾なしの用語の場合、その名前と完全に一致する定義が最初に表示されます。そのため、NFProfile で検索すると、参照先としてのみ含まれているスキーマよりも先に、NFProfile スキーマが返されます。

スキーマのインデックス対象テキストには、items や additionalProperties を介した場合も含め、$ref の1段階の展開が含まれます。5G SBI 定義の関係性の多くはこの方法で記述されているため、参照型のフィールドを、その型を使用するスキーマから検索できます。2段階先の型はそのテキストには含まれません。search とは異なり、このインデックスではステミングは行われず、識別子は記載どおりに照合されます。また、-、.、_ はトークンの区切りとして扱われるため、Nnrf_NFManagement は NFManagement でも、/nf-instances は instances でも見つかります。camelCase は分割されません。

インデックスは build と update の最後に作成されます。import と import-dir はインデックスに影響しません。YAML ファイルはアーカイブの zip に含まれているため、.docx をインポートしても、インデックス対象は変わりません。このツールの追加前に構築されたデータベースにはインデックスがありません。既存のデータベースに追加するには、build-openapi-index を実行してください。

ASN.1 定義

ツール	説明	主なパラメーター
get_asn1	名前を指定して ASN.1 の割り当てを取得します。1 つの仕様内またはすべての仕様を対象に検索できます。または、仕様の割り当て名を一覧表示します	spec_id（省略可能。省略すると、すべての仕様を対象に name を検索します）、name（割り当て名。例：AMF-UE-NGAP-ID。spec_id を指定しない場合は必須）、version（spec_id が必要）、offset、max_lines、max_chars

ASN.1 で規定されたプロトコル（RRC TS 38.331/36.331、NGAP TS 38.413、S1AP TS 36.413、XnAP、F1AP など）では、-- ASN1START / -- ASN1STOP マーカーの間に ASN.1 が記述されており、コンバーターはこれを ```asn1 フェンスとして保存します（コードブロックを参照）。get_asn1 は、これらのフェンスからすべてのトップレベルの割り当て（型、定数、情報オブジェクト）を抽出します。

name を指定すると、その割り当ての全文と、それを定義しているセクションが返されるため、回答を引用できます。すべての IE が 1 つの条項に定義されているプロトコルでは、これは重要です。NGAP の IE 定義条項は数百キロバイトにもなり、get_section で取得できる 1 ページよりはるかに大きい一方、「ASN.1 ではここでどの範囲が許可されているか」という問いに答える定義は数行です。照合では大文字・小文字や区切り文字を無視するため、IE の表にある AMF UE NGAP ID から ASN.1 の AMF-UE-NGAP-ID が見つかります。一致する名前がない場合は、類似する名前が提案されます。同じ名前が複数回定義されている場合は、それぞれの定義が、個別のソース行とともにすべて返されます。

どの仕様で名前が定義されているかわからない場合は、spec_id を省略してください。データベースのビルド時に作成される名前インデックスを使って、データベース内のすべての仕様から名前が検索されます（build、update、import、import-dir はいずれもインデックスを更新します）。間違った仕様を指定して検索すると、その名前が実際に定義されている場所が通知されます。このツールの導入前にビルドされたデータベースにはインデックスがありません。既存のデータベースに build-asn1-index を追加してください。仕様をまたいだ検索で対象となるのは、データベース内のバージョンのみです。アーカイブ版を読むには spec_id（および任意で version）を指定してください。この場合も、get_section と同様に必要に応じてダウンロードされます。

spec_id を指定し、name を指定しない場合は、定義しているセクションごとにグループ化して、すべての割り当て名を一覧表示します。

埋め込み画像

ツール	説明	主なパラメーター
list_images	仕様に埋め込まれた画像を一覧表示します	spec_id（必須）、version（省略可能）
get_image	LLM で表示できる、埋め込み画像の Base64 データを取得します	spec_id、name（必須）：画像ファイル名、version（省略可能）

PNG/JPEG/GIF/WebP 画像は LLM で直接表示できます。EMF/WMF 画像（3GPP の図のほとんどがこの形式です）は、デフォルトで未加工のデータとして保存されます。ビルド時に LibreOffice を使って PNG に変換するには、--convert-image を使用してください。

画像形式にかかわらず、図はセクション本文内で 1 つの表記法を使って参照されます。本文では ![Figure](image://NAME?w=&h=)、表のセル内では <img src="image://NAME?w=&h=" ...> を使用します。その NAME を get_image に渡してください。元のファイル名（image3.emf）と変換後のファイル名（image3.png）のどちらでも解決できます。

会議ドキュメント（TDocs）

ツール	説明	主なパラメーター
list_meetings	グループの会議を新しい順に一覧表示します。コード、日付、TDoc の範囲、FTP フォルダーが含まれます。グループを指定しない場合は、対応しているグループを一覧表示します	group（R1、RAN1、SA2 など）、limit、offset（すべて任意）
list_tdocs	会議の公式 TDoc リストから、種類、ステータス、出典、アジェンダ項目、タイトル、CR／LS の詳細を含むドキュメントを一覧表示します	meeting（必須）：R1-123、RAN1#123、またはフォルダーのパス。group、agenda_item、type、status、source、spec、query、details、limit、offset（すべて任意）
get_tdoc	会議ドキュメント（TDoc）を Markdown として読み取ります	tdoc_id（必須）：TDoc 番号（R1-2509715）または FTP パス（tsg_ran/WG1_RL1/TSGR1_123/Report/Final_Minutes_report_RAN1#123_v100.zip）。meeting、section_number、offset、max_lines、max_chars（すべて任意）
get_meeting_report	会議名を指定して、会議の報告書（議事録）または最終アジェンダを読み取ります	meeting（必須）。group、kind（report。デフォルト）、または agenda、section_number、offset、max_lines、max_chars（すべて任意）

TDoc は、3GPP 会議の作業ドキュメントです。寄書、変更要求（CR）、リエゾンステートメント（LS）、アジェンダ、会議報告書が含まれます。TDoc 番号は、グループの DynaReport 会議ページ（https://www.3gpp.org/dynareport?code=Meetings-R1.htm とその関連ページ）でTDoc番号の範囲から特定され、その会議の Docs/ フォルダーからダウンロードされ、初回使用時に変換されます。番号が掲載されている範囲に含まれない場合は、meeting（R1-123、RAN1#123、TSGR1_123）を渡してください。会議報告書など、TDoc 番号のないドキュメントは、代わりに https://www.3gpp.org/ftp/ 以下のパスで指定します。

list_tdocs は会議の公式 TDoc リストを表示します。各ドキュメントの種類、ステータス（agreed、noted、revised など）、出典、アジェンダ項目、改訂履歴を確認でき、CR については仕様、CR 番号、カテゴリー、LS については宛先も表示します。フィルターを指定しない場合、出力の先頭にアジェンダ項目とドキュメント数が表示されます。query は、その会議に範囲を限定して、タイトル、出典、概要、アジェンダ項目の説明、作業項目を全文検索します。会議が最近のものである間、リストは毎日更新されます。

変換済みドキュメントと TDoc リストは、サイズ制限付きの専用キャッシュ（tdocs.db。詳細は --tdoc-cache を参照）に保存されます。メインデータベースとは別で、TDoc がメインデータベースにインポートされることはなく、search の対象にもなりません。

get_meeting_report は会議名だけで、会議の承認済み報告書または最終アジェンダを読み取ります。出力ヘッダーには解決されたドキュメントが表示され、各セクションにはドキュメントに記載された番号が付くため、アジェンダ項目のセクションを番号で読み取れます。

注意事項：

• CR の表紙と LS のヘッダーは preamble という名前のセクションにあり、出力の先頭にも要約が表示されます。CR では仕様、CR 番号、カテゴリー、リリース、出典、変更の理由と概要、影響を受ける条項、CR の記述が準拠するバージョンの変更条項を読み取る get_section の呼び出しが含まれます。LS では送信者、宛先、返信対象の LS、リリース、作業項目、連絡先が含まれます。Web ビューアーにも同じブロックが表示され、変更された各条項と CR の各番号付きセクションから仕様にリンクしています。
• ダウンロードに添付ファイルが含まれる場合、変換されるのはメインの Word ファイルのみです。それ以外のファイルは出力ヘッダーに一覧表示されるため、読者はそれらの存在を確認できます。
• .doc ドキュメントの実行時には LibreOffice（soffice）が必要です。.pptx、.xlsx、.pdf は変換されず、ツールは代わりにファイル一覧を報告します。
• 対応グループ：RAN および RAN1-6、SA および SA1-6、CT および CT1、CT3、CT4、CT6、GERAN。TDoc のプレフィックスは RP、R1-R6、SP、S1-S6、CP、C1、C3、C4、C6、GP です。

コードブロック

セクションのテキストにはタグ付きコードフェンスが含まれているため、LLM と Web ビューアーの両方で記法を判別できます。

フェンス	内容
```asn1	-- ASN1START / -- ASN1STOP マーカーで囲まれた ASN.1 モジュール
```diameter	Diameter コマンドとグループ化された AVP 定義（RFC 6733 CCF）
```xml	XML スキーマ、XML 本文の例、DTD
```sip	SIP/RTSP メッセージの例
```sdp	単独の SDP セッション記述
```latex	Word OMML から変換された単独の数式
```	ソースドキュメントでコードとして書式設定されたその他すべて

数式

Word の数式（OMML）は 3 種類の記法で LaTeX に変換されるため、単独でも文中でも読みやすくなっています。

記法	用途
```latex フェンス	数式だけで構成される段落。数式番号は \tag{7.3-1} として保持され、右揃えの (7.3-1) として表示されます。
$$...$$	表のセルやリスト項目内など、フェンス付きブロックにできないディスプレイ数式。
$...$	文中の数式。

インデント

3GPP の文章では、入れ子になった要件や条件のリスト、複数レベルの定義など、構造をインデントで表します。本文段落の先頭の空白は改行なしスペース（U+00A0）として保持されます。ソースドキュメントのタブ 1 つは 4 つになります。通常のタブや先頭の 4 つ以上のスペースを使うと Markdown でインデント付きコードブロックになり（その中では <sub> などの HTML が解釈されません）、一方、改行なしスペースを使えば、どのレンダラーでも視覚的な階層を保ち、全文検索の妨げにもなりません。

ヒント

モデルにツールを使うよう指示する

サーバーを接続しただけでは、モデルがそれを参照するとは限りません。モデルによっては、選択肢があると 3GPP に関する質問に記憶だけで回答します。ベンチマークでは、Claude Sonnet 5 は TeleQnA の質問の 40% で検索を省略し、GPT 5.6 Luna は 60% で省略しました。そうした質問ではツールの効果はありませんでした。クライアントのシステムプロンプトに一文加えるだけで、この判断の余地をなくせます。効果が測定された文言は次のとおりです。

記憶だけで回答しないでください。まず仕様を検索し、すでに答えを知っていると確信している場合でも、取得したテキストに基づいて回答してください。

この一文により、Luna の検索省略率はゼロになり、効果は +5.9 ポイントから +12.0 ポイントに上がりました。すべての質問をすでに検索していたモデルには変化がなく、ツールを接続していない場合には効果がありません。これは答えをこっそり与えるのではなく、検索を必須にするものです。同じ趣旨の、より強い運用ルールとして「3GPP に関するすべての回答は、これらのツールで取得した条文のテキストに基づき、条文を引用すること」も妥当ですが、ベンチマークで測定されたのは上記の一文のみです。

リリースごとにデータベースを分ける

リリースをまたいだ簡単な比較には、compare_versions と version パラメーターを使えばよく、追加設定は不要です。特定のリリースを継続して利用する場合は、リリースごとに別のデータベースを構築すると効果があります。全文検索の search、get_references、OpenAPI 定義は、データベースに組み込まれたバージョンのみを対象とするため、リリース専用のデータベースを用意すれば、オンデマンドでダウンロードすることなく、そのリリースのこれら 3 つすべてを利用できます。

# Build databases for different releases
3gpp-mcp build --release 18 --db data/3gpp-rel18.db --convert-doc --convert-image
3gpp-mcp build --release 19 --db data/3gpp-rel19.db --convert-doc --convert-image

--release は、そのリリースにバージョンがある仕様だけを残すため、以前のリリースで凍結された仕様（たとえば TS 34.108）はデータベースにまったく含まれません。そうした仕様を失わずにリリースを固定するには、代わりに選択範囲に上限を設定します。すべての仕様が、その上限以下で最も新しいバージョンで取得されます。

# Everything as of Release 19: specs with no Rel-19 version fall back to their
# newest older version rather than dropping out.
3gpp-mcp build --max-release 19 --db data/3gpp-rel19.db --convert-doc --convert-image

# Keep the cap when refreshing the database later.
3gpp-mcp update --max-release 19 --db data/3gpp-rel19.db --convert-doc

それぞれを個別の MCP サーバーとして登録します。

claude mcp add --scope user 3gpp-rel18 -- 3gpp-mcp serve --db /path/to/data/3gpp-rel18.db
claude mcp add --scope user 3gpp-rel19 -- 3gpp-mcp serve --db /path/to/data/3gpp-rel19.db

仕様を最新の状態に保つ

update コマンドを使って、データベースにすでに登録されている仕様に新しいバージョンがあるか確認します。

3gpp-mcp update --db data/3gpp.db --convert-doc --convert-image

コマンドリファレンス

serve

MCP サーバーを起動します。

フラグ	説明	デフォルト
--db	SQLite データベースのパス	3gpp.db
--transport	トランスポートの種類：stdio または http（環境変数：THREEGPP_MCP_TRANSPORT。PORT が設定されている場合、デフォルトは http）	stdio
--addr	HTTP のリッスンアドレス（環境変数：THREEGPP_MCP_ADDR、または PORT を :$PORT として解釈）	:8080
--bearer-token	HTTP 認証用のベアラートークン（環境変数：THREEGPP_MCP_BEARER_TOKEN）
--web	MCP サーバーと併せてウェブビューアーを有効にします（HTTP トランスポートのみ）	false
--no-fetch	データベースにない仕様バージョンのオンデマンド取得を無効にします	false
--version-cache	オンデマンドバージョンキャッシュのパス	$XDG_CACHE_HOME/3gpp-mcp/versions.db（未設定の場合は ~/.cache/3gpp-mcp/versions.db）
--version-cache-mb	バージョンキャッシュのサイズ上限（MB）。0 の場合は最後に取得したバージョンのみを保持し、-1 の場合は無制限です（環境変数：THREEGPP_VERSION_CACHE_MB）	1024
--tdoc-cache	オンデマンドの会議文書（TDoc）キャッシュのパス	$XDG_CACHE_HOME/3gpp-mcp/tdocs.db（未設定の場合は ~/.cache/3gpp-mcp/tdocs.db）
--tdoc-cache-mb	会議文書キャッシュのサイズ上限（MB）。0 の場合は最後に取得した文書のみを保持し、-1 の場合は無制限です（環境変数：THREEGPP_TDOC_CACHE_MB）	512
--fetch-budget	呼び出し元に再試行を求めるまでに、ツール呼び出しがオンデマンド取得を待つ時間（環境変数：THREEGPP_FETCH_BUDGET）	60s

バージョンキャッシュは別個の SQLite ファイルであるため、メインデータベースは読み取り専用のままで、追加バージョンによって汚染されることはありません。会議文書キャッシュも別のファイルで、サイズ上限があり、同じ方法で古いデータが削除されます。--no-fetch は両方を無効にします。scratch ベースのコンテナーイメージのように、読み取り専用または一時的なファイルシステムでキャッシュを作成できない場合、サーバーは警告をログに記録し、オンデマンド取得を無効にして実行します。それ以外の機能はすべて引き続き利用できます。キャッシュされたバージョンは、サイズ上限を超えると最も長く使われていないものから削除されます。

HTTP トランスポートでは、認証なしで 200 OK を返す GET /health も公開されます。このパスは、プラットフォームのヘルスチェック（Cloud Run、Sakura AppRun、Kubernetes の liveness/readiness プローブなど）に使用してください。

build

仕様をダウンロードし、データベースにインポートします（初期セットアップに推奨）。別名：pipeline。

フラグ	説明	デフォルト
--db	出力 SQLite データベースのパス	3gpp.db
--release	特定のリリースの仕様を処理します（例：19）
--max-release	選択対象のリリース上限を指定します（例：19）。各仕様について、そのリリース以下で最新のバージョンを選択します
--latest	各仕様の最新バージョンを選択します（ほかの選択条件を指定しない場合に使用）	false
--spec	特定の仕様を処理します（例：23.501）
--series	シリーズで絞り込みます。カンマ区切りで指定します（例：23,29）
--workers	並列ワーカー数	NumCPU
--convert-doc	LibreOffice を使って .doc ファイルを .docx に変換します	false
--convert-image	LibreOffice を使って EMF/WMF 画像を PNG に変換します	false
--spec-list	アーカイブをスクレイピングする代わりに、ファイルから仕様リストを読み込みます（選択条件の指定は引き続き必要です）
--no-cache	仕様リストのキャッシュを無効にします	false
--scrape-workers	仕様一覧のスクレイピング時の並列数（0 = 自動）	0
--timeout	HTTP タイムアウト	30s

--spec-list を含め、--release、--max-release、--latest、--series、--spec のいずれかを指定する必要があります。ファイルには候補エントリーが含まれ、選択条件によって絞り込まれます。

--release と --max-release では、指定されたリリースにバージョンがない仕様の扱いが異なります。--release 19 はその仕様を除外し、--max-release 19 は上限以下で最新のバージョンを選択します。この2つは併用できません。

その他のコマンド

• download — 変換せずに仕様書をダウンロードします（--output-dir、デフォルトは specs）。build と同様に、--release、--max-release、--latest、--series、--spec のいずれかが必要です。
• import — 単一の .docx ファイルをデータベースにインポートします。エイリアス：convert。使用方法：3gpp-mcp import --db data/3gpp.db path/to/spec.docx
• import-dir — ディレクトリ内のすべての .docx ファイルをデータベースにインポートします。エイリアス：convert-dir。使用方法：3gpp-mcp import-dir --db data/3gpp.db ./specs
• update — データベース内の仕様書を最新バージョンに更新するか、--max-release で上限を指定して更新します。
• build-openapi-index — 既存のデータベースの OpenAPI 検索インデックスを再構築します。build と update は自動で再構築するため、このコマンドは search_openapi が存在する前に構築されたデータベースにインデックスを追加する場合に使用します。serve はデータベースを読み取り専用で開くため、その場で作成することはできません。
• build-asn1-index — 既存のデータベースの ASN.1 名称インデックスを再構築します。build、update、import、import-dir は自動で再構築するため、このコマンドは get_asn1 が存在する前に構築されたデータベースにインデックスを追加する場合に使用します。
• completion — シェル補完スクリプトを出力します：3gpp-mcp completion bash（または zsh、fish）

上限はデータベースに保存されないため、--max-release 19 を指定して構築したデータベースを更新するには、update にも同じフラグが必要です。指定しない場合、すべての仕様書がアーカイブ内の最新リリースまで更新されます。上限を指定すると、更新によって仕様書はどちらの方向にも移動するため、すでに構築済みの上限なしデータベースも上限まで戻されます。すべてのバージョンが上限を超える仕様書は、上限付きデータベースに含まれるバージョンがないため削除されます。アーカイブの一覧にない仕様書はそのまま残されます。一覧の取得失敗は、仕様書が取り下げられた場合と同じ状態に見えるためです。

クエリコマンド

クエリコマンド（list-specs、list-versions、get-toc、get-section、 get-asn1、compare-versions、search、list-openapi、get-openapi、 search-openapi、get-references、list-images、get-image、 list-meetings、list-tdocs、get-tdoc、get-meeting-report）は、 MCP の読み取りツールと 1 対 1 で対応しているため、MCP クライアントを使わずに シェルからデータベースを調査し、スクリプトを実行できます：

3gpp-mcp search --db data/3gpp.db --limit 3 "AMF AND authentication" | jq '.results[].section_number'
3gpp-mcp get-section --db data/3gpp.db "TS 23.501" 5.15.2 | less
3gpp-mcp list-tdocs --db data/3gpp.db --type CR --status agreed --spec 38.214 R1-123
3gpp-mcp get-tdoc --db data/3gpp.db R1-2509715 | less
3gpp-mcp get-meeting-report --db data/3gpp.db RAN1#123 | less

すべてのコマンドに共通するルール：

• フラグは位置引数より前に指定する必要があります。
• JSON の結果は整形され、ページ分割されずに標準出力へ出力されます。jq、 head、less にパイプで渡せます。警告と進捗メッセージは標準エラー出力へ送られるため、標準出力は解析可能な状態に保たれます。
• --version を受け取るコマンド（および compare-versions）は、MCP ツールと同じバージョン形式（15.8.0、f80、Rel-15、latest）に対応し、再試行を求める代わりに、オンデマンドのダウンロードが完了するまで待機します。Ctrl-C で中断できます。serve の取得フラグ（--no-fetch、--version-cache、--version-cache-mb、--fetch-budget）を共有します。バージョンを指定しないクエリではバージョンキャッシュは作成されません（list-versions はキャッシュがすでにある場合に cached の利用可否を報告するため読み取りますが、作成はしません）。
• get-tdoc は TDoc 番号または FTP パスと、任意のセクション（CR の表紙または LS のヘッダー用の preamble）、および --meeting を受け取ります。list-meetings はグループ、list-tdocs は会議とツールと同じフィルター（--agenda-item、--type、--status、--source、--spec、--query、--details）を受け取ります。get-meeting-report は会議、任意のセクション、および議題用の --kind agenda を受け取ります。この 4 つのコマンドは serve の会議文書用フラグ（--no-fetch、--tdoc-cache、--tdoc-cache-mb、--fetch-budget）を共有し、独自のキャッシュのみを読み取ります。バージョンキャッシュは読み取りません。
• すべてのコマンドで --db を指定できます（デフォルトは 3gpp.db）。

環境変数

変数	説明
THREEGPP_MCP_TRANSPORT	serve のトランスポート（stdio または http）。--transport で上書きされます
THREEGPP_MCP_ADDR	serve の HTTP リッスンアドレス。--addr で上書きされます
THREEGPP_MCP_BEARER_TOKEN	HTTP トランスポート認証用のベアラートークン
PORT	PaaS の慣例（Cloud Run / Heroku）。serve はデフォルトで :$PORT の HTTP トランスポートを使用します
THREEGPP_VERSION_CACHE_MB	オンデマンドのバージョンキャッシュのサイズ上限（MB、デフォルト 1024）
THREEGPP_TDOC_CACHE_MB	オンデマンドの会議文書（TDoc）キャッシュのサイズ上限（MB、デフォルト 512）
THREEGPP_FETCH_BUDGET	オンデマンド取得の完了をツール呼び出しが待機する時間（デフォルト 60s）
THREEGPP_MAX_ZIP_SIZE_MB	ZIP ダウンロードの最大サイズ（デフォルト 512）
THREEGPP_CACHE_TTL_HOURS	仕様リストキャッシュの有効期間（時間、デフォルト 24）
THREEGPP_LISTING_RETRY_MS	アーカイブ一覧の取得試行間の初期待機時間（ミリ秒、デフォルト 1000）
XDG_CACHE_HOME	XDG Base Directory 仕様に準拠したキャッシュディレクトリのルート