mcp-portainer-lite: Instructions file for Codex

AGENTS.md

Compact guide for OpenCode sessions working in this repo.

Toolchain

• Node >= 20, ES modules ("type": "module"), module/moduleResolution: NodeNext. Use .js extensions in relative imports (required at runtime under NodeNext).
• No ESLint/Prettier — npm run lint and npm run typecheck are both tsc --noEmit. Do not look for a separate linter config.
• npm run build compiles src/ -> dist/ (rootDir: src, outDir: dist); tests/ is excluded from tsconfig.json.

Commands

• Dev: npm run dev (tsx watch on src/index.ts).
• Build: npm run build; run built: npm start (stdio) or npm run start:stdio / npm run start:http.
• Tests: npm test (vitest run). Coverage: npm run test:coverage.
• Single test: npx vitest run tests/tools/restart-service.test.ts or npx vitest run -t "pattern".
• CI runs npm run typecheck then npm test on Node 22 and 24. Match that locally before pushing.

Tests

• vitest.config.ts sets globals: true and environment: 'node'; tests live in tests/**/*.test.ts.
• tests/setup.ts stubs env vars (PORTAINER_URL, PORTAINER_API_KEY, PORTAINER_ENDPOINT_ID, ALLOW_MUTATIONS=true, LOG_LEVEL=error) for the whole suite via beforeAll. Don't assume a real Portainer is reachable.
• Tests mock PortainerClient / HTTP — no integration services required.

Architecture

• Entry: src/index.ts (bin dist/index.js). Loads config, validates HTTP config, builds PortainerClient, creates the MCP McpServer, then selects transport from MCP_TRANSPORT.
• src/config.ts owns all env loading and validation; validateHttpConfig requires MCP_AUTH_TOKEN when MCP_TRANSPORT=http.
• src/server.ts registers tools from buildTools() into the MCP McpServer and wraps handlers with safe-error normalization.
• Transport: src/transport/stdio.ts and src/transport/http.ts. HTTP transport adds bearer auth, rate limiting (60 req/min/IP), and 1 MB body limit; defaults HOST=127.0.0.1.
• Tools live in src/tools/handlers/ and are aggregated in src/tools/registry.ts into readOnlyTools and mutationTools. Adding a tool = create handler file + append to the right array in registry.ts; server.ts picks the rest up automatically.
• Mutations are gated by ALLOW_MUTATIONS (default false); buildTools only includes mutationTools when enabled (registry.ts:48).
• src/portainer/client.ts is the only Portainer API surface; src/portainer/resources/ (endpoint.ts, service.ts, stack.ts) wraps resource-specific calls and ID validation (alphanumeric patterns to prevent path traversal).