net-mcp: Instructions file for Claude Code

CLAUDE.md

net-mcp is a FastMCP server that gives LLMs structured access to network engineering data: BGP, RPKI/ASPA, DNS/DNSSEC, IRR, PeeringDB, IP math, and local diagnostics.

Commands

uv sync --group dev       # install (dev group includes pytest + ruff)
uv run pytest -q          # tests are fully offline; ~1s
uv run ruff check src tests && uv run ruff format src tests
uv run net-mcp            # run the server on stdio

Poke a tool in-process (this is also how the tests call tools):

import asyncio
from net_mcp.server import mcp

async def main():
    res = await mcp.call_tool("bgp_prefix_origin", {"prefix": "1.1.1.0/24"})
    print(res.structured_content)

asyncio.run(main())

.mcp.json registers the server for Claude Code sessions opened in this repo.

Architecture

• server.py creates FastMCP("net-mcp") and calls each module's register_<domain>_tools(mcp). Register a new module there.
• tools/<domain>.py defines tools inside that register function with @mcp.tool(tags={...}); private helpers are _-prefixed and live at module level so tests can monkeypatch them.
• models.py holds the DNS/RPKI/BGP result models. IRR, PeeringDB, iptools, and local keep their models in their own module. Both are fine; do not move them for consistency's sake.
• __init__.py holds the shared HTTP layer: get_http_client() (one pooled httpx.Client, sets User-Agent), ripestat_get(), cloudflare_get(), cloudflare_unavailable_reason().
• config.py is a singleton via get_config(). Precedence: NET_MCP_* env vars, then config.toml, then defaults. config.toml is gitignored (it may hold API tokens); config.example.toml is the documented template.

Conventions you cannot infer from one file

Tools are sync def on purpose. FastMCP runs sync tools in a thread pool, so blocking httpx, socket, subprocess, dnspython, and bgpkit calls are correct. Do not make a tool async def unless every I/O call inside it is also async, or it will block the whole server.