# Local 3GPP MCP Server

A small local [Model Context Protocol](https://modelcontextprotocol.io/) server
that extracts and serves 3GPP specification PDFs from disk. The model remains in
your MCP client; this server makes no external API calls at query time.

## Requirements and setup

- Python 3.11 or newer
- A local checkout of the curated 3GPP documents

Clone the document repository yourself (the server intentionally does not do
this automatically):

```bash
git clone https://github.com/emanuelfreitas/3gpp-documentation.git
```

Create a virtual environment and install the two runtime dependencies:

```bash
cd /full/path/to/3gpp-local-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

## Run

Set `SPECS_DIR` to the cloned repository's `documentation` directory. The
default is `./documentation` relative to the process working directory.

```bash
SPECS_DIR=/full/path/to/3gpp-documentation/documentation python server.py
```

The initial run extracts every readable PDF and writes `.cache/index.json`.
Later starts reuse cached text for files whose path, modification time, and size
have not changed. Corrupt, scanned, and empty PDFs are logged and skipped.

Force a complete rebuild with `python server.py --rebuild`, or call the MCP
`refresh_index` tool. Optional Streamable HTTP mode is available at
`http://127.0.0.1:8000/mcp`:

```bash
SPECS_DIR=/full/path/to/documentation python server.py --http
```

You can also set `MCP_TRANSPORT=http`, `MCP_HOST`, and `MCP_PORT`. Stdio is the
default and is appropriate for desktop MCP clients.

## Tools

- `list_specs()` returns sorted, human-readable spec IDs.
- `search_specs(query, max_results=5)` performs case-insensitive keyword search
  and returns the first context snippet from each matching spec.
- `get_spec(spec_id, max_chars=8000)` returns extracted text, truncated to the
  requested limit.
- `refresh_index()` forces all PDFs to be re-extracted.

## Client configuration

For Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "3gpp-local": {
      "command": "/full/path/to/3gpp-local-agent/.venv/bin/python",
      "args": ["/full/path/to/3gpp-local-agent/server.py"],
      "env": {
        "SPECS_DIR": "/full/path/to/3gpp-documentation/documentation"
      }
    }
  }
}
```

All paths must be absolute. The configured Python interpreter must be the one
where `fastmcp` and `pypdf` are installed—normally the virtual environment shown
above. Cursor uses a near-identical MCP server configuration.

## Verify

The self-contained test suite creates a small text PDF and a corrupt PDF in a
temporary directory; it does not require the document repository:

```bash
python -m unittest -v test_server.py
```

For a real-data smoke test, start the server with `SPECS_DIR` pointing at the
curated checkout and confirm the startup log reports a non-zero indexed count.

## Future phases

Potential upgrades include local semantic/vector search, live 3GPP or ETSI
fetching, and section-aware pagination for very large specs. The v1 tool
signatures can remain stable when those capabilities are added.