Imported from cisco-open/cisco-api-guide-mcp (AGENTS.md). Install upstream with npx skills add cisco-open/cisco-api-guide-mcp. Copyright stays with the author.

AGENTS.md

Project

MCP (Model Context Protocol) server providing LLM-accessible Cisco API documentation for ACI, NDFC, and Intersight (and pluggable modular APIs). Runs over stdio as a JSON-RPC 2.0 server (or streamable HTTP). API documentation modules are downloaded on demand and cached locally.

Layout

cmd/cisco-api-guide/   # Production MCP server binary
cmd/ingest/            # Dev-only DB ingestion CLI
internal/db/           # SQLite queries, schema, types, multi-module DB manager
internal/modules/      # Module fetcher, caching, checksum verification, registry manifest
internal/mcp/          # MCP tool definitions and server
internal/search/       # FTS5 query builder + synonym expansion
assets/                # Raw human-readable API specs (OpenAPI JSON/YAML, metadata)
scripts/               # Ingestion orchestration (ingest_all.sh, fetch_aci_jsonmeta.py)
modules.json           # Registry manifest listing modular API download URLs and SHA256

Tech Stack

• Go (CGO-free, static binaries via ncruces/go-sqlite3 WASM)
• SQLite with FTS5 virtual tables and BM25 ranking
• No web framework — raw bufio/encoding/json over stdio or lightweight HTTP
• Modular DBs — Downloaded and cached per module in ~/.cache/cisco-api-guide/ (or OS standard cache path)

Build & Test

go test ./...                                                  # run tests
go build -o bin/cisco-api-guide ./cmd/cisco-api-guide          # local build
go install github.com/cisco-open/cisco-api-guide-mcp/cmd/cisco-api-guide@latest  # install binary

Exposed MCP Tools

CLI Options & Modules

cisco-api-guide --modules aci,ndfc      # load only specific modules
cisco-api-guide --modules all           # load all available modules (default)
cisco-api-guide --data-dir /custom/path # custom SQLite cache directory
cisco-api-guide --auto-update           # check manifest and update cached DBs
cisco-api-guide --http --addr :8080     # HTTP streamable mode

Managing & Adding API Modules

1. Source Specs: Keep all raw OpenAPI JSON/YAML or class metadata in assets/<product>/.... No binary SQLite databases are checked into Git.
2. Local Generation:

   ./scripts/ingest_all.sh

   Generates per-product compressed SQLite DBs (data/aci.db.gz, data/ndfc.db.gz, data/intersight.db.gz) and updates modules.json with computed sizes and SHA-256 hashes.
3. Publishing Releases: Triggered via .github/workflows/publish-module.yml in GitHub Actions to attach .db.gz files to the data-modules-latest release tag.

Key Patterns

• FTS5 + synonyms: Queries expand terms via synonyms table (e.g. vrf → virtual routing forwarding vrf-context) before hitting endpoints_fts.
• Multi-module DB routing: db.Manager aggregates multiple SQLite DBs, executing parallel/unified FTS queries and routing detail calls.
• Token-efficient output: Tools return formatted plain text, not JSON, to minimize LLM context usage.
• Product aliases: ucs/dcnm resolve to intersight/ndfc internally.

Products