3gpp-mcp AGENTS.md

AGENTS.md

MCP server that downloads 3GPP specification documents (.docx), converts them to Markdown, stores them in SQLite with FTS5 full-text search, and serves them via MCP tools and an optional web viewer. Go 1.26+, pure Go SQLite (modernc.org/sqlite) — no CGO.

README.md has the command reference, MCP tool list, environment variables, code-fence table and deployment guide. This file only covers what an agent cannot easily discover from the code.

Commands

make build                # Build to bin/3gpp-mcp
go test ./...             # Run tests (-short skips tests that hit the 3GPP FTP)
gofmt -l . && go vet ./... && golangci-lint run   # Lint (CI also runs go test -race)
make build-db             # Download + import latest version of every spec (RELEASE=19 for one release, MAX_RELEASE=19 to cap)
make web                  # HTTP server with web viewer at :8080
make e2e                  # Playwright suite for web viewer JS behavior (CI job "e2e"); hermetic server harness in e2e/e2eserver

Package Map

• cmd/3gpp-mcp/ — CLI entry point (serve, build, download, import, import-dir, update, plus query subcommands mirroring the MCP read tools 1:1 in query.go). New subcommands register in the commands slice in main.go — dispatch, the usage line and the shell completion scripts are all generated from it
• internal/converter/docx/ — DOCX → Markdown parser; internal/converter/pipeline/ — streaming download + convert worker pool
• internal/db/ — SQLite schema, queries, FTS5
• internal/versionstore/ — on-demand cache of spec versions not in the prebuilt database
• internal/tools/ — MCP tool handlers; internal/web/ — web viewer (reads through the same tools.Source, so it is version-aware)
• internal/specver/ — base-36 archive token (k20) ↔ dotted version (20.2.0)
• internal/structdiff/, internal/textdiff/ — compare_versions diff logic, shared with the web compare page

Invariants & Gotchas

• One version per spec in the main database. specs is keyed by (id, version), but InsertSpecWithSectionsAndImages drops any other version of the same spec. Search depends on this: the FTS index has no version column, so a second version would double every hit.
• Archived versions never reach search. versionstore fetches them into a separate SQLite file ($XDG_CACHE_HOME/3gpp-mcp/versions.db) with no FTS tables. Fetches are deduplicated per (spec, version) and run on a context detached from the caller so a client timeout does not discard the work; entries are evicted LRU, and a version's text and images evict as one unit. Images are fetched lazily on the first get_image/list_images call. OpenAPI YAML and cross-references are prebuilt-only.
• OpenAPI search is a second FTS index. openapi_chunks / openapi_chunks_fts (db.OpenAPIIndexSchema) hold one row per schema and per operation, derived from openapi_specs by internal/openapiindex and rebuilt wholesale — never incrementally, because most $refs cross into another file, so importing one document changes the chunks of documents imported before it. build and update end in rebuildOpenAPIIndex; import and import-dir deliberately do not, because the YAML arrives in the archive zip and a .docx import cannot touch openapi_specs. The tokenizer is plain unicode61, no porter: these rows are identifiers, not prose, and -/./_ split so a partial name matches. A schema chunk expands $ref one level, through items and additionalProperties as well as directly — that is how the 5G SBI definitions state most of their relationships. Like the rest of the OpenAPI features it is prebuilt-only and absent from versionstore. Databases built before this existed have no index at all — serve opens read-only and cannot create it, so SearchOpenAPI returns db.ErrNoOpenAPIIndex and the tool points at build-openapi-index. The index is never allowed to be stale: a rebuild that fails drops it (DropOpenAPIIndex) rather than leaving chunks that describe the previous corpus, so the honest "missing" state is the only failure mode. update keeps its working copy on such a failure — the spec import costs hours, the index seconds — but only after confirming the drop took.
• get_asn1 answers from the asn1_defs table, built at DB build time. internal/asn1index extracts every top-level assignment (candidates seeded via sections_fts MATCH 'ASN1START' — a LIKE over a full corpus takes minutes) and build, update, import and import-dir all end in a wholesale rebuild — import too, because unlike OpenAPI YAML a .docx does carry ASN.1. Like the OpenAPI index it is never allowed to be stale: a failed rebuild drops it, and serve (read-only) reports it missing and names build-asn1-index. Without the table the cross-spec (spec_id-less) mode and the wrong-spec hint are lost; the per-spec path falls back to reading the whole document per call. Archived versions never enter the index.
• Image references are format-independent: image://NAME?w=&h= in body text, <img src="image://..."> in table cells. structdiff.NormalizeImageRefs keeps conversion-pair extension changes (.emf/.wmf/.pcz/.png) from counting as content changes in diffs.
• Tagged code fences (```asn1, ```diameter, ```xml, ```sip, ```sdp, ```latex): Diameter, XML, SIP and SDP blocks carry no code style in the source documents and are detected by content (internal/converter/docx/xmlblock.go, internal/converter/docx/sipblock.go); paragraphs already fenced via style/font keep bare ``` fences and never enter content detection. ```latex is structural, not content-detected: mathFenceBody (internal/converter/docx/mathblock.go) promotes a paragraph whose only content is one formula. Changing fence or notation output requires a database rebuild (make build-db) and a bump of versionstore.cacheSchemaVersion, which wipes old version caches on open.
• Math is format-independent, like image references: ```latex for a standalone equation, $$...$$ for display math where a fence cannot go (a table cell, a list item), $...$ inline. runInfo.Text holds bare LaTeX and runInfo.markdownText() is the only place the delimiters are added — so mergeAdjacentRuns must never merge a math run, or they vanish silently. ommlToLaTeX guarantees the LaTeX carries no </> (escapeMathAngles), which is why internal/converter/docx/table.go can write cell math unescaped and keep & as a matrix column separator.
• Paragraph indentation is preserved as no-break spaces (U+00A0, one source tab = four): trimming it destroyed list nesting (issue #188), and keeping literal tabs/spaces would reopen the CommonMark indented-code-block problem (issue #25). preserveIndent in internal/converter/docx/paragraph.go is the single place the rewrite happens; like fence/notation changes, touching it needs a rebuild and a versionstore.cacheSchemaVersion bump.
• HTTP transport runs stateless (StreamableHTTPOptions{Stateless: true}) — required to serve MCP protocol 2026-07-28; older protocol versions get per-request sessions.
• webmcp.js is a thin same-origin passthrough to /mcp/ (W3C document.modelContext): it registers the tools reported by tools/list at page load, so the browser registration stays in sync with the server without a tool list of its own. The e2e harness (e2e/e2eserver) mounts /mcp/ with the same tools.NewStreamableHTTPHandler as buildHTTPHandler, so the bridge is tested against the real stateless handler.
• --convert-image (EMF/WMF → PNG) requires LibreOffice (soffice) at runtime.
• Tool descriptions stay under 1024 characters. The OpenAI-compatible chat completions API rejects a longer tools[].function.description ("string too long. Expected a string with maximum length 1024"), and clients that front other vendors' models with that API shape (GitHub Copilot, Gemini models included) drop the whole tool list on one over-long description. TestToolDescriptionLength enforces the cap on what tools/list actually returns; detail that does not fit goes into the parameter descriptions (jsonschema tags), which no API caps.