libredesk-mcp: Instructions file for Codex

AGENTS.md

Project overview

libredesk-mcp is a single-file MCP (Model Context Protocol) server that exposes the Libredesk REST API as MCP tools. It dynamically generates all tools at startup from a bundled OpenAPI 3.0 spec. ~54 endpoints become MCP tools.

• Language: TypeScript (ESM — "type": "module" in package.json)
• Runtime: Node.js ≥ 18
• MCP SDK: @modelcontextprotocol/sdk v1
• Transport: stdio (JSON-RPC over stdin/stdout)
• Single source file: all logic lives in src/index.ts (~390 lines). Key functions are exported for testability; main() is guarded to only run when executed directly (not when imported).

Essential commands

npm install          # install dependencies
npm run build        # tsc → dist/ + copy openapi.json into dist/
npm start            # run compiled output (node dist/index.js)
npm test             # run vitest unit tests
npm run test:watch   # vitest in watch mode
npm run fetch-spec   # update bundled OpenAPI spec from upstream

There is a test suite (vitest, 38 tests) and CI (GitHub Actions with build, test, and Docker integration). There is no linter.

Architecture

src/
├── index.ts       # Everything: spec loader, tool builder, MCP server, HTTP client
└── openapi.json   # Bundled copy of Libredesk's OpenAPI 3.0 spec (~4800 lines)

Startup flow

1. main() loads openapi.json from dist/ (or falls back to src/ during dev via tsx)
2. buildTools() walks every path+method in the spec, flattens parameters and request bodies into MCP tool schemas
3. Tools are registered via ListToolsRequestSchema / CallToolRequestSchema handlers on the MCP Server
4. Server connects via StdioServerTransport and logs readiness to stderr

Tool generation (buildTools)

For each operation in the OpenAPI spec:

• Name: derived from operationId by stripping a handle prefix, splitting camelCase into snake_case (with consecutive-uppercase acronym handling), then lowercasing. Examples: handleGetConversation → get_conversation, handleGetAIPrompts → get_ai_prompts, handleGenerateAPIKey → generate_api_key. Constrained to ≤ 60 chars.
• Description: concatenates summary, description, HTTP method/path, and tags
• inputSchema: type "object" with additionalProperties: true. Properties are built from:
  • Path parameters (always required)
  • Query parameters (required if marked so in spec)
  • Request body properties (dereferenced from $refs). JSON body fields get the spec description prefixed with (body). If a body field name collides with a path/query param, it gets a body_ prefix.