MCP Server 3gpp

mcp-server-3gpp

用于3GPP和IETF RFC规范的MCP服务器，由预构建的SQLite语料库支持。

当前的v2服务器是围绕AI引导的章节导航构建的，而不是硬编码的协议查找逻辑。预期的工作流程是：

1. 通过以下方式了解相关规格 get_spec_catalog, search_etsi_catalog，或 search_3gpp_docs.
2. 浏览章节结构 get_spec_toc.
3. 使用检索精确文本 get_section.
4. 在本地扩展 search_related_sections.
5. 使用以下命令跳过文档 get_spec_references.
6. 提取测试用例结构 get_test_case_structure 和 list_test_cases.

搜索是一个起点，而不是整个产品。该模型预计会有意识地浏览和选择章节。

今天有什么船

• 数据库支持的v2服务器，配备12个MCP工具
• 预构建语料库 data/corpus/3gpp.db
• 总共207个规格：113个TS，1个TR，93个RFC
• 66109个完整部分和63376个TOC行
• 45162交叉规格参考边
• 标准MCP入口点 src/index.js
• 可选的流式HTTP传输 src/http.js
• 四向RRF混合搜索（互序融合）
• 可选的Windows AnyTXT搜索器集成
• 可选HyDE（假设文档嵌入）通过NVIDIA NIM API进行查询扩展

搜索行为

搜索使用一个多阶段检索管道，最多有四个并行检索器，由RRF（互易秩融合，k=60）融合：

Query -> [FTS5/BM25]    (keyword, always active)
      -> [sqlite-vec]    (semantic, when embeddings ready)
      -> [AnyTXT API]    (full-document, when AnyTXT running on Windows)
      -> [HyDE + LLM]    (query expansion, when NVIDIA API key configured)
      -> RRF fusion -> Structure-aware ranking -> Results

关键属性：

• 基线 npm install 为您提供关键字就绪的服务器路径：BM25/FTS搜索、TOC导航、精确部分检索和跨规范引用。
• search_3gpp_docs 支持引用短语， spec: 过滤器， section: 该基线路径中的提示和否定。
• RRF融合用基于排名的评分取代了原始评分组合，消除了在具有不兼容分布的检索器之间进行评分归一化的需要。使用 fusion: 'rrf' （默认）或 fusion: 'linear' 切换。
• 数据库和运行时可以托管 sqlite-vec 嵌入通过 vec_sections，但这仅使语料库向量具有能力。
• 语义检索或混合检索应被视为一种可选的就绪状态。仅当运行时具有语义先决条件并且烟雾路径实际返回时，它才处于活动状态 mode_actual=hybrid 或 mode_actual=semantic 结果中有语义证据。
• HyDE通过NVIDIA LLM生成一个假设的3GPP风格的答案，然后嵌入该答案进行矢量搜索，从而扩展了简短/模糊的查询。这弥合了查询和文档之间的词汇差距。

需求

• Node.js 20.x、22.x和24.x是受支持的、经过CI测试的运行时。
• 该项目使用 better-sqlite3 12.x，因此安装可以在支持的Node版本中使用预构建的本机二进制文件，包括Windows上的Node 24。
• 如果稍后扩展节点版本范围，请同时更新本机依赖关系和CI矩阵。

快速启动

git lfs install
git clone https://github.com/Lee-SiHyeon/mcp-server-3gpp.git
cd mcp-server-3gpp
npm install
npm run validate
npm start

捆绑的数据库使用Git LFS进行跟踪。一个健康的创业公司看起来像：

[3GPP MCP] Database ready: .../data/corpus/3gpp.db
[3GPP MCP] Features - FTS: true, Vector: true
[3GPP MCP] Registered 12 tools (v2 DB mode)

npm run validate 现在报告了两个独立的状态：

• Baseline keyword readiness：数据库支持的12工具服务器运行良好，搜索/导航工作在关键字模式下。
• Optional semantic readiness：是否安装了语义先决条件，以及实时工具冒烟测试是否实际激活了语义/混合检索。

