# akamai-docs-mcp

A local MCP server over Akamai TechDocs, scoped to **CDN, Security, DNS, and
EdgeWorkers** (Akamai Cloud is intentionally excluded — use the official
`akamai-cloud-mcp` for that).

Docs are pulled from Akamai's own `llms.txt` indexes (Markdown-formatted page
lists per product), so no HTML scraping is involved.

## 1. Install

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

## 2. Ingest the docs

```bash
python ingest.py
```

This downloads pages for every slug listed in `config.py` (currently:
`property-mgr`, `purge`, `adaptive-media-delivery` for CDN; `application-security`,
`network-lists` for Security; `edge-dns` for DNS; `edgeworkers` for EdgeWorkers)
into `docs_corpus/`.

Useful flags:
```bash
python ingest.py --categories dns edgeworkers   # only ingest a subset
python ingest.py --limit-per-slug 15            # quick test run, few pages per slug
```

Re-run `ingest.py` any time to refresh the corpus — it overwrites existing files.

## 3. Test the server locally

```bash
npx @modelcontextprotocol/inspector python server.py
```

Try calling `search_akamai_docs` with something like `"activate a security
configuration version"` or `"edgeworkers subworker limits"`.

## 4. Wire it into Claude Desktop / Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "akamai-docs": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/akamai-docs-mcp/server.py"]
    }
  }
}
```

Restart the client. You should see three tools available:
- `search_akamai_docs(query, category?, top_k?)`
- `get_full_doc(path)`
- `list_categories()`

## Adjusting scope

Edit `PRODUCT_SCOPE` in `config.py` to add/remove product slugs per category.
Find a slug by visiting any TechDocs page for that product and looking at the
"For AI agents" line at the top, which points to `.../<slug>/llms.txt`.

## Notes

- Search is BM25 keyword search (`rank_bm25`) — no embeddings, no external
  API calls at query time. Good enough for a PoC/demo; swap in a vector store
  later if recall becomes an issue on paraphrased queries.
- This server is **read-only and docs-only**. For live account/API access
  (properties, DNS zones, security configs, EdgeWorkers deployments), pair it
  with Akamai's official MCP servers rather than extending this one.