3gpp-mcp

Сервер MCP (Model Context Protocol), который предоставляет LLM доступ к спецификациям 3GPP.

Предыстория

Спецификации 3GPP — это важнейшие справочные материалы для инженерии мобильной связи и телекоммуникаций, но LLM сложно эффективно с ними работать:

• Слишком много документов — существуют тысячи спецификаций в нескольких сериях, что затрудняет поиск нужной.

• Отдельные документы слишком объемны — многие спецификации насчитывают сотни страниц, что значительно превышает типичный размер контекстного окна.

• Распространяются в формате Word — спецификации публикуются в форматах .docx / .doc и требуют конвертации для текстовой обработки.

• Интенсивные перекрестные ссылки — спецификации часто ссылаются друг на друга; чтение одного документа в отрыве от других дает неполную картину.

• Информация в таблицах и рисунках — сложные таблицы и блок-схемы содержат важные детали. Этот инструмент преобразует таблицы в Markdown и извлекает встроенные изображения для просмотра LLM.

• Сложность версий — одна и та же спецификация существует в нескольких релизах 3GPP, и определение правильной версии имеет значение.

Этот инструмент решает эти проблемы путем разбора файлов .docx, структурирования содержимого по разделам и хранения всего в базе данных SQLite с полнотекстовым поиском (FTS5). Затем сервер MCP предоставляет инструменты для поиска, просмотра по разделам и перехода по перекрестным ссылкам — позволяя LLM перемещаться по спецификациям так, как это делал бы инженер.

Почему не RAG?

RAG на основе эмбеддингов — распространенный способ повышения точности ответов на вопросы по документам, и существуют RAG-системы, специализированные для документов 3GPP (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

Этот процесс загружает данные из FTP-архива 3GPP, скачивает 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

Добавьте в ваш конфигурационный файл (~/Library/Application Support/Claude/claude_desktop_config.json на macOS, %APPDATA%\Claude\claude_desktop_config.json на Windows):

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

4. Веб-просмотрщик (опционально)

Просматривайте спецификации в браузере, добавив --web к HTTP-транспорту:

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-формул (LaTeX formulas), которые выдает конвертер, темная тема, адаптивный дизайн. Блоки кода подсвечиваются в соответствии с нотацией — ASN.1, Diameter, SIP/RTSP, SDP и XML (см. Code blocks).

WebMCP

Когда браузер предоставляет API W3C WebMCP (document.modelContext, на момент 2026 года — Chrome origin trial), просмотрщик регистрирует все свои инструменты MCP в браузере при загрузке страницы, поэтому внутрибраузерный агент может напрямую запрашивать базу данных спецификаций. Регистрация представляет собой тонкий прокси-сервер с тем же источником к конечной точке /mcp/ — на стороне сервера ничего настраивать не нужно, а браузеры без этого API не затрагиваются. Во время origin trial включите его локально через флаги 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 и так далее) для использования в оболочке и скриптах — см. команды запросов в Справочнике команд.

Просмотр спецификаций

Каждый результат get_toc, get_section и search указывает спецификацию и версию, из которой он получен, на каждой странице пагинированного ответа.

Прошлые версии

База данных содержит одну версию каждой спецификации. Чтобы прочитать другую версию, передайте version в get_section или get_toc. version принимает точечную форму (15.8.0), токен архива (f80), селектор релиза (Rel-15 или 15, выбирает самую новую версию в этом релизе) или latest. Селекторы релизов и latest разрешаются через архив 3GPP, поэтому они требуют загрузки по запросу (не работают с --no-fetch). old_version и new_version в compare_versions принимают те же формы; new_version по умолчанию равен версии в базе данных.

Версия, которой нет в базе данных, загружается из архива 3GPP и конвертируется при первом использовании. Это может занять до нескольких минут для большой спецификации; если процесс все еще выполняется, когда истекает время вызова, инструмент сообщает об этом, и при повторении того же вызова позже возвращается содержимое. Результаты хранятся в кэше ограниченного размера (см. serve), который отделен от основной базы данных, поэтому:

• search охватывает только версию в базе данных — полнотекстовый поиск по всем релизам не поддерживается

• get_references содержит данные только для версии в базе данных, и раздел, прочитанный из архивной версии, сообщает об этом в своем заголовке

• get_image и list_images также принимают version: изображения архивной версии загружаются при первом использовании (одна дополнительная загрузка архива на версию, с тем же поведением повторных попыток), а рисунки EMF/WMF конвертируются в PNG, если на сервере установлен LibreOffice

• номера разделов меняются между релизами; перед чтением раздела старой версии проверьте 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 или один 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

Протоколы, определённые через 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 в одном пункте: пункт определений IE NGAP занимает сотни килобайт, что намного больше одной страницы get_section, в то время как одно определение, отвечающее на вопрос «какой диапазон допускает здесь ASN.1», состоит из нескольких строк. Сопоставление игнорирует регистр и разделители, поэтому AMF UE NGAP ID из таблицы IE находит AMF-UE-NGAP-ID из ASN.1; имя, не соответствующее ничему, получает предложения похожих имён. Имя, определённое более одного раза, возвращает все определения, каждое под своей исходной строкой.

Если вы не знаете, какая спецификация определяет имя, опустите 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 для преобразования их в PNG через LibreOffice во время сборки.

Рисунки ссылаются из текста раздела в единой нотации, независимо от формата изображения: ![Рисунок](image://NAME?w=&h=) в основном тексте и <img src="image://NAME?w=&h=" ...> внутри ячеек таблицы. Передайте это NAME в get_image; разрешаются как исходное имя файла (image3.emf), так и преобразованное (image3.png).

Блоки кода

Текст раздела содержит помеченные блоки кода, чтобы и LLM, и веб-просмотрщик могли различать нотации:

Формулы

Формулы Word (OMML) преобразуются в LaTeX в трёх нотациях, чтобы формула была читаема как отдельно, так и внутри предложения:

Отступы

Проза 3GPP кодирует структуру с помощью отступов — вложенные списки требований и условий, многоуровневые определения. Начальные пробелы абзаца тела сохраняются как неразрывные пробелы (U+00A0), одна табуляция исходного документа становится четырьмя: литеральная табуляция или 4+ начальных пробела превратили бы строку в блок кода с отступом в Markdown (внутри которого HTML, например <sub>, никогда не интерпретируется), в то время как неразрывные пробелы сохраняют визуальную вложенность в любом рендерере и не мешают полнотекстовому поиску.

Советы

Сообщите модели использовать инструменты

Подключение сервера само по себе не заставляет модель обращаться к нему: при наличии выбора некоторые модели отвечают на вопросы по 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, пробы liveness/readiness 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 — Вывести скрипт автодополнения для оболочки: 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).

Переменные окружения