3gpp-mcp

一个 MCP（模型上下文协议）服务器，使 3GPP 规范对 LLM 可访问。

背景

3GPP 规范是移动和电信工程的重要参考，但 LLM 难以有效处理它们：

• 文档太多 - 跨多个系列存在数千份规范，难以找到正确的文档。

• 单个文档太大 - 许多规范长达数百页，远超典型的上下文窗口。

• 以 Word 文件形式分发 - 规范以 .docx / .doc 格式发布，需要转换才能进行文本处理。

• 大量交叉引用 - 规范频繁相互引用；孤立地阅读单个文档会得到不完整的图景。

• 信息集中在表格和图中 - 复杂的表格和流程图承载着关键细节。此工具将表格转换为 Markdown 并提取嵌入的图像供 LLM 查看。

• 版本复杂性 - 同一规范存在于多个 3GPP 版本中，识别正确的版本很重要。

此工具通过解析 .docx 文件、按章节组织内容并将所有内容存储在带有全文搜索（FTS5）的 SQLite 数据库中来应对这些挑战。然后，一个 MCP 服务器公开用于搜索、按章节浏览和跟踪交叉引用的工具——让 LLM 像工程师一样浏览规范。

为什么不使用 RAG？

基于嵌入的 RAG 是提高文档问答准确性的常用方法，并且存在专门针对 3GPP 文档的 RAG 系统（Telco-RAG，TelcoAI）。此工具采用更简单的方法：不是在模型前构建检索管道，而是为模型提供搜索和导航工具，让它像工程师一样探索规范——全文搜索，然后跟踪章节层次结构和交叉引用。由于检索是对结构化章节的纯 FTS5 搜索，因此无需运行嵌入模型或向量数据库，所有内容都存在于一个 SQLite 文件中。

在 TeleQnA 上衡量，这使三个模型系列在 3GPP 标准问题上的准确率提高了 6.5 到 12.0 个百分点。其中大部分归功于拥有文本本身：对同一数据库的单个 BM25 查询贡献了 +7.8 到 +9.6 个百分点。该工具自身的搜索在回答距离首次检索到的段落不止一跳的问题时脱颖而出——在从规范本身生成的任务（协议代码、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 源试用）时，查看器会在页面加载时将其所有 MCP 工具注册到浏览器，因此浏览器内代理可以直接查询规范数据库。注册是通过 /mcp/ 端点的轻量级同源直通——无需配置服务器端，没有该 API 的浏览器不受影响。在源试用期间，通过 Chrome 标志（chrome://flags）在本地启用它，或者对于共享部署，从代理服务器提供 Origin-Trial 标头。

部署

Streamable HTTP

HTTP 传输是无状态的：它支持 MCP 协议版本 2026-07-28（无初始化握手，无 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/。

参见 examples/systemd/ 了解使用 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> 以限制最新版本，而不删除其中没有该版本的规范。两者不能结合使用。

Cloud Run

要在 Cloud Run 上运行，请参见 cloudbuild.yaml（构建 + 推送 + 部署）和 service.yaml（Cloud Run 服务规范）。

工具

下面的每个工具也有一个 CLI 对应项（list_specs → 3gpp-mcp list-specs，依此类推），用于 shell 使用和脚本编写——请参阅命令参考中的查询命令。

浏览规范

每个 get_toc、get_section 和 search 结果都会在分页响应的每一页上命名其来源的规范和版本。

历史版本

数据库保存每个规范的一个版本。要读取另一个版本，请将 version 传递给 get_section 或 get_toc。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：存档版本的图像会在首次使用时单独下载（每个版本额外一次存档下载，具有相同的重试行为），并且当服务器上安装了 LibreOffice 时，EMF/WMF 图形会转换为 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 内容。一次命中对应一个定义而非一个文档——来自 components.schemas 的 schema，或一个路径的一个 HTTP 方法（命名如 PUT /nf-instances/{nfInstanceID}）——因此您可以找到数据类型或端点而无需知道是哪个 API 文档定义了它，然后通过 get_openapi 完整读取。查询为单个裸词时，会将名称完全匹配的定义排在首位，因此 NFProfile 会返回 NFProfile schema，排在仅引用它的 schema 之前。

