cml-mcp: Instructions file for Codex

AGENTS.md — CML MCP Server

Project Overview

cml-mcp is a Model Context Protocol (MCP) server that exposes Cisco Modeling Labs (CML) operations as AI-callable tools. It is written in Python (≥ 3.12) using FastMCP and the virl2_client library. The package is published to PyPI as cml-mcp and to Docker Hub as xorrkaz/cml-mcp.

Compatibility Goal

This server must work across the widest possible range of MCP clients and tool-calling LLMs — flagship hosted models (Claude, GPT-4-class, Gemini), AI Canvas, Cursor, Claude Desktop, LM Studio, and local / open-weight models (Gemma, Llama, Qwen, etc.). Optimize the public surface for the lowest-common-denominator client. In particular, assume the LLM may rely on the per-parameter inputSchema more than on the docstring — small models often parse structured schema cheaply and skim prose. Every design decision (flat primitive args, rich per-parameter constraints, Literal[...] over free strings, typed return shapes) traces back to this goal.

Repository Layout

src/cml_mcp/
  __main__.py          # CLI entry point (cml-mcp command)
  server.py            # FastMCP app wiring; registers all tool modules
  cml_client.py        # Async HTTP wrapper around the CML REST API
  settings.py          # Pydantic-settings config (env vars)
  types.py             # Shared response types used across tool modules
  cml/                 # Auto-generated Pydantic schemas from CML (Cisco license)
  tools/               # One module per functional area (see below)
    cache.py           # Thread-safe async session cache for HTTP mode
    dependencies.py    # Shared CML client dependency and elicitation helper
    middleware.py      # HTTP middleware and ACL enforcement
    model_helpers.py   # Lenient Pydantic construction (strips unknown fields, accepts JSON strings)
tests/
  conftest.py          # Fixtures; USE_MOCKS env var switches mock ↔ live mode
  mocks/               # Pre-recorded JSON responses for offline testing
  input_data/          # Sample topology YAML files
acl.yaml.example       # Reference for HTTP-mode ACL configuration
server.json            # MCP server registry metadata
Justfile               # Task runner (test, build, publish, clean, …)
pyproject.toml         # Build config; linters: black (140), isort, flake8