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 で測定した結果、3GPP 標準に関する質問の精度が 3 つのモデルファミリー全体で 6.5 ～ 12.0 パーセントポイント向上しました。そのほとんどは単にテキストが存在することによるものです。同じデータベースに対する単一の BM25 クエリだけで +7.8 ～ +9.6pt の向上が得られています。このツール独自の検索は、答えが最初に取得されたパッセージから 2 ホップ以上離れている質問で差を生み出します。仕様自体から生成されたタスク（プロトコルコード、ASN.1 構造、5G SBI スキーマ）では、すべてのタスクタイプとすべてのモデルで 88 ～ 100% の正解率（かつ正しく引用）を達成し、同じ BM25 ベースラインを +26 ～ +88 ポイント上回っています。詳細は BENCHMARK.md を参照してください。

Related MCP server: mcp-docs

はじめに

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. Web ビューア（オプション）

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/

機能：フィルタリング可能な仕様一覧、目次サイドバー付きセクション表示、ページネーション対応の全文検索、過去バージョンの参照（バージョンは仕様ごとに一覧表示され、MCP ツールと同様にオンデマンドでダウンロード）、バージョン比較（構造的な概要とセクションごとの差分）、埋め込み画像、相互参照リンク、シンタックスハイライト付き OpenAPI 定義、コンバーターが出力する LaTeX 数式 の KaTeX レンダリング、ダークモード、レスポンシブデザイン。コードブロックは表記法に応じてシンタックスハイライトされます — ASN.1、Diameter、SIP/RTSP、SDP、XML（コードブロック 参照）。

WebMCP

ブラウザが W3C WebMCP API（document.modelContext、2026 年時点では Chrome origin trial）を提供している場合、ビューアはページ読み込み時にすべての MCP ツールをブラウザに登録するため、ブラウザ内のエージェントが仕様データベースを直接クエリできます。この登録は、同じオリジン内の /mcp/ エンドポイントへのシンプルなパススルーです。サーバー側で設定するものはなく、API がないブラウザには影響しません。Origin trial 期間中は、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 など）。詳しくはコマンドリファレンスのクエリコマンドを参照してください。

仕様の参照

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 回発生し、同じリトライ動作）。EMF/WMF 図は、サーバーに LibreOffice がインストールされている場合に PNG に変換されます。

• セクション番号はリリース間で移動することがあります。古いバージョンのセクションを読む前に、そのバージョンの get_toc で確認してください。

検索

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）は自動的に引用符で囲まれるため、手動エスケープは不要です。

相互参照

OpenAPI定義

search_openapi は独自のFTS5インデックスを使用し、search が使用するものとは別です： search は仕様の節テキストを対象とし、OpenAPIコンテンツを返しません。 search_openapi はOpenAPIコンテンツのみを対象とします。1ヒットは1文書ではなく1定義です — components.schemas のスキーマ、または1つのパスの1つのHTTPメソッド（PUT /nf-instances/{nfInstanceID} のように命名）— そのため、どのAPI文書で定義されているかを知らなくてもデータ型やエンドポイントを見つけられ、get_openapi で全文を読むことができます。単一の裸の用語であるクエリは、その名前と完全に一致する定義を最初にランク付けするため、NFProfile は NFProfile スキーマを、それを参照するだけのスキーマよりも先に返します。

スキーマのインデックス化されたテキストは、1レベルの $ref 展開を保持します — items や additionalProperties を通じて、また直接的に（これが5G SBI定義がほとんどの関係を表現する方法です）— そのため、参照される型のフィールドはそれを使用するスキーマから検索可能です。2ホップ先の型はそのテキストには含まれません。search とは異なり、このインデックスはステミングを適用しません — 識別子は記述されたまま一致します — また -、.、_ はトークンを分割するため、Nnrf_NFManagement は NFManagement でも見つかり、/nf-instances は instances でも見つかります。camelCaseは分割されません。

インデックスは build と update の最後に構築されます。import と import-dir はそのままにします：YAMLファイルはアーカイブzipに同梱されているため、.docx をインポートしてもインデックス対象が変わることはありません。このツールが存在する前に構築されたデータベースにはインデックスがありません。build-openapi-index でその場で追加します。

ASN.1定義

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がここで許可する範囲は何か」という質問に答える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 を指定しない場合、定義セクションごとにグループ化されたすべての割り当て名を一覧表示します。

埋め込み画像

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

図は、画像形式に関係なく、単一の表記法でセクションテキストから参照されます：本文では ![Figure](image://NAME?w=&h=)、テーブルセル内では <img src="image://NAME?w=&h=" ...>。その NAME を get_image に渡します。元のファイル名（image3.emf）と変換後のファイル名（image3.png）の両方が解決されます。

コードブロック

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

数式

Wordの数式（OMML）は3つの表記法でLaTeXに変換されるため、数式が単独で存在する場合でも文の中にある場合でも読み取り可能です：

インデント

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 パラメータで追加の設定は不要です。それでも、1つのリリースに対して継続的に作業する場合、リリースごとに個別のデータベースを構築すると効果的です：全文 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サーバーを起動します。

バージョンキャッシュは別の SQLite ファイルであるため、メインデータベースは読み取り専用のままで、余分なバージョンで汚染されることはありません。キャッシュを作成できない場合（scratch ベースのコンテナイメージなど、読み取り専用またはエフェメラルなファイルシステム）、サーバーは警告をログに記録し、オンデマンドフェッチを無効にして実行します。その他の機能はすべて正常に動作します。キャッシュされたバージョンは、サイズ制限を超えると、最も最近使用されていないものから削除されます。

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

build

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

--release、--max-release、--latest、--series、または --spec のいずれかを指定する必要があります。--spec-list を含む場合: ファイルが候補エントリを提供し、セレクターがそれらをフィルタリングします。

--release と --max-release は、指定されたリリースにバージョンがない仕様の扱いが異なります: --release 19 はそれをドロップし、--max-release 19 は制限以下の最新バージョンで保持します。これらは組み合わせて使用できません。

その他のコマンド

• 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）は 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

すべてに共通する規則:

• フラグは位置引数の前に置く必要があります。

• JSON 結果はインデントされ、ページ分割されずに stdout に出力されます — jq、head、または less にパイプしてください。警告と進行状況は stderr に出力されるため、stdout は解析可能なままです。

• --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 の可用性を報告しますが、作成はしません）。

• すべてのコマンドは --db（デフォルト 3gpp.db）を受け入れます。

環境変数