schema 的索引文本携带一级 $ref 展开——通过 items 和 additionalProperties 以及直接引用，这正是 5G SBI 定义表述其大部分关系的方式——因此被引用类型的字段可从使用它的 schema 中搜索到；相隔两跳的类型不在该文本中。与 search 不同，此索引不应用词干提取——标识符按原样匹配——并且 -、. 和 _ 会分割 token，因此 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……）将其 ASN.1 写在 -- ASN1START / -- ASN1STOP 标记之间，转换器将其存储为 ```asn1 围栏（参见代码块）。get_asn1 从这些围栏中提取每个顶级赋值——类型、常量和信息对象。

使用 name 时，它返回该赋值的完整文本及其定义所在的章节，以便答案可被引用。这对于将所有 IE 定义在一个条款中的协议很重要：NGAP 的 IE 定义条款有数百 KB，远超一个 get_section 页面，而回答“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 时，它会列出每个赋值名称，按定义章节分组。

嵌入图片

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）以三种符号转换为 LaTeX，因此公式无论是独立存在还是位于句子中都可读：

缩进

3GPP 文本通过缩进编码结构——嵌套的需求和条件列表、多级定义。正文段落的开头空白保留为不间断空格（U+00A0），源文档的一个制表符变为四个：字面制表符或 4 个以上前导空格会将行变为 Markdown 中的缩进代码块（其中像 <sub> 这样的 HTML 永远不会被解释），而不间断空格在任何渲染器中保持视觉嵌套，且不影响全文搜索。

提示

告知模型使用工具

附加服务器本身并不会使模型查阅它：在可以选择的情况下，一些模型会凭记忆回答 3GPP 问题。在基准测试中，Claude Sonnet 5 跳过了 40% 的 TeleQnA 问题的检索，GPT 5.6 Luna 跳过了 60%，而在这些问题上，工具毫无价值。客户端系统提示中的一句话消除了这种自由裁量权。经过测量的措辞：

不要凭记忆回答。首先搜索规范，并根据您检索到的文本给出答案，即使您确信自己已经知道答案。

这句话将 Luna 的跳过率降至零，其增益从 +5.9 分提高到 +12.0 分，对已经搜索每个问题的模型没有影响，并且如果没有附加工具则毫无价值——它强制检索而不是偷偷塞入答案。本着同样精神更严格的内部规则——关于 3GPP 的每个答案都基于通过这些工具检索到的条款文本，并引用该条款——是合理的，但只有上述句子是基准测试所测量的。

每个版本使用单独的数据库

对于跨版本的快速比较，compare_versions 和 version 参数无需额外设置。当您持续针对一个版本工作时，为每个版本构建单独的数据库仍然值得：全文 search、get_references 和 OpenAPI 定义仅覆盖数据库内置的版本，因此特定版本的数据库为您提供该版本的所有这三个功能，无需按需下载。

# 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 的容器镜像），服务器会记录警告并以禁用按需获取的方式运行；其他所有功能继续正常工作。一旦超出大小限制，缓存的版本将按最近最少使用（LRU）策略被驱逐。

HTTP 传输还暴露了 GET /health，该端点无需认证即可返回 200 OK。请使用此路径进行平台健康检查（Cloud Run、Sakura AppRun、Kubernetes 存活/就绪探针等）。

build

下载并将规范导入数据库（推荐用于初始设置）。别名：pipeline。

必须提供 --release、--max-release、--latest、--series 或 --spec 之一，包括 --spec-list 时：文件提供候选条目，选择器对其进行筛选。

--release 和 --max-release 的区别在于，当某个规范在指定版本中没有对应版本时：--release 19 会丢弃该规范，--max-release 19 则保留其低于该限制的最新版本。两者不能同时使用。

其他命令

• download — 下载规范而不进行转换（--output-dir，默认为 specs）。需要提供 --release、--max-release、--latest、--series 或 --spec 之一，与 build 相同。

• 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 — 打印 Shell 补全脚本：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 读取工具一一对应，因此可以在没有 MCP 客户端的情况下从 Shell 检查和编写数据库脚本：

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 结果以缩进格式打印到标准输出，不进行分页——可以管道到 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 可用性，但不会创建缓存）。

• 每个命令都接受 --db（默认为 3gpp.db）。

环境变量