MCP客户端配置

克劳德桌面版

{
  "mcpServers": {
    "3gpp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-3gpp/src/index.js"]
    }
  }
}

VS代码/GitHub副本

{
  "servers": {
    "3gpp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-3gpp/src/index.js"]
    }
  }
}

可选自定义数据库路径

{
  "env": {
    "THREEGPP_DB_PATH": "/custom/path/to/3gpp.db"
  }
}

服务器按顺序检查这些数据库位置：

1. THREEGPP_DB_PATH
2. data/corpus/3gpp.db
3. data/3gpp.db

工具表面

推荐的提示模式

使用鼓励结构优先导航的提示：

Find the chapter in TS 24.301 that defines attach reject causes.
Start by locating the spec, then inspect the TOC, then fetch the most relevant section.

I need the exact wording for the NAS registration timer behavior in 5G.
Search for likely sections, then read the chapter text and nearby sections.

Show which RFCs and 3GPP specs TS 29.500 cites most often.

语料库统计

建筑概览

LLM client
  -> MCP transport (stdio or HTTP)
  -> tool registry + validation
  -> tool handlers
  -> SQLite corpus (specs, toc, sections, sections_fts, spec_references, ingestion_runs)
  -> ETSI catalog (etsi_publication_types, etsi_ranges, etsi_documents, etsi_versions, etsi_files)
  -> optional vec_sections table and guide resources
  -> search pipeline:
       keywordSearch.js  (FTS5 + BM25)
       semanticSearch.js  (sqlite-vec cosine)
       anytxtSearch.js    (AnyTXT JSON-RPC API, Windows only)
       hydeExpander.js    (NVIDIA NIM LLM for query expansion)
       hybridRanker.js    (RRF fusion + structure-aware ranking)

更多细节生活在 docs/architecture.md 和 docs/data-model.md.

验证和测试

npm run validate
npm test

npm run validate 检查包元数据，解析DB路径，验证核心模式和计数，确认v2 12工具表面，运行导航烟雾路径，并将语义准备情况与基线关键字准备情况分开报告。

可选语义准备

语义检索不是基线安装合同的一部分。将其视为关键字服务器之上的操作员选择加入层。

当前先决条件：

1. sqlite-vec 必须在运行时成功加载。
2. vec_sections 必须为活动语料库填充嵌入。
3. 本地嵌入必须存在兼容的变压器运行时。存储库现在随附 @huggingface/transformers，运行时仍然接受 @xenova/transformers 为了兼容性。
4. 现场直播 search_3gpp_docs 烟雾路径必须实际返回 mode_actual=hybrid 或 mode_actual=semantic.

scripts/generate_embeddings.js 现在是真正的本地语料库填充工作流程 vec_sections它可以构建或重建嵌入索引，但语义主动就绪仍然需要 新鲜完整语料库索引.部分运行(--spec 或 --limit)可用于烟雾测试和受控回填，但它们是有意为之 不 将语义检索标记为全局就绪。

手动烟雾工作流程

ETSI目录烟雾：

npm run catalog:smoke

这只会将一小部分ETSI TS范围爬行到目录表中。它没有 下载PDF、提取文本或生成嵌入。为了更广泛的编目， 使用 npm run catalog:crawl -- --all-publication-types --depth versions 并添加 限制，例如 --max-ranges, --max-docs, --max-versions，或 --max-requests 用于受控回填。

目录爬虫安全控制：

python3 scripts/crawl_etsi_catalog.py --publication-types etsi_ts etsi_tr --depth documents --plan-only
python3 scripts/crawl_etsi_catalog.py --publication-types etsi_ts etsi_tr --depth documents --max-ranges 10
python3 scripts/crawl_etsi_catalog.py --publication-types etsi_ts etsi_tr --depth documents --resume
python3 scripts/select_etsi_ingest.py --policy priority --format download-list

