mcify: Instructions file for Codex

AGENTS.md — AI agent instructions for mcify

This file is read by AI coding assistants (Claude Code, Cursor, Cody, Windsurf, Copilot Workspace, OpenAI Codex, etc.) to understand the codebase and project conventions. Keep it tight and actionable. When something here goes stale, fix it in the same PR that exposed the staleness.

TL;DR

mcify is an open-source platform that turns any API into an MCP (Model Context Protocol) server. CLI-first, local-first, dev-friendly. Apache 2.0. Maintained by Lelemon Studio.

Stack: TypeScript (strict, ESM), Hono, Zod, Pino (opt-in), esbuild, pnpm workspaces, Vitest, Turbo, ESLint flat config, Changesets.

Three publishable packages under the @mcify scope on npm:

Package	Role
@mcify/cli	The mcify binary: init, dev, build, generate
@mcify/core	Builder lib: defineTool, defineResource, definePrompt, defineConfig, schemas, auth
@mcify/runtime	MCP server runtime: stdio + HTTP transports, multi-target adapters

Repository layout

mcify/
├── packages/
│   ├── core/         @mcify/core — pure TS, no runtime deps beyond zod
│   ├── runtime/      @mcify/runtime — Hono + MCP SDK + Pino
│   ├── cli/          @mcify/cli — esbuild + tsx + chokidar
│   ├── inspector/    (Phase B — not yet present)
│   └── examples/     Reference connectors (Phase C)
├── apps/
│   └── docs/         mcify.dev (Astro Starlight, placeholder)
├── .changeset/       Changesets — release management
├── .github/
│   └── workflows/    CI (typecheck/lint/test/build) and Release (changesets/action)
├── .claude/          Slash commands and subagents for Claude Code
├── docs/decisions/   ADRs (Architecture Decision Records)
└── eslint.config.js  Flat config, applies to the whole monorepo

Critical invariants — break these and things go wrong

Workers / edge compatibility

• @mcify/core and packages/runtime/src/dispatch.ts MUST run on Cloudflare Workers, Bun, and Node alike. No Node-only APIs (node:fs, node:child_process, process.cwd(), etc.) in those modules.
• Pino logger is opt-in — Pino uses node:fs internals and breaks on Workers. Default is createConsoleLogger, which is portable.
• Adapters in packages/runtime/src/adapters/{node,bun,workers}.ts are runtime-specific. Node-only code lives there, not in shared modules.
• Cloudflare Workers do not preserve module-level state across cold starts in the way Node does. The Hono app must be built once per handler instance, not per request (we hit this bug in createWorkersHandler).