adonis-mcp: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.

Project Overview

@jrmc/adonis-mcp is an AdonisJS package that provides a Model Context Protocol (MCP) server for AdonisJS applications. It allows AdonisJS apps to expose tools, resources, and prompts over MCP via HTTP, stdio, or fake (testing) transports.

Commands

• Build: npm run build (cleans, runs tsc, copies stubs; postbuild indexes ace commands)
• Type check: npm run typecheck
• Format: npm run format (prettier, @adonisjs/prettier-config)
• Run all tests: npm test
• Run a single test file: node --loader ts-node/esm --enable-source-maps bin/test.ts -- tests/unit/path/to/file.spec.ts
• Docs (VitePress): npm run docs:dev / docs:build / docs:preview

Tests use Japa (@japa/runner) with assert and expect-type plugins. Test files live under tests/unit/ with the .spec.ts extension; fixtures (sample tools/resources/prompts) under tests/fixtures/, helpers (fake app, context/request factories) under tests/helpers/.

Architecture

Entry Point and Exports

• index.ts — Public API: exports Tool, Resource, Prompt, McpResponse, defineConfig, and configure.
• configure.ts — AdonisJS package configuration hook (runs on node ace add); publishes stubs/config.ts.stub and the MCP middleware stub.
• package.json exports — many subpath exports consumers rely on (./types/*, ./contents/*, ./annotations, ./transports/*, ./bouncer, ./exceptions, …). When adding a new public module, add the corresponding subpath here.

Core Server (src/server.ts)

The Server class is the central orchestrator. It:

• Holds registered tools, resources, and prompts as path maps (name/uri → file path)
• Dispatches JSON-RPC requests to lazily-imported method handlers
• Binds a transport for sending responses
• Creates ServerContext instances per request