# F5 AI Security Docs MCP Server

An MCP server that provides **search** and **fetch** tools over the entire
[F5 AI Security documentation](https://docs.aisecurity.f5.com/) site, modeled
after the [Strands Agents MCP server](https://github.com/strands-agents/mcp-server).

It exposes two tools to MCP-compatible AI assistants:

- **`search_docs`** – TF-IDF, Markdown-aware ranked search across all docs pages.
- **`fetch_doc`** – Token-efficient reader: page catalog → table of contents → individual sections.

## How it enumerates the whole site

`docs.aisecurity.f5.com` is a **VitePress** static site. VitePress publishes a
complete page manifest at **`/hashmap.json`** whose keys are the markdown source
paths for every rendered page. The server downloads that file once at startup and
derives a URL for each page:

```
api-docs_first-steps.md           -> /api-docs/first-steps.html
release-notes_2026-06-17-saas.md  -> /release-notes/2026-06-17-saas.html
operations_get_scans.md           -> /operations/get_scans.html
index.md                          -> /index.html
```

(First `_` becomes the section separator; `.md` becomes `.html`.)

This captures **all ~219 pages** — `system-overview/`, `get-started/`,
`application-docs/`, `api-docs/`, `api-reference/`, the full REST `operations/`
reference, `integrations/`, `red-team/`, `use-cases/`, `reference/`, `glossary`,
and `release-notes/` — with no fragile HTML crawling.

## Architecture

```
src/f5_aisec_mcp_server/
  config.py              # base_url, allowed host, hashmap path, timeouts
  server.py              # search_docs + fetch_doc MCP tools
  utils/
    page_source.py       # download /hashmap.json -> [(title, url), ...]
    cache.py             # global index + lazy page hydration
    doc_fetcher.py       # HTTP fetch + VitePress HTML -> clean text
    indexer.py           # lightweight TF-IDF inverted index (stdlib only)
    text_processor.py    # titles, snippets, TOC/section parsing
```

**Flow:** at startup the hashmap is parsed and the TF-IDF index is seeded with
page titles only (no content fetched → fast start). `search_docs` ranks by title,
then lazily fetches the top results to build content snippets. `fetch_doc` lets
the model browse a page's TOC and pull just the section it needs.

## Install / Run

Requires Python 3.13+ (developed and tested on 3.13.14).

```bash
cd f5-aisec-mcp
python3.13 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"

# Quick-test with the MCP Inspector
npx @modelcontextprotocol/inspector python -m f5_aisec_mcp_server
```

## MCP client configuration

Point `command` at the venv's Python (absolute path) so the right interpreter
and installed `mcp` package are used:

```json
{
  "mcpServers": {
    "f5-aisec": {
      "command": "/Users/<<USER>>/path/to/project/f5-aisec-mcp/venv/bin/python",
      "args": ["-m", "f5_aisec_mcp_server"],
      "env": { "FASTMCP_LOG_LEVEL": "INFO" },
      "disabled": false,
      "autoApprove": ["search_docs", "fetch_doc"]
    }
  }
}
```


## Tests

```bash
pytest tests/
```