amp-mcp-server: Instructions file for Codex

AGENTS.md — amp-mcp-server

Context for AI coding agents (Claude Code, Codex, etc.) working on this repository.

---

Current state (v0.2.1, 2026-05-01)

• What's running: stable. v0.2.1 ships HTTP auth (bearer + OAuth 2.1), security hardening (host/origin allow-lists, rate limiting, unsafe-binding guard), and a /health liveness endpoint. v0.1 was already verified end-to-end against Will's live homelab AMP at https://amp.darkforge.app.
• Hosting: GitLab is primary (https://gitlab.darkforge.app/weddins/amp-mcp-server). A push mirror to GitHub (https://github.com/eddinsw/amp-mcp-server) is being set up so the public can see the code; PRs from outside contributors land on GitHub but merges happen on the GitLab side.
• CI/CD: GitLab CI builds + pushes Docker images to the GitLab registry on every push to main and on tags. No GitHub Actions.
• Tests: vitest with 23 passing unit tests covering auth middleware (bearer, OAuth, scope check, audience check, error paths). Integration smoke-tested manually for the security guards (rate limit, origin, host, unsafe-bind refuse).
• Build: npm run build clean. npm test clean.

The earlier Phase A–D framing is retired — that was v0.1 packaging. We're past it.

What this is

An MCP (Model Context Protocol) server that wraps CubeCoders AMP (Application Management Panel) so MCP clients — Claude Desktop, Claude Code, Claude.ai, others — can list, inspect, and control AMP-managed game-server instances.

CubeCoders AMP is a paid, self-hosted game-server control panel. This project is a client of AMP's public REST API; no AMP source or binaries are redistributed. Users bring their own licensed AMP install.

Why it exists

No MCP server existed for AMP. Will runs AMP in his homelab. Building this gives Claude direct, structured access to start/stop game servers, send console commands, take backups, and read server state without screen-scraping the AMP web UI.

Architecture

MCP client (Claude.ai / Desktop / Code / custom)
        │  stdio  ── or ──  HTTP (stateless Streamable + bearer/OAuth)
        ▼
   amp-mcp-server
        │
        ├─ src/transports/{stdio,http}.ts   (transport entrypoints)
        ├─ src/server.ts                    (per-request McpServer factory)
        ├─ src/tools/{instances,console,operations}.ts (registered tools)
        ├─ src/auth/{bearer,oauth,shared}.ts (HTTP auth middleware)
        ├─ src/config.ts                    (zod-validated env loader)
        └─ src/amp-client.ts ── REST/JSON ──▶  AMP install (homelab)
                  └─▶ @neuralnexus/ampapi  (typed AMP client; native fetch, no transitive deps)