爬虫记录中的进度 catalog_crawl_runs 和 catalog_crawl_progress长目录写入仅限于CLI；MCP目录工具 是只读的。下载、提取和嵌入状态与 文档标识 etsi_document_status. select_etsi_ingest.py 标记 优先级3GPP映射的ETSI文档，用于以后的下载/提取/嵌入工作，以及 可以生成一个以标签分隔的下载计划，而无需下载任何PDF。

降级路径烟雾：

npm install
npm run validate

预期结果：

• Baseline keyword readiness: true
• Optional semantic prerequisites met: false 或 Semantic-active tool smoke: false
• Search mode actual: keyword

语义活性烟雾：

1. 跑 npm install.
2. 确保 sqlite-vec 负载和 vec_sections 充满了新鲜的 完整语料库 嵌入与活动384 dim模型/前缀契约匹配的索引。例子：

node scripts/generate_embeddings.js --rebuild

1. 跑 npm run validate.

预期结果：

• Optional semantic prerequisites met: true
• Semantic-active tool smoke: true
• Semantic smoke mode actual: hybrid 或 semantic

可选AnyTXT集成（Windows）

AnyTXT Searcher为PDF以外的格式提供了额外的搜索信号和文档解析。运行时，其位于的JSON-RPC API localhost:9920 自动检测。

先决条件：

1. 安装 AnyTXT搜索器 在Windows上。
2. 启用HTTP API：菜单帮助->API。
3. 同步 raw/ 目录到AnyTXT的索引中（工具->索引管理器）。

如果可用，AnyTXT会将第三个检索器添加到RRF融合中，搜索原始文件内容，包括DOCX、XLSX和扫描的PDF（OCR）。当不可用时，管道降级为双向RRF（关键字+语义）。

CLI提取工具：

node scripts/extract_anytxt.js --check                # verify API availability
node scripts/extract_anytxt.js --sync raw/            # sync raw dir to AnyTXT index
node scripts/extract_anytxt.js raw/ts_38_523_1.pdf    # extract text from a file
node scripts/extract_anytxt.js --batch raw/           # batch extract all supported files

可选的HyDE查询扩展

HyDE（假设文档嵌入）通过LLM生成假设的3GPP风格答案，然后使用该答案的嵌入进行向量搜索，从而提高了对简短或模糊查询的召回率。这弥合了查询和技术文档之间的词汇差距。

通过环境变量或编程API进行配置：

NVIDIA_API_KEY=nvapi-... npm start

import { configureHyde } from './src/search/hybridRanker.js';
configureHyde({ apiKey: 'nvapi-...' });

默认为 nvidia/llama-3.1-nemotron-nano-8b-v1 在NVIDIA NIM端点上。任何与OpenAI兼容的聊天完成URL都可以通过 apiUrl 选项。

项目结构

mcp-server-3gpp/
├── src/
│   ├── index.js
│   ├── http.js
│   ├── db/
│   ├── search/
│   │   ├── hybridRanker.js      (RRF fusion + structure-aware ranking)
│   │   ├── keywordSearch.js     (FTS5 + BM25)
│   │   ├── semanticSearch.js    (sqlite-vec)
│   │   ├── anytxtSearch.js      (AnyTXT JSON-RPC retriever)
│   │   ├── hydeExpander.js      (HyDE query expansion via NVIDIA LLM)
│   │   └── queryParser.js
│   ├── anytxt/
│   │   ├── client.js            (JSON-RPC 2.0 client)
│   │   └── parser.js            (document text extraction)
│   ├── tools/
│   └── ingest/
├── docs/
├── data/
│   └── corpus/
│       └── 3gpp.db
├── test/
├── validate.js
└── package.json

备注

• 记录在案的操作模型是数据库支持的v2服务器。
• 中仍有一条传统的回退路径 src/index.js 如果找不到SQLite数据库，但这是一个引导逃逸窗口，而不是此存储库记录的主要接口。
• get_section 和 get_spec_toc 是核心的确定性检索工具。搜索应该养活他们，而不是取代他们。