3gpp-mcp

Un servidor MCP (Model Context Protocol) que hace que las especificaciones 3GPP sean accesibles para los LLM.

Antecedentes

Las especificaciones 3GPP son referencias esenciales para la ingeniería de telefonía móvil y telecomunicaciones, pero son difíciles de manejar eficazmente para los LLM:

• Demasiados documentos - Existen miles de especificaciones en múltiples series, lo que dificulta encontrar la correcta.

• Los documentos individuales son demasiado grandes - Muchas especificaciones tienen cientos de páginas, superando con creces las ventanas de contexto típicas.

• Distribuidas como archivos de Word - Las especificaciones se publican en formato .docx / .doc y requieren conversión para el procesamiento de texto.

• Gran cantidad de referencias cruzadas - Las especificaciones se referencian entre sí con frecuencia; leer un solo documento de forma aislada da una imagen incompleta.

• Información contenida en tablas y figuras - Las tablas complejas y los diagramas de flujo contienen detalles críticos. Esta herramienta convierte las tablas a Markdown y extrae las imágenes incrustadas para su visualización por parte del LLM.

• Complejidad de versiones - Una misma especificación existe en múltiples releases de 3GPP, e identificar la versión correcta es importante.

Esta herramienta aborda estos desafíos analizando los archivos .docx, estructurando el contenido por sección y almacenándolo todo en una base de datos SQLite con búsqueda de texto completo (FTS5). Un servidor MCP expone entonces herramientas para buscar, navegar por secciones y seguir referencias cruzadas, permitiendo que un LLM navegue por las especificaciones como lo haría un ingeniero.

¿Por qué no RAG?

El RAG basado en embeddings es una forma común de mejorar la precisión en preguntas y respuestas sobre documentos, y existen sistemas RAG especializados para documentos 3GPP (Telco-RAG, TelcoAI). Esta herramienta adopta un enfoque más simple: en lugar de construir un pipeline de recuperación delante del modelo, le proporciona al modelo herramientas de búsqueda y navegación y le permite explorar las especificaciones como lo haría un ingeniero: búsqueda de texto completo, luego seguimiento de la jerarquía de secciones y referencias cruzadas. Dado que la recuperación es una simple búsqueda FTS5 sobre secciones estructuradas, no hay ningún modelo de embeddings ni base de datos vectorial que ejecutar, y todo reside en un único archivo SQLite.

Medido en TeleQnA, esto mejora la precisión en preguntas sobre estándares 3GPP entre 6.5 y 12.0 puntos porcentuales en tres familias de modelos. La mayor parte se debe a tener el texto en sí: una sola consulta BM25 sobre la misma base de datos representa entre +7.8 y +9.6 puntos de esa mejora. La propia búsqueda de la herramienta es lo que marca la diferencia en preguntas cuya respuesta se encuentra a más de un salto del primer pasaje recuperado; en tareas generadas a partir de las propias especificaciones (códigos de protocolo, estructura ASN.1, esquemas SBI de 5G) responde y cita correctamente entre el 88 y el 100%, superando esa misma línea base BM25 entre +26 y +88 puntos en cada tipo de tarea y cada modelo. Consulte BENCHMARK.md.

Related MCP server: mcp-docs

Primeros pasos

1. Instalación

# Homebrew
brew install higebu/tap/3gpp-mcp

# ...or with Go 1.26+
go install github.com/higebu/3gpp-mcp/cmd/3gpp-mcp@latest

También hay binarios precompilados disponibles en la página de releases. LibreOffice es opcional (necesario para la conversión de .doc a .docx y de imágenes EMF/WMF a PNG).

2. Construir la base de datos

Descargar e importar las especificaciones en la base de datos. Los archivos temporales se eliminan después de procesar cada especificación, minimizando el uso de disco.

# 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

Esto raspará el archivo FTP de 3GPP, descargará archivos ZIP, extraerá y analizará archivos .docx, e insertará el contenido estructurado en la base de datos SQLite.

3. Registrarse con su cliente 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

Añadir a ~/.config/github-copilot/cli-mcp.json (crear si no existe):

{
  "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

Añadir a su archivo de configuración (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows):

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

4. Visor web (opcional)

Navegue por las especificaciones en su navegador añadiendo --web al transporte HTTP:

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080 --web
# MCP endpoint: http://localhost:8080/mcp/
# Web viewer:   http://localhost:8080/

Características: lista de especificaciones con filtrado, visor de secciones con barra lateral de TOC, búsqueda de texto completo con paginación, navegación por versiones anteriores (las versiones se listan por especificación y se descargan bajo demanda, como las herramientas MCP), comparación de versiones (resumen estructural y diferencias por sección), imágenes incrustadas, enlaces de referencias cruzadas, definiciones OpenAPI con resaltado de sintaxis, renderizado KaTeX de las fórmulas LaTeX que emite el convertidor, modo oscuro, diseño adaptativo. Los bloques de código tienen resaltado de sintaxis por notación: ASN.1, Diameter, SIP/RTSP, SDP y XML (consulte Bloques de código).

WebMCP

Cuando el navegador proporciona la API W3C WebMCP (document.modelContext, un origin trial de Chrome a partir de 2026), el visor registra todas sus herramientas MCP con el navegador al cargar la página, de modo que un agente en el navegador pueda consultar la base de datos de especificaciones directamente. El registro es un paso a través del mismo origen hacia el endpoint /mcp/; no hay nada que configurar en el lado del servidor, y los navegadores sin la API no se ven afectados. Durante el origin trial, actívelo localmente mediante las banderas de Chrome (chrome://flags), o para un despliegue compartido sirva un encabezado Origin-Trial desde un proxy frontal.

Despliegue

HTTP Streamable

El transporte HTTP es sin estado: soporta la versión 2026-07-28 del protocolo MCP (sin handshake de inicialización, sin Mcp-Session-Id) mientras que los clientes más antiguos (2024-11-05 hasta 2025-11-25) siguen funcionando mediante sesiones por solicitud.

Inicie el servidor con transporte HTTP:

3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

Opcionalmente, active la autenticación mediante token Bearer:

export THREEGPP_MCP_BEARER_TOKEN=$(openssl rand -hex 32)
3gpp-mcp serve --db data/3gpp.db --transport http --addr :8080

Luego configure su cliente para conectarse vía HTTP:

{
  "mcpServers": {
    "3gpp": {
      "url": "http://your-server:8080",
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_TOKEN"
      }
    }
  }
}

Cuando se usa --web, el endpoint MCP se mueve a /mcp/.

Consulte examples/systemd/ para el despliegue en producción con systemd.

Docker

El Dockerfile es multi-etapa y construye la base de datos para una release directamente, produciendo una imagen autocontenida con la base de datos SQLite (secciones, definiciones OpenAPI e imágenes incrustadas) incluida. No se necesita ninguna base de datos preconstruida en el contexto de construcción.

# 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 por defecto es latest, que incluye la última versión de cada especificación en todas las releases. Establezca --build-arg RELEASE=<n> (ej. 19) para restringir la base de datos a una sola release, o --build-arg MAX_RELEASE=<n> para limitar la release más nueva sin eliminar especificaciones que no tengan versión en ella. Los dos no se pueden combinar.

Cloud Run

Para ejecutar en Cloud Run, consulte cloudbuild.yaml (build + push + deploy) y service.yaml (especificación del servicio Cloud Run).

Herramientas

Cada herramienta a continuación también tiene un gemelo CLI (list_specs → 3gpp-mcp list-specs, y así sucesivamente) para uso en shell y scripting — consulte los comandos de consulta en la Referencia de comandos.

Navegación por especificaciones

Cada resultado de get_toc, get_section y search nombra la especificación y versión de la que proviene, en cada página de una respuesta paginada.

Versiones anteriores

La base de datos contiene una versión por especificación. Para leer otra versión, pase version a get_section o get_toc. version acepta la forma con puntos (15.8.0), el token de archivo (f80), un selector de release (Rel-15 o 15, que elige la versión más nueva en esa release), o latest. Los selectores de release y latest se resuelven contra el archivo de 3GPP, por lo que requieren descarga bajo demanda (no funcionan con --no-fetch). old_version y new_version de compare_versions aceptan las mismas formas; new_version por defecto es la versión en la base de datos.

Una versión que no está en la base de datos se descarga del archivo de 3GPP y se convierte en el primer uso. Esto puede tomar hasta unos minutos para una especificación grande; si aún se está ejecutando cuando expira el presupuesto de la llamada, la herramienta lo indica y la misma llamada repetida más tarde devuelve el contenido. Los resultados se guardan en una caché de tamaño limitado (consulte serve) que está separada de la base de datos principal, por lo que:

• search cubre solo la versión en la base de datos — no se admite la búsqueda de texto completo entre releases

• get_references solo tiene datos para la versión en la base de datos, y una sección leída de una versión archivada lo indica en su encabezado

• get_image y list_images también aceptan version: las imágenes de una versión archivada se descargan en su primer uso (una descarga de archivo adicional por versión, con el mismo comportamiento de reintento), y las figuras EMF/WMF se convierten a PNG cuando LibreOffice está instalado en el servidor

• los números de sección se mueven entre releases; verifique get_toc para la versión anterior antes de leer una sección de la misma

Búsqueda

La herramienta search admite la sintaxis de consulta FTS5 de SQLite:

• Búsqueda de frase: "service based interface"

• Operadores booleanos: AMF AND UE, AMF OR SMF, NOT deprecated

• Exclusión después de un término positivo: handover -conditional

• Coincidencia de prefijo: handov*

• Filtro de columna: title:authentication, content:handover

• Proximidad: NEAR(AMF UE, 5)

Los términos que contienen guiones o puntos (IMS-AKA, 38.101) se citan automáticamente, por lo que no necesitan escape manual.

Referencias cruzadas

Definiciones de OpenAPI

search_openapi utiliza su propio índice FTS5, separado del que usa search: search cubre el texto de las cláusulas de especificación y nunca devuelve contenido OpenAPI, search_openapi cubre solo contenido OpenAPI. Un acierto es una definición en lugar de un documento — un esquema de components.schemas, o un método HTTP de una ruta (nombrado como PUT /nf-instances/{nfInstanceID}) — así que puedes encontrar un tipo de dato o un endpoint sin saber qué documento de API lo define, y luego leerlo completamente con get_openapi. Una consulta que es un único término simple ordena primero una definición con exactamente ese nombre, por lo que NFProfile devuelve el esquema NFProfile antes que los esquemas que solo lo referencian.

El texto indexado de un esquema lleva un nivel de expansión de $ref — a través de items y additionalProperties además de directamente, que es como las definiciones de 5G SBI expresan la mayoría de sus relaciones — por lo que los campos de un tipo referenciado son buscables desde el esquema que lo usa; un tipo a dos saltos de distancia no está en ese texto. A diferencia de search, este índice no aplica stemming — los identificadores se comparan tal como están escritos — y -, . y _ dividen tokens, por lo que Nnrf_NFManagement también se encuentra mediante NFManagement y /nf-instances mediante instances. camelCase no se divide.

El índice se construye al final de build y update. import e import-dir lo dejan intacto: los archivos YAML se incluyen en el archivo zip, por lo que importar un .docx no puede cambiar lo que hay que indexar. Una base de datos construida antes de que existiera esta herramienta no tiene índice; añádelo en su lugar con build-openapi-index.

Definiciones ASN.1

Los protocolos especificados en ASN.1 (RRC TS 38.331/36.331, NGAP TS 38.413, S1AP TS 36.413, XnAP, F1AP, ...) escriben su ASN.1 entre los marcadores -- ASN1START / -- ASN1STOP, que el convertidor almacena como bloques de código ```asn1 (ver Bloques de código). get_asn1 extrae cada asignación de nivel superior — tipos, constantes y objetos de información — de esos bloques.

Con name devuelve el texto completo de esa asignación junto con la sección que la define, para que la respuesta pueda ser citada. Esto es importante para los protocolos que definen todas sus IE en una cláusula: la cláusula de definiciones de IE de NGAP tiene cientos de kilobytes, mucho más de lo que cabe en una página de get_section, mientras que la única definición que responde "¿qué rango permite el ASN.1 aquí?" son unas pocas líneas. La coincidencia ignora mayúsculas/minúsculas y separadores, por lo que el AMF UE NGAP ID de la tabla de IE encuentra el AMF-UE-NGAP-ID del ASN.1; un nombre que no coincide con nada sugiere nombres similares. Un nombre definido más de una vez devuelve cada definición, cada una bajo su propia línea de origen.

Cuando no sabes qué especificación define un nombre, omite spec_id: el nombre se resuelve en todas las especificaciones de la base de datos, a partir de un índice construido en el momento de la construcción de la base de datos (build, update, import e import-dir lo actualizan). Una búsqueda que nombra la especificación incorrecta recibe información sobre dónde está realmente definido el nombre. Una base de datos construida antes de que existiera esta herramienta no tiene índice — añádelo en su lugar con build-asn1-index. La resolución entre especificaciones cubre solo las versiones de la base de datos — pasa spec_id (y opcionalmente version) para leer una versión archivada, con el mismo comportamiento de descarga bajo demanda que get_section.

Con un spec_id y sin name lista todos los nombres de asignación, agrupados por sección definitoria.

Imágenes incrustadas

Las imágenes PNG/JPEG/GIF/WebP son directamente visibles por los LLMs. Las imágenes EMF/WMF (la mayoría de las figuras 3GPP usan este formato) se almacenan como datos sin procesar por defecto; usa --convert-image para convertirlas a PNG mediante LibreOffice en tiempo de construcción.

Las figuras se referencian desde el texto de la sección en una notación única, sea cual sea el formato de la imagen: ![Figure](image://NAME?w=&h=) en el texto del cuerpo y <img src="image://NAME?w=&h=" ...> dentro de las celdas de tabla. Pasa ese NAME a get_image; tanto el nombre de archivo original (image3.emf) como el convertido (image3.png) se resuelven.

Bloques de código

El texto de la sección lleva bloques de código etiquetados, para que tanto los LLMs como el visor web puedan distinguir las notaciones:

Fórmulas

Las fórmulas de Word (OMML) se convierten a LaTeX en tres notaciones, para que una fórmula sea legible tanto si está sola como si está dentro de una frase:

Sangría

La prosa de 3GPP codifica la estructura en la sangría — listas anidadas de requisitos y condiciones, definiciones multinivel. El espacio en blanco inicial de un párrafo del cuerpo se conserva como espacios de no separación (U+00A0), convirtiéndose una tabulación del documento fuente en cuatro: una tabulación literal o 4+ espacios iniciales convertirían la línea en un bloque de código indentado en Markdown (dentro del cual el HTML como <sub> nunca se interpreta), mientras que los espacios de no separación mantienen el anidamiento visual en cualquier renderizador y no interfieren con la búsqueda de texto completo.

Consejos

Indica al modelo que use las herramientas

Adjuntar el servidor no hace por sí mismo que un modelo lo consulte: si se le da la opción, algunos modelos responden preguntas sobre 3GPP de memoria. En el benchmark, Claude Sonnet 5 omitió la recuperación en el 40% de las preguntas de TeleQnA y GPT 5.6 Luna en el 60%, y en esas preguntas las herramientas no sirvieron de nada. Una frase en el prompt del sistema del cliente elimina esa discreción. El texto medido:

No respondas de memoria. Busca primero en las especificaciones y basa tu respuesta en el texto que recuperes, incluso cuando estés seguro de que ya sabes la respuesta.

Esa frase redujo la tasa de omisión de Luna a cero y su ganancia de +5.9 a +12.0 puntos, no movió nada en un modelo que ya buscaba en cada pregunta, y no vale nada sin las herramientas adjuntas — fuerza la recuperación en lugar de colar una respuesta. Reglas internas más estrictas en el mismo espíritu — basa cada respuesta sobre 3GPP en el texto de las cláusulas recuperado a través de estas herramientas, y cita la cláusula — son razonables, pero solo la frase anterior es la que midió el benchmark.

Bases de datos separadas por release

Para comparaciones puntuales entre releases, compare_versions y el parámetro version no necesitan configuración adicional. Construir una base de datos separada por release sigue siendo rentable cuando trabajas continuamente contra un release: la búsqueda de texto completo search, get_references y las definiciones OpenAPI solo cubren la versión integrada en la base de datos, por lo que una base de datos específica de un release te da los tres para ese release, sin descargas bajo demanda.

# 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 mantiene solo las especificaciones que tienen una versión en ese release exacto, por lo que una especificación congelada en un release anterior (TS 34.108, por ejemplo) falta en la base de datos por completo. Para fijar un release sin perder esas especificaciones, limita la selección en su lugar — cada especificación se toma en su versión más nueva en o por debajo del límite:

# 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

Regístralos como servidores MCP separados:

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

Mantener las especificaciones actualizadas

Usa el comando update para buscar versiones más recientes de las especificaciones ya en tu base de datos:

3gpp-mcp update --db data/3gpp.db --convert-doc --convert-image

Referencia de comandos

serve

Iniciar el servidor MCP.

La caché de versiones es un archivo SQLite separado, por lo que la base de datos principal permanece de solo lectura y nunca se contamina con versiones adicionales. Cuando no se puede crear la caché — un sistema de archivos de solo lectura o efímero, como la imagen de contenedor basada en scratch — el servidor registra una advertencia y se ejecuta con la obtención bajo demanda deshabilitada; todo lo demás sigue funcionando. Las versiones en caché se eliminan según la política de menos recientemente usada una vez que se supera el límite de tamaño.

El transporte HTTP también expone GET /health, que devuelve 200 OK sin autenticación. Use esta ruta para comprobaciones de estado de la plataforma (Cloud Run, Sakura AppRun, sondas de vida/readiness de Kubernetes, etc.).

build

Descargar e importar especificaciones en la base de datos (recomendado para la configuración inicial). Alias: pipeline.

Se debe proporcionar uno de --release, --max-release, --latest, --series o --spec, incluido --spec-list: el archivo proporciona las entradas candidatas y el selector las filtra.

--release y --max-release difieren en lo que sucede con una especificación que no tiene versión en el lanzamiento nombrado: --release 19 la descarta, --max-release 19 la mantiene en su versión más nueva por debajo del límite. No se pueden combinar.

Otros comandos

• download — Descargar especificaciones sin conversión (--output-dir, por defecto specs). Requiere uno de --release, --max-release, --latest, --series o --spec, como build.

• import — Importar un único archivo .docx en la base de datos. Alias: convert. Uso: 3gpp-mcp import --db data/3gpp.db ruta/a/spec.docx

• import-dir — Importar todos los archivos .docx en un directorio a la base de datos. Alias: convert-dir. Uso: 3gpp-mcp import-dir --db data/3gpp.db ./specs

• update — Actualizar las especificaciones en la base de datos a las versiones más recientes, o a un límite con --max-release.

• build-openapi-index — Reconstruir el índice de búsqueda OpenAPI de una base de datos existente. build y update hacen esto por sí mismos, por lo que es para agregar el índice a una base de datos construida antes de que existiera search_openapi: serve abre la base de datos en modo solo lectura y no puede crearlo sobre la marcha.

• build-asn1-index — Reconstruir el índice de nombres ASN.1 de una base de datos existente. build, update, import y import-dir hacen esto por sí mismos, por lo que es para agregar el índice a una base de datos construida antes de que existiera get_asn1.

• completion — Imprimir un script de completado de shell: 3gpp-mcp completion bash (o zsh, fish)

El límite no se almacena en la base de datos, por lo que una base de datos construida con --max-release 19 necesita la misma bandera en update; de lo contrario, la actualización eleva cada especificación a la versión más reciente en el archivo. Con un límite, la actualización mueve una especificación en cualquier dirección, por lo que también reduce una base de datos ya construida sin límite al límite; una especificación cuya versión está por encima del límite se elimina, ya que ninguna versión de ella pertenece a una base de datos limitada. Una especificación que falta en el listado del archivo se deja intacta, ya que un listado fallido se ve igual que una especificación retirada.

Comandos de consulta

Los comandos de consulta (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) reflejan las herramientas de lectura MCP 1:1, por lo que la base de datos se puede inspeccionar y scriptear desde un shell sin un cliente 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

Convenciones compartidas por todos:

• Las banderas deben ir antes de los argumentos posicionales.

• Los resultados JSON se imprimen en stdout con sangría y sin paginación — canalice a jq, head o less. Las advertencias y notas de progreso van a stderr, por lo que stdout se mantiene analizable.

• Los comandos que aceptan --version (y compare-versions) toman las mismas formas de versión que las herramientas MCP (15.8.0, f80, Rel-15, latest) y esperan a que finalice una descarga bajo demanda en lugar de pedirle que reintente; interrumpa con Ctrl-C. Comparten las banderas de obtención de serve: --no-fetch, --version-cache, --version-cache-mb, --fetch-budget. Las consultas que no nombran ninguna versión nunca crean la caché de versiones (list-versions lee una caché existente para informar disponibilidad cached, pero no creará una).

• Cada comando toma --db (por defecto 3gpp.db).

Variables de Entorno