3gpp-mcp

3gpp-mcp

一个 MCP（Model Context Protocol）服务，让大模型能够访问 3GPP 规范。

背景

3GPP 规范是移动和电信工程的重要参考资料，但大模型难以有效处理这些文档：

• 文档数量过多 - 各个系列中有数千份规范，很难找到合适的文档。
• 单份文档过于庞大 - 许多规范长达数百页，远超常见的上下文窗口限制。
• 以 Word 文件形式分发 - 规范以 .docx / .doc 格式发布，需要转换后才能进行文本处理。
• 交叉引用繁多 - 规范之间经常相互引用；孤立地阅读单份文档会导致理解不完整。
• 信息密集地呈现在表格和图示中 - 复杂表格和流程图包含关键信息。此工具会将表格转换为 Markdown，并提取嵌入的图片供大模型查看。
• 版本复杂 - 同一份规范可能对应多个 3GPP 版本，确定正确的版本很重要。

此工具通过解析 .docx 文件、按章节构建内容结构，并将所有内容存储在支持全文搜索（FTS5）的 SQLite 数据库中，来应对这些挑战。随后，MCP 服务会提供搜索、按章节浏览和追踪交叉引用等工具，让大模型像工程师一样查阅规范。

为什么不使用 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。

开始使用

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 工具一样按需下载）、版本比较（结构摘要和逐章节差异）、嵌入图像、按需获取会议列表和文档（TDocs）（通过 /meetings 和 /tdocs）、交叉引用链接、带语法高亮的 OpenAPI 定义、对转换器生成的 LaTeX 公式进行 KaTeX 渲染、深色模式、响应式设计。代码块会根据标记语言进行语法高亮，包括 ASN.1、Diameter、SIP/RTSP、SDP 和 XML（参见代码块）。

WebMCP

当浏览器提供 W3C WebMCP API（document.modelContext；截至 2026 年仍处于 Chrome origin trial 阶段）时，查看器会在页面加载时向浏览器注册其所有 MCP 工具，因此浏览器内的 Agent 可以直接查询规范数据库。注册过程只是对 /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>，限制最新发行版，同时保留在该发行版中没有版本的规范。两者不能同时使用。

Cloud Run

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

工具

下面列出的每个工具都有对应的 CLI 命令（例如，list_specs → 3gpp-mcp list-specs）， 可用于 Shell 和脚本——请参见命令参考中的 查询命令。

浏览规范

工具	描述	关键参数
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	比较某项规范的两个版本：结构摘要或章节文本差异	spec_id、old_version（必需）、new_version、section_number、include_subsections、context_lines、offset、max_lines、max_chars

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

以往版本

数据库为每项规范保存一个版本。若要读取其他版本，请向 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：首次使用归档版本的图像时会单独下载（每个版本额外下载一次归档，重试行为相同）；如果服务端安装了 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 使用自己的 FTS5 索引，与 search 使用的索引分开： search 搜索规范条款文本，不会返回 OpenAPI 内容， search_openapi 仅搜索 OpenAPI 内容。一个命中对应一个定义，而非一个文档——可以是 components.schemas 中的一个架构，也可以是一个路径的一个 HTTP 方法 （名称类似 PUT /nf-instances/{nfInstanceID}）——因此，你无需知道哪个 API 文档定义了某个数据类型或端点，就能找到它，然后使用 get_openapi 阅读完整内容。对于只有一个裸词的查询，会优先返回名称完全匹配的定义，因此，搜索 NFProfile 时，会先返回 NFProfile 架构，再返回仅引用它的架构。

架构的索引文本会展开一级 $ref——包括通过 items 和 additionalProperties 展开的引用，以及直接引用；这正是 5G SBI 定义中大多数关系的表述方式——因此，可以从使用某个类型的架构中搜索该引用类型的字段；相隔两级的类型不会出现在该文本中。与 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 赋值项（可在单个规范中或所有规范中查找），或列出某个规范的赋值项名称	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 的协议尤为重要：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 时，会按定义章节分组列出所有赋值项名称。

嵌入式图片

工具	描述	关键参数
list_images	列出规范中的嵌入式图片	spec_id（必填）、version（可选）
get_image	获取可供大模型查看的嵌入式图片 Base64 数据	spec_id、name（必填）：图片文件名；version（可选）

大模型可以直接查看 PNG/JPEG/GIF/WebP 图片。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）都可以解析。

会议文档（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	以 Markdown 格式读取会议文档（TDoc）	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、版本、工作项目和联系人。网页查看器会显示相同内容，并将每个变更条款以及 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 和网页查看器都能区分不同记法：

围栏	内容
```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）会转换为三种记法的 LaTeX，因此无论公式独立呈现还是出现在句子中，都易于阅读：

记法	用途
```latex 围栏	内容只有一个公式的段落。公式编号会保留为 \tag{7.3-1}，并呈现为右对齐的 (7.3-1)。
$$...$$	无法使用围栏代码块的显示公式，例如表格单元格或列表项中的公式。
$...$	句子中的公式。

缩进

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 服务。

标志	描述	默认值
--db	SQLite 数据库路径	3gpp.db
--transport	传输类型：stdio 或 http（环境变量：THREEGPP_MCP_TRANSPORT；设置了 PORT 时默认为 http）	stdio
--addr	HTTP 监听地址（环境变量：THREEGPP_MCP_ADDR；或将 PORT 解释为 :$PORT）	:8080
--bearer-token	HTTP 身份验证的 Bearer 令牌（环境变量：THREEGPP_MCP_BEARER_TOKEN）
--web	启用与 MCP 服务并行运行的 Web 查看器（仅限 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 传输还会开放 GET /health，该端点无需身份验证并返回 200 OK。可将此路径用于平台健康检查（Cloud Run、Sakura AppRun、Kubernetes 存活性／就绪性探针等）。

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

必须指定 --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、 list-meetings、list-tdocs、get-tdoc、get-meeting-report）与 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
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。这四个命令共用 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 传输身份验证的 Bearer 令牌
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	规范列表缓存的 TTL（单位：小时，默认值为 24）
THREEGPP_LISTING_RETRY_MS	获取归档列表时重试间隔的初始退避时间（单位：ms，默认值为 1000）
XDG_CACHE_HOME	缓存目录根路径，遵循 XDG 基本目录规范