@rikology/adonisjs-mcp
v0.1.0
Published
Development-only MCP endpoint embedded in a running AdonisJS v7 application
Maintainers
Readme
@rikology/adonisjs-mcp
A development-only Model Context Protocol endpoint embedded in a running AdonisJS v7 application. Connect an agent to the application's actual routes, configuration, models, middleware, logs and integrations instead of asking it to guess from source files. It also offers explicitly mutating tools for requests, trusted evaluation, rendering and Ace commands.
The server is named adonis and uses Streamable HTTP at /__adonis/mcp by default. It shares the application's HTTP port; it does not start a separate daemon. Read adonis://profile (or call get_project_profile) first: capabilities explain which definitions are served, disabled or unavailable for this request.
This is a trusted local development interface, not a sandbox or an authenticated public API. Never expose it through a public proxy or tunnel. Use disposable development data when exercising mutating tools.
Requirements and compatibility
Install as a development dependency in an AdonisJS v7 application and run its development HTTP process. GitHub Actions runs the CI matrix below on every push and pull request; it is not a claim of universal driver, platform or patch-version compatibility.
| Component | Version or boundary |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js | Minimum 24.11.1; latest Node 24 |
| AdonisJS Core | Peer range ^7.5.2; minimum 7.5.2; fixture lockfiles 7.6.0 |
| Lucid | Minimum complete starter-kit tuple 22.4.0; fixture lockfiles 22.4.2 |
| MCP SDK v2 | @modelcontextprotocol/server 2.3.1; @modelcontextprotocol/node 2.1.1 |
| MCP protocol | Official SDK clients: 2026-07-28 and 2025-11-25 |
| Operating system | CI: ubuntu-latest (x64) and macos-latest (arm64) |
| Raw SQL | SQLite file databases (better-sqlite3 13.0.3); owned PostgreSQL from apt on Ubuntu and Homebrew postgresql@18 on macOS, with a dedicated reader role |
| Inertia | React and Vue tested; Svelte and Solid not claimed |
| Tenant integration | @rikology/adonisjs-tenant 1.0.2 |
| Queue | @adonisjs/queue 0.6.2 + @boringnode/queue 0.6.0, database driver |
| Permissions | @adonisjs/bouncer 4.0.1: abilities and policy registrations |
CI matrix (also reused by release verification against the single packed artifact):
| Runner / architecture | Node | Core / Lucid | Database | Gate | | -------------------------------------------- | --------------------- | ---------------------------------- | ------------------------------ | -------------------------------------------------------------------- | | ubuntu-latest / x64 | 24.11.1 and latest 24 | 7.6.0 / 22.4.2 (fixture lockfiles) | SQLite; PostgreSQL from apt | Full integration, including eval/HMR, lifecycle and matrix scenarios | | macos-latest / arm64 | 24.11.1 and latest 24 | 7.6.0 / 22.4.2 (fixture lockfiles) | SQLite; Homebrew postgresql@18 | Full integration, including eval/HMR, lifecycle and matrix scenarios | | ubuntu-latest / x64 and macos-latest / arm64 | 24.11.1 | 7.5.2 / 22.4.0 | SQLite | compat-min: pack, database inspection and production-prune smoke | | ubuntu-latest / x64 and macos-latest / arm64 | latest 24 | 7.6.0 / 22.4.2 (fixture lockfiles) | SQLite; PostgreSQL as above | Pack/production-prune, both protocol-era clients, security suite |
Local evidence additionally covers a Debian bookworm arm64 container on Node 24.21.0 and 24.11.1. PostgreSQL minor versions are not pinned by CI.
Node 24.0.0 and 24.0.2 fail the starter kit's Knex imports under the synchronous TypeScript loader. HMR fails with an undefined source on the tested 24.1.0, 24.2.0, 24.5.0, 24.8.0, 24.10.0 and 24.11.0 releases; 24.11.1 is the first passing boundary tested. Core releases before 7.5.1 lack the current starter kit's ./ignitor export, and the 7.5.1 tarball lacks its exported commands entry. Lucid 22.0.0 works for the live database inspection scenario, but the current starter kit's production build needs the ./plugins/db export introduced in 22.4.0. The declared Core range and CI minimum tuple therefore use 7.5.2/22.4.0.
Optional integrations are not prerequisites for boot. Tools that need them are withheld with a reason. Source AST extraction and source symbol lines require the application's TypeScript compiler. Installed documentation and source lookup are tested with outbound networking disabled. Windows, other Node major versions and other database drivers are not covered. Linux test containers need an init process (docker run --init) to reap orphaned Ace children after an HTTP hard restart; tests never use an existing PostgreSQL service.
Install and configure
npm install --save-dev @rikology/adonisjs-mcp
node ace configure @rikology/adonisjs-mcp
npm run devThe configure hook is idempotent and preserves existing user files. It:
- Creates
config/mcp.ts, createsproviders/mcp_dev_provider.ts, and registers#providers/mcp_dev_provideronce inadonisrc.tsforenvironment: ['web']. - Offers capture instrumentation: a development-only
start/mcp_dev_hooks.tsgateway,hooks: { streamWrite }on the default logger inconfig/logger.ts, andobserveException(error, ctx)as the first statement ofhandle()inapp/exceptions/handler.ts. An existing stream hook is composed, not replaced. Unrecognized shapes are skipped with manual instructions. - Offers the evaluator flag: prefixes an existing
scripts.devwithNODE_OPTIONS=--experimental-vm-modulesonly when the flag and anotherNODE_OPTIONSassignment are absent. Otherwise, and always on Windows (cmd.execannot parse the inline assignment), it gives a manual instruction. The inline assignment replaces aNODE_OPTIONSvalue exported in your shell for that script; merge them by hand if you rely on one. - Copies the shipped skill to
.claude/skills/adonisjs-mcp/SKILL.mdonly if.claude/already exists. It never creates.claude/implicitly. - Prints client next steps using
PORT=from.env(default 3333) and the existing config path (default/__adonis/mcp), without printing.envcontents. When the path or port is not a literal value, it says so and asks you to substitute the actual one.
Options:
| Flag | Effect |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| --instrument / --no-instrument | Enable or skip capture wiring. |
| --vm-modules / --no-vm-modules | Enable or skip dev script flag insertion. |
| --force | Allow stub/skill replacement; review existing customizations before using it. |
When an instrumentation or VM flag is omitted, an interactive TTY gets a confirmation (default yes). Non-interactive runs without the flag skip that step and list it in next steps. For an explicit setup:
node ace configure @rikology/adonisjs-mcp --instrument --vm-modulesThe application needs the #providers/* import alias, and the #start/* alias for capture instrumentation (without it configure leaves logger and handler untouched and prints the manual step). Keep production-loaded files free of unconditional runtime imports from this development dependency or zod.
Why the wrapper and type-only config matter
Adonis loads config in production and console processes too. After npm ci --omit=dev, the MCP package may not exist. Therefore app config is a plain object with a type-only import, not a runtime call to defineConfig:
import type { McpConfig } from '@rikology/adonisjs-mcp'
export default {
enabled: true,
path: '/__adonis/mcp',
} satisfies McpConfigThe app-local provider imports the package only in development:
import app from '@adonisjs/core/services/app'
export default app.inDev
? (await import('@rikology/adonisjs-mcp/providers/mcp_provider')).default
: class McpDisabledProvider {}The package provider also checks development mode. Logger/exception instrumentation imports the app-local gateway, whose package import is likewise development-guarded. Lazy extraTools prevent production config from evaluating extension imports.
Client recipes
Start the app first. Substitute its actual port/path in each recipe. These are client-specific formats, not interchangeable files. Official documentation was consulted on October 13, 2026. The endpoint implements no OAuth; do not invent an authentication token or use a client's Authenticate action as setup.
Claude Code
Official MCP documentation verifies the HTTP command and project .mcp.json format:
claude mcp add --transport http adonis http://localhost:3333/__adonis/mcp
claude mcp get adonisFor project scope, use --scope project with the add command, or place this in the project root .mcp.json and approve the server in Claude Code:
{
"mcpServers": {
"adonis": {
"type": "http",
"url": "http://localhost:3333/__adonis/mcp"
}
}
}Verification status: exercised with Claude Code 2.1.295 on macOS against a configured fixture application: claude mcp add --scope project wrote the .mcp.json above (the server stays “Pending approval” until approved in interactive claude), and headless claude -p --mcp-config .mcp.json ran /mcp__adonis__debug_request /invoices GET (route → real request → exception → source → fix → re-run) and /mcp__adonis__add_feature reports-list (inspection → Ace scaffolding → migration → HTTP check) end to end. Claude Code passes prompt arguments as whitespace-separated positional values: a multi-word feature cannot be passed in one argument, so use a single token such as reports-list and describe the feature in the next message. A connected status alone does not verify a workflow.
Cursor
Place this in .cursor/mcp.json:
{
"mcpServers": {
"adonis": {
"url": "http://localhost:3333/__adonis/mcp"
}
}
}Official Cursor MCP documentation. Verification status: not verified with Cursor Agent 2026.05.20-2b5dd59 on macOS. The configuration above was installed in a real configured application's .cursor/mcp.json; cursor-agent mcp list reported adonis: not loaded (needs approval). Headless execution with --trust --approve-mcps --output-format stream-json stopped with “Free plans can only use Auto” before any MCP tool call. Retrying with --model auto timed out after 240 seconds without tool-call results; a second read-only --mode ask attempt timed out after 120 seconds. This is an observed client/account execution blocker, not evidence of a server incompatibility. No tool or prompt execution was verified.
For a headless smoke after starting the app, run from its root:
cursor-agent -p --trust --approve-mcps --model auto --output-format stream-json \
"Call adonis get_project_profile and get_routes and report their actual results."--approve-mcps approves every configured MCP server; use it only in a trusted workspace. A discovery/approval status alone is not verification.
VS Code
Place this in .vscode/mcp.json:
{
"servers": {
"adonis": {
"type": "http",
"url": "http://localhost:3333/__adonis/mcp"
}
}
}Official VS Code MCP configuration reference. Verification status: not verified with VS Code 1.125.1 on macOS. The file above was installed in a running fixture application. code chat --help exposes an agent-mode editor chat, not a headless result stream. Background GUI launches (including an isolated --user-data-dir) reached the fixture workspace/welcome screen, but the windows disappeared before the MCP server could be started and an agent-mode tool call observed; the isolated MCP log remained empty. The initial workspace screenshot showed the trust dialog and “Unable to resolve your shell environment in a reasonable time.” Neither connection nor tool execution was verified; this is a local GUI execution blocker, not an observed MCP protocol failure.
Zed
Merge this into the settings file opened by zed: open settings file:
{
"context_servers": {
"adonis": {
"url": "http://localhost:3333/__adonis/mcp"
}
}
}Official Zed MCP documentation. Verification status: not verified with Zed 1.23.3 on macOS. The configuration above was placed in the fixture's .zed/settings.json. Repeated background GUI launches, including an isolated --user-data-dir, returned a running process but exposed no surviving workspace window to automation. Consequently no server status, OAuth dialog, tool call, or prompt execution was observed.
Zed documents tools and prompts support, not full resource support. Its documentation also says URL servers without an Authorization header prompt for OAuth. This endpoint has no OAuth, so that remains a documentation-only interoperability caveat, not an observed failure in this smoke. Do not add a fictitious token to work around it; the documented JSON shape is not a guarantee of a working connection.
Configuration reference
Every key is optional. Unknown options are rejected in development; resolved config is frozen. Arrays replace defaults rather than append to them. Counts, byte limits and deadlines are positive integers; deadlines below are milliseconds.
| Key | Default | Meaning |
| --------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| enabled | true | Kill switch; false registers no endpoint. |
| path | '/__adonis/mcp' | Exact absolute path, no trailing slash, parameters, wildcards, query, encoding or dot segments. |
| allowRemoteAccess | false | Permit non-loopback peers; does not bypass Host/Origin checks or provide authentication. |
| allowedHosts | [] | Additional exact Host values (hostname or hostname:port), no wildcards. |
| allowedOrigins | [] | Additional exact HTTP(S) origins, no paths/wildcards; absent Origin accepted, null rejected. |
| limits.maxRequestBytes | 1048576 (1 MiB) | MCP body limit. |
| limits.maxResultBytes | 262144 (256 KiB) | Serialized tool/resource result limit; truncation stays valid JSON and is labelled. |
| profile.surfaces.web.prefix | auto-detected | Correct web path prefix. |
| profile.surfaces.web.guard | auto-detected | Correct web impersonation guard. |
| profile.surfaces.api.prefix | auto-detected | Correct API path prefix. |
| profile.surfaces.api.guard | auto-detected | Correct API impersonation guard. |
| profile.surfaces.default | auto-detected | 'web' or 'api'; ambiguous hybrid requests require an explicit surface. |
| tools.disabled | [] | Never serve these tool names, including extensions. |
| tools.projectEval | { timeout: 30000 } | false disables evaluation. |
| tools.projectEval.timeout | 30000 | Default/max cooperative wait; not an execution deadline. |
| tools.sql.readOnly | true | Database-enforced read-only raw SQL. False opts into writes on the application pool. |
| tools.sql.maxRows | 100 | Returned row limit for raw SQL and model queries; maximum 10000. |
| tools.sql.allowCrossTenant | false | Explicit cross-tenant reads, labelled in results. |
| tools.sql.timeout | 10000 | Default/max SQL statement deadline; see write-mode limitations. |
| tools.sql.readers | {} | Dedicated PostgreSQL reader configs keyed by Lucid connection name. |
| tools.logs.bufferSize | 1000 | Log entry count, maximum 100000. |
| tools.logs.bufferBytes | 2097152 (2 MiB) | Log serialized byte budget. |
| tools.logs.exceptionBufferSize | 100 | Exception count, maximum 10000. |
| tools.logs.exceptionBufferBytes | 1048576 (1 MiB) | Exception serialized byte budget. |
| tools.docs.include | ['@adonisjs/*', '@rikology/*'] | Installed package names/scope patterns to index offline. |
| tools.http.timeout | 30000 | Request deadline; does not undo app execution. |
| tools.http.tenantDomain | null | Parent domain for subdomain tenant resolver, hostname without port; unnecessary for header/path resolvers. |
| tools.ace.timeout | 30000 | Console process deadline; owned POSIX process group can be killed, side effects remain. |
| extraTools | [] | Lazy imports returning a default tool or array of tools. |
Both log byte budgets accept 64 KiB through 256 MiB. Oldest entries are evicted first and oversized entries shortened. Buffers are in-memory, bounded and not a durable audit log.
A PostgreSQL reader is either { connectionString: string } (inherits nothing) or { user, password?, host?, port?, database?, ssl? } (omitted connection fields inherit Lucid config). ssl accepts a boolean or options object; port is 1–65535. Configure credentials from the application's environment without pasting them into documentation:
import env from '#start/env'
import type { McpConfig } from '@rikology/adonisjs-mcp'
export default {
tools: {
sql: {
readers: {
pg: {
user: env.get('MCP_READER_USER'),
password: env.get('MCP_READER_PASSWORD'),
},
},
},
docs: { include: ['@adonisjs/*', '@rikology/*'] },
},
extraTools: [() => import('#start/mcp_tools')],
} satisfies McpConfigDeclare those environment variables in the app's Env schema. The PostgreSQL reader must not be superuser, must lack write privileges, and must lack BYPASSRLS for tenant-scoped queries. No reader means no read-only raw SQL on that PostgreSQL connection: there is no fallback to a write-capable application pool.
Tool catalogue
Availability is evaluated per request. Config/registry disabling applies to every tool; dependency presence alone does not prove an integration is active. Read tools/list and profile capabilities, including their diagnostics.
| Tool | Purpose and boundary |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get_project_profile | Project kind, surfaces, guards, generated artifacts and capabilities; read first. |
| get_routes | Committed routes, domains, middleware and surface evidence; executes no handler. |
| get_middleware | Ordered server/router/named stacks; executes no middleware. |
| get_logs | Redacted bounded log records, cursor/request/call filtering; needs capture instrumentation. |
| get_last_exceptions | Handled HTTP exceptions, fingerprints and request references; needs capture instrumentation. |
| get_container_bindings | Partial declared/observed inventory verified with hasBinding; constructs no service. |
| get_events | Persistent listener metadata; emits no events or listener imports. |
| get_config | Resolved config subtree with redaction; calls no getters or lazy providers. |
| get_env | Env schema/presence, never values; needs application TypeScript. |
| get_models | Lucid model metadata; requires Lucid, imports trusted modules but queries no rows. |
| query_model | Structured Lucid SELECTs with scopes/hooks/serializers; requires Lucid; app hooks can have side effects. |
| execute_sql_query | Physical rows; requires Lucid and supported reader/driver; read-only by default, explicitly mutating when readOnly: false. |
| get_migrations | Lucid files/history status; never runs migrations or creates the history table. |
| diff_schema | Lucid metadata versus physical schema; never generates/runs migrations. |
| http_request | Real request to the app's own loopback socket; requires a usable listener; middleware/handlers can mutate even on GET. |
| get_validators | Compiled Vine AST; needs Vine, imports validator modules but does not validate or run rule callbacks. |
| get_inertia_pages | Static route/page/prop references; needs Inertia and application TypeScript; never executes controllers. |
| get_shared_props | Static middleware share/flash keys; needs Inertia and application TypeScript; never evaluates values. |
| get_transformers | Transformer source/generated Data aliases; needs application TypeScript, not necessarily Inertia. |
| get_tuyau_schema | Runtime routes and generated/type-only declarations; needs Tuyau and application TypeScript; no generation or execution. |
| get_views | Edge mounted template/component inventory; needs Edge, imports Edge but does not render. |
| render_view | Renders an inventoried Edge view with JSON state; needs Edge; helpers/templates can mutate, request globals may fail. |
| get_permissions | Bouncer ability names and policy registrations; needs Bouncer; imports trusted modules, never makes authorization decisions. |
| get_queue_jobs | Configured job registration/counts; needs queue integration; imports trusted modules, never dispatches jobs; expanded status needs tested database adapter. |
| project_eval | Trusted dev REPL in the running HTTP app; needs VM flag; can change data/files, access secrets/network and freeze the server. |
| run_ace_command | Fresh console process with structured args/flags; requires POSIX runner; generators/migrations/provider boot can mutate. |
| get_source_location | Alias/path/package/symbol resolution without execution; symbol lines need application TypeScript. |
| search_package_docs | Offline lexical search of allowlisted installed README/docs/declarations; needs discoverable node_modules; no network. |
For http_request, pass a path, never an external URL. Use as: { userId, guard? }, tenant, surface or domain only when the task calls for them. Impersonation supports Lucid-backed access tokens and cookie sessions, not arbitrary guards/session stores. The tool sets protected headers and traverses the app's normal middleware chain; it cannot be used as an arbitrary HTTP proxy.
Resources and prompts
Resources return read-only, redacted JSON with evidence/limitations:
| Resource | Content |
| ----------------------- | ----------------------------------------------------------------------------------- |
| adonis://profile | Same project profile/capabilities as get_project_profile. |
| adonis://routes | Unfiltered route inventory. |
| adonis://models | Unfiltered model metadata; requires Lucid, imports model modules. |
| adonis://config/{key} | Resolved config at a dot key, e.g. adonis://config/auth. |
| adonis://package | Allowlisted manifest fields and safe resolved rc metadata; runtime/source evidence. |
The package resource includes only manifest name, version, private, type, engines, packageManager, imports, dependency maps and scripts. Dependency ranges and script commands are masked for URL userinfo (https://<token>@host, https://user:pass@host), sensitive query parameters (?token=), secret-like NAME=value assignments, secret-like CLI flag values (--password x, --authToken=x) and known secret environment values; package and script names are kept. Rc metadata includes TypeScript/directories, provider/preload/command literal import specifiers, environments, command aliases, meta files, test suites/timeouts, experimental options and hook counts. Dynamic import identities are null with limitations; functions are never stringified.
Prompts return one user message, not an automatically executed operation. All arguments are strings. References are limited to served definitions; relevant unavailable definitions are listed with reasons.
| Prompt | Arguments | Workflow |
| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| debug_request | Required path; optional method (GET default), userId, guard, tenant, surface (web/api) | Profile → route → real HTTP request → exceptions/logs → source → fix → re-run; passes impersonation/tenant only when supplied. |
| add_feature | Required feature; optional surface (web/api/both) | Profile-aware API, Inertia or Edge plan; hybrid without surface asks the user first. |
For API, plan validator/controller/route/JSON HTTP tests. Inertia adds node ace make:page, transformers and Inertia-header tests. Edge adds templates and rendering/HTTP tests. Hybrid both uses one validator, one service, a shared transformer and two thin controllers. Generated controller/Data aliases appear only when profile evidence says they exist. Building a prompt performs no database query, HTTP request or evaluation.
Extension API
Another provider can register definitions in boot() while mcp.registry is open. Check the binding before importing this dev-only package or Zod so production remains safe:
import type { ApplicationService } from '@adonisjs/core/types'
export default class AppToolsProvider {
constructor(protected app: ApplicationService) {}
async boot() {
if (!this.app.container.hasBinding('mcp.registry')) return
const { defineTool } = await import('@rikology/adonisjs-mcp')
const { z } = await import('zod')
const registry = await this.app.container.make('mcp.registry')
registry.tool(
defineTool({
name: 'app_identity',
description: 'Reads the running application name.',
inputSchema: z.object({}),
annotations: { readOnlyHint: true, destructiveHint: false },
handler: async (_input, context) => ({
data: { name: context.app.config.get('app.appName') },
evidence: ['runtime'],
}),
})
)
registry.extend(async (_call, next) => next())
registry.disable('project_eval')
}
}defineTool accepts a Zod v4 object schema, infers handler input, validates snake_case names and preserves definition metadata. available(context) can return { available: true } or { available: false, code, reason }; broken checks are reported as INTEGRATION_FAILED. ToolContext includes app, resolved config, lazy profile, call ID, cancellation signal, optional capture readers and per-call tenancy.
extend(wrapper) wraps tool invocation in registration order (outermost first); call next() to delegate. disable(name) withholds a tool regardless of registration order. registry.resource(...) and registry.prompt(...) register corresponding typed definitions. Duplicate names/URIs and registration after finalization are rejected. Definitions finalize in ready() and a fresh MCP server serves the immutable snapshot per request; registry/buffers belong to the app, not individual clients.
Alternatively, export defineTool(...) or an array as the default of #start/mcp_tools, and use the lazy extraTools config shown above. The loader runs only in development. Never eagerly import the module into config/mcp.ts, and do not add an unconditional runtime MCP import to a provider loaded in production. Restart the dev process after changing provider registrations or extraTools; atomic registry rebuild on HMR is not implemented.
Agent skill
One English source, skills/adonisjs-mcp/SKILL.md, is shipped in the npm tarball and copied by configure when .claude/ exists. It can also be installed from the repository:
npx skills add rikoriswandha/adonisjs-mcpThe skill derives conventions from the profile instead of imposing Inertia on API/Edge projects.
Security model
- Local trust, not authentication. Loopback peer checks use the socket peer, not forwarded headers. Exact Host and Origin checks reduce rebinding/browser exposure; an absent Origin is accepted and local processes remain trusted. MCP has no OAuth.
allowRemoteAccessincreases risk even with allowlists: never use a public proxy/tunnel; any remote use needs an external trusted network boundary. - Trusted application code.
project_evalis a REPL, not a sandbox: imports use the application loader; code can reach data, filesystem, environment and network. Timeout/cancellation only stops waiting, synchronous loops can freeze HTTP, and side effects can continue.--experimental-vm-modulesis mandatory and Node emits anExperimentalWarning. - SQL layers. Default raw SQL uses a dedicated PostgreSQL read-only connection/least-privilege reader or a read-only SQLite child, plus restrictive single-statement policy. Tenant SQL requires proven FORCE RLS and a reader without BYPASSRLS; shared tables without that boundary are refused. SQL policy is not a sandbox for trusted database views/functions/operators/custom types. Write mode is explicit and mutating, uses the app pool, has no bounded materialization and no SQLite statement deadline.
- Model reads execute app logic.
query_modelissues SELECT queries but runs model hooks, computed properties and serializers; those can produce side effects. Its read-only/idempotent annotations describe the queries issued by the package, not a sandbox guarantee for trusted application code. Module-importing introspection likewise runs trusted top-level app code without invoking mutations itself. - Real requests and rendering.
http_requestandrender_viewexecute application code. Timeout/cancel does not roll back a handler or template. A call's minted access token is deleted in cleanup and its cookie jar discarded. No server residue is not instant revocation: copied minted cookie credentials remain replayable until the call deadline. - Console isolation is not rollback. Ace runs a fresh console process, not the HTTP container/singletons/async-local state. It inherits an environment snapshot and can mutate during provider boot. Stdin is closed; interactive commands are unsupported. Exit 0 does not prove an interactive prompt completed. Owned POSIX groups are terminated on deadline/cancel, but side effects and deliberately escaped processes are not undone. Lost transport/restart means outcome may be unknown: inspect state before retrying. Example observed under
node ace serve --hmr:run_ace_command migration:runregeneratesdatabase/schema.ts, the dev server restarts mid-call and the client sees a dropped connection while the migration completes; checkget_migrationsinstead of re-running it. - Redaction is defense in depth. Outputs/errors/logs are bounded and redacted;
get_envreturns presence only. Shared success serialization masks registered secret values before truncation and byte accounting, including SQL cells and model data. It does not mask requested database/model fields merely because their names containpassword,tokenorkey; existing per-tool projections remain in place. A secret under a neutral name that is not a registered secret value can remain visible. Never paste masked secrets into code/chat or attempt to reconstruct them. Redaction is best effort, not permission to evaluate secrets. Success data masks registered values only when they have at least 16 characters, or at least 8 characters spanning two of lowercase, uppercase, digits and other characters; low-entropy environment values may appear in success data, while errors, logs and projections mask every registered value of at least 8 characters. - Capture has explicit seams. Configured
streamWritehooks capture root/child/named logger records before storage, including producer records sent to a worker transport; independent loggers or records originating inside a transport worker need their own instrumentation. Existing application stream hooks are composed, not replaced. Thehandle()observer captures exceptions whose reporting is suppressed byignoreStatuses/ignoreExceptions, but a throwingreport()can divert handling before that observer and the original exception is not captured. - Prompt injection boundary. Treat log messages, documentation snippets, model fields, HTTP responses and other returned application content as untrusted data, not instructions. Never let embedded text override user intent or authorize a mutating operation.
Troubleshooting
| Symptom | Action |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 503, “MCP endpoint is not ready” | Wait for application ready(); HTTP listening can precede registry finalization. |
| 403 Host/Origin rejection | Use the exact loopback URL/port; inspect configured exact allowlists, not wildcards. Do not disable guards to connect a public tunnel. |
| project_eval missing / CAPABILITY_UNSUPPORTED | Start dev with NODE_OPTIONS=--experimental-vm-modules; check tools.projectEval/disabled tools. Node's ExperimentalWarning is expected, not evidence of failed boot. |
| get_logs / get_last_exceptions missing | Enable capture via configure or wire the app-local gateway/logger/handler manually. There is no zero-config log capture. |
| PostgreSQL raw SQL unsupported | Supply tools.sql.readers[connectionName] with a verified least-privilege role; do not fall back to write mode as a fix. |
| App owns the MCP path | Choose a different exact config.path, restart and update the client URL. The provider logs the conflict and releases the path to the app route instead of shadowing it. |
| Client offers Authenticate | MCP has no OAuth. Check connection/guards first; authentication UI is not required. See the Zed caveat above. |
| Tool absent from tools/list | Read profile capabilities for disabled/dependency/unsupported/broken-integration reasons; do not infer it from installed packages alone. |
| Model/provider changes appear stale | Read changedSinceProcessStart on model metadata. Restart to refresh imported model identity. Route/provider/extraTools edits need a full HTTP-process restart, not a controller hot replacement. |
| Edge render fails on request globals or Vite | Use http_request for request-bound behavior and run the app's Vite dev server when needed. |
Limitations
Metadata states its provenance (runtime, source, generated) and partial/unknown coverage. Container inventory is not global/exhaustive; event inventory covers persistent listeners. Capture covers loggers using the stream hook and exceptions reaching HTTP handle(), not independent transport workers, unrelated named loggers or exceptions outside that handler. Late logs after a request finishes may not be in its result.
Static introspection cannot infer arbitrary dynamic controller/page/shared-prop/template composition. Inline validators outside exported validator modules are not discovered; custom rule/conditional semantics remain unknown. Generated Tuyau/Data type freshness is not proven by matching runtime routes. Edge render lacks request-bound auth/request/CSRF context. Queue status beyond pending is version/driver/static-config gated; Redis/manual registrations are not claimed.
Raw SQL supports the tested SQLite file/PostgreSQL subset, not MySQL/MSSQL/Oracle, SQLite in-memory/URI or schema/database-per-tenant strategies. Tenant HTTP header resolution is integration-tested; subdomain/path resolver support is not equivalent evidence. Impersonation excludes non-Lucid user providers, custom/basic guards and stateful session stores. Legacy protocol cancellation does not reach evaluation's signal.
Source lookup uses verified source-map evidence, not guesses from arbitrary bundles. Docs search is bounded and lexical, not semantic; its package cache keys include manifest realpath/version/mtime, so editing docs without changing package.json does not invalidate it.
The registry is finalized once per HTTP process, then published to the endpoint as one immutable snapshot. Controller hot replacement does not rebuild providers or tools. A full assembler restart builds a new registry before serving MCP; requests during initialization receive 503 rather than a partially built registry. In-flight requests on the old process may lose transport when the assembler kills that process; they are not migrated or retried. Model inventory rescans source generations but never cache-busts ESM imports: changed files are explicitly labeled changedSinceProcessStart. Page inventory reads source files on each call.
In the tested ace serve --hmr fixture boundaries, controller edits keep the HTTP PID; edits to an imported model, routes, providers and start/mcp_tools.ts replace it. Adding/deleting source files can be observed by the next inventory scan without a restart. A deleted page can remain in generated page declarations, but is reported with existsOnDisk: false, never as existing source. Hot-hook boundaries and application watchers are application configuration, not package-owned watchers.
npm run smoke:capacity -- --out /tmp/m9-capacity.json reports cold/warm latency, event-loop delay, post-GC memory, active resources, capture subscribers and emitter listeners. Three equal 240-call windows each contain 216 sequential calls and 24 concurrent fast/slow calls; the first warms bounded caches, the next two measure steady-state retention, then one same-PID controller swap measures HMR retention separately. Idle keep-alive sockets are allowed to settle before sampling. It writes the environment, workload and measurements to both stdout and the requested JSON file. Two-tenant concurrent correctness and temporary impersonation-token cleanup are exercised separately in matrix.spec.ts. Latency and RSS are informational, not pass/fail budgets; both pre-swap and post-swap samples gate resource/listener growth and retained heap growth at 16 KiB per measured call after explicit GC, with at most 8 KiB/call additional growth over the previous steady-state window. The report records both window deltas and separate swap retention so bounded cold caches are not mistaken for per-call leaks. Eval display byte truncation is labeled data.displayTruncated; envelope truncated separately describes result-encoder truncation.
License
MIT.
