elysia-mcp-adapter: Instructions file for Codex

AGENTS.md

This repository contains @mwillbanks/elysia-mcp-adapter, an Elysia plugin that exposes Elysia HTTP routes and standalone MCP primitives through a Model Context Protocol HTTP endpoint.

Operating principles

• Treat the adapter as production infrastructure.
• Preserve Elysia semantics. Route-backed MCP calls must invoke app.handle(new Request(...)) rather than calling route handlers directly.
• Avoid introducing a second application framework inside the plugin.
• Keep MCP-specific abstractions thin and protocol-oriented.
• Prefer explicit opt-in for resources and prompts. HTTP routes become tools by default.
• Avoid model-controlled access to headers, cookies, credentials, or filesystem data unless explicitly configured.
• Keep route discovery isolated in src/route-inspector.ts because Elysia internals may change.

Development workflow

This project uses Bun as its package manager and test runner. Run these checks before considering a change complete:

bun run lint       # bun fmt --check
bun run typecheck  # bun check
bun test           # bun:test suites in test/
bun run fallow     # dead code + duplication gate
bun run build      # TypeScript 7 ESM + d.ts output

Commits are validated by husky: commit-msg runs commitlint (Conventional Commits) and pre-commit runs bun fmt on staged files. Releases are automated by release-please (.github/workflows/release.yml) from Conventional Commit history.

Source map

• src/plugin.ts: Elysia plugin entrypoint and macro registration.
• src/methods/install.ts: Runtime installation of .mcpTool(), .mcpResource(), and .mcpPrompt().
• src/registry.ts: Registry builder for explicit and route-backed tools/resources/prompts.
• src/route-inspector.ts: Elysia route discovery adapter.
• src/route-filters.ts: allowedRoutes / excludedRoutes behavior.
• src/schema/*: JSON Schema normalization, composition, and validation.
• src/invoke/*: Internal Elysia request construction and response marshaling.
• src/transport/json-rpc.ts: MCP JSON-RPC over HTTP transport.