net-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

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

Commands

uv sync                  # Install dependencies
uv sync --group dev      # Install with test dependencies
uv run net-mcp           # Run the MCP server
uv run pytest            # Run tests (pytest-asyncio, auto mode)

Test tools interactively:

import asyncio
from net_mcp.server import mcp

async def main():
    tools = await mcp.list_tools()
    result = await mcp.call_tool('tool_name', {'param': 'value'})
    print(result.structured_content)

asyncio.run(main())

Architecture

Entry point: src/net_mcp/server.py — creates FastMCP("net-mcp"), calls register_*_tools(mcp) from each tool module, exposes main().

Tool modules (src/net_mcp/tools/): Each module exports one register_<domain>_tools(mcp: FastMCP) function. Inside, tools are defined with @mcp.tool(tags={...}) decorators. Private helper functions are prefixed with _. Seven modules: bgp.py, dns.py, rpki.py, irr.py, peeringdb.py, iptools.py, local.py.

Models (src/net_mcp/models.py): All Pydantic BaseModel classes for tool inputs/outputs. Every tool returns a model. Parameters use Annotated[type, Field(description="...")].

Shared API helpers (src/net_mcp/__init__.py):

• ripestat_get(path, params) — adds sourceapp=net-mcp to all RIPEstat requests
• cloudflare_get(path, params) — adds Bearer token, returns None if no token configured (callers must handle graceful fallback)

Config (src/net_mcp/config.py): Singleton via get_config(). Loads from env vars (NET_MCP_*) → config.toml → defaults. Key settings: mrt_cache_dir, cloudflare_api_token, bgproutes_api_key, default_collector, default_dns_resolver, allow_active_local_tools (gates local_nmap/local_curl, off by default).