unifi-fabric-mcp-server: Instructions file for Codex

AGENTS.md — UniFi Fabric MCP Server

Instructions for AI coding agents and human contributors working on this repository. CLAUDE.md imports this file, so Claude Code reads the same guide.

What this repo is

A Python MCP (Model Context Protocol) server that wraps the UniFi Site Manager cloud API (api.ui.com) as tools for AI assistants. Built with FastMCP. Enables Claude Code and other MCP clients to manage UniFi network infrastructure via natural language.

Pass-through invariant (do not break this)

This server is a faithful pass-through. Tools return whatever the upstream UniFi API returns for a request, unchanged. Do not add runtime filtering, redaction, sanitisation, or field-stripping to tool responses — not for credentials, not for MAC/IP/hostname identifiers, not for GPS coordinates, not for asset URLs.

There are exactly two built-in transforms. The server always replaces its own configured secrets (its API keys, MCP_BEARER_TOKEN, MCP_TLS_KEY_PASSWORD) with *** wherever a response, error or log line echoes them, and the operator's opt-in UNIFI_REDACT_SECRETS masks documented credential fields with ***REDACTED*** (src/unifi_fabric/secret_scrub.py, src/unifi_fabric/redaction.py). Anything else added to a response is a violation.

Why this is a rule and not a preference — the reasoning is the guardrail, because a bare "don't redact" line does not survive the next contributor who thinks they are helpfully cleaning something up (which is exactly how such filtering got written here before and had to be removed):

• This is a layering decision, and the layer is wrong for policy. The server's one job is faithful access. Whether a given caller is allowed to see a passphrase or a coordinate is a policy question that belongs to whoever deploys the server, and they have somewhere to put it — a proxy or wrapper between the consumer and this server.
• The asymmetry is the whole argument. A deployment can always ADD restriction on top of a faithful response (drop a field, mask a value). It can never RECOVER data the tool chose not to return. Withholding by default destroys information irreversibly for every downstream consumer, including the operator who legitimately owns that data and asked for it.
• If you think output should be restricted, you are probably right for your deployment — so restrict it in your deployment, not in this shared access layer. A reviewer may argue for narrowing what a tool returns; the data-survival tests are the check on that, and they are meant to fail such a change loudly.