NetLicensing-MCP: Instructions file for Codex

AGENTS.md

This file provides guidance to AI Agents when working with code in this repository.

Overview

netlicensing-mcp is a FastMCP server that exposes the Labs64 NetLicensing REST API as MCP tools and prompts. It runs over stdio (Claude Desktop / Copilot) or streamable HTTP (remote deployments). Python ≥ 3.12, async throughout.

Development commands

# Install dev environment (editable + dev extras)
pip install -e ".[dev]"
pip install hatch hatch-vcs

# Run the server locally
python -m netlicensing_mcp.server          # stdio (default)
python -m netlicensing_mcp.server http     # HTTP on $MCP_HOST:$MCP_PORT (127.0.0.1:8000)
mcp dev src/netlicensing_mcp/server.py     # MCP Inspector UI at http://localhost:5173

# Tests (pyproject sets asyncio_mode=auto and turns on coverage automatically)
pytest tests/ -v
pytest tests/test_tools.py::test_name -v   # run a single test
pytest tests/ -v --no-cov                  # disable coverage for faster iteration

# Lint / format / type-check (these are the exact CI checks)
ruff check .
ruff format --check .       # use `ruff format .` to apply
mypy src/

# Security
pip-audit --ignore-vuln CVE-2026-4539 --ignore-vuln CVE-2026-3219

# Build & Docker
hatch build --target wheel  # version comes from git tag via hatch-vcs
docker build -t ghcr.io/labs64/netlicensing-mcp:latest .

CI matrix runs tests on Python 3.12, 3.13, 3.14. Lint/format/mypy run on 3.14 only.

Architecture

Three layers, top-down:

1. server.py — single FastMCP entry point. Each NetLicensing operation is a thin @mcp.tool() wrapper named netlicensing_<action>_<entity> (e.g. netlicensing_create_license). The wrapper's only jobs are: (a) translate empty strings / None defaults into "leave unchanged" semantics, (b) call the matching function in tools/<entity>.py, (c) wrap NetLicensingError into a JSON error blob via _error(). Tools return JSON strings, not dicts — _json() serializes the result and applies the redaction layer. Token create operations additionally call tag_one_time_display() before _json(); token read operations use _json_token_read() which applies redact_token_read() to also mask APIKEY number and SHOP shopURL fields.