create-codemodekit

Scaffold a runnable, one-file Code Mode MCP server from Local Tools, an upstream MCP command, or a remote MCP URL.

Build with a coding agent

Install CodeModeKit's development skills, then ask your agent to build the server:

npx skills add stjbrown/codemodekit

The skills can also be installed separately with --skill build-codemodekit-server or --skill author-codemode-skill. The generator below installs both automatically, so this step is for existing projects or a skill-first workflow.

Interactive weather starter

npm create codemodekit@latest

The default creates an editable Open-Meteo weather project, companion skill, and portable Agent Plugin. The equivalent non-interactive command is:

npm create codemodekit@latest weather-code-mode -- --example weather

The generated server uses two Local Tools—findLocation and getCurrentWeather—to demonstrate multi-call composition inside one run_typescript execution. No API key is required for Open-Meteo's limited non-commercial endpoint. Use the generated .env.example for customer or self-hosted endpoints.

Wrap an MCP command

npm create codemodekit@latest my-code-mode -- \
  --mcp-name upstream \
  --mcp-command 'uvx my-mcp-server'

cd my-code-mode
npm run verify
npm start

The command is parsed directly into an executable and argument array. Shell operators, shell expansion, and leading environment assignments are rejected; no shell is invoked. Dependency installation is automatic unless --no-install is supplied. The build-codemodekit-server and author-codemode-skill development skills are installed under .agents/skills by default; use --no-authoring-skill to omit both.

Generated servers use --policy allow-all by default so the project runs immediately. Use --policy deny-all when you want the generated server to start closed while you define a narrower tool policy.

Use --mcp-url https://example.com/mcp instead of --mcp-command for a Streamable HTTP source. Add --mcp-bearer-env MCP_TOKEN or repeat --mcp-header-env Header-Name=ENV_NAME to assemble authentication headers from the host environment without writing credential values to source, manifests, or plugin artifacts.

Repeat a complete source group to combine MCPs in one generated catalog:

npm create codemodekit@latest work-code-mode -- \
  --mcp-name github --mcp-command 'docker run -i --rm ghcr.io/github/github-mcp-server' \
  --mcp-name tickets --mcp-url https://tickets.example.com/mcp \
  --mcp-bearer-env TICKETS_TOKEN

Every scaffold includes npm run verify. It validates source discovery, the two-tool downstream surface, invalid calls, and sandbox isolation without calling provider tools. For a semantic live check, set CODEMODEKIT_VERIFY_CODE_FILE to a bounded TypeScript composition that returns { verified: true }. The generated .env.example is documentation; export its variables with your preferred environment manager.

Generate an Agent Plugin

Add --agent-plugin to create a portable Agent Plugins 1.0 package around the Code Mode server:

npm create codemodekit@latest my-code-mode -- \
  --mcp-name upstream \
  --mcp-command 'uvx my-mcp-server' \
  --agent-plugin

This adds root plugin.json and mcp.json files plus skills/use-upstream-codemode/. The generated companion skill is a mechanically correct runtime baseline. Catalog sync writes a complete references/tools.d.ts, one file per source, and bounded tool-prefix shards for large sources; catalog-metadata.json indexes the set. Use the installed author-codemode-skill to add domain triggers, real workflows, safety decisions, and type-correct compositions. After installation, the generator builds a self-contained dist/plugin artifact containing the server bundle, QuickJS WASM, manifests, and runtime skill.

The generator attempts catalog sync after dependency installation. If the upstream MCP still needs credentials or connectivity, the project remains valid with pending references. Configure the source and run:

npm run plugin:sync
npm run plugin:build

Use --no-sync to skip the initial attempt intentionally. The artifact deliberately excludes node_modules, .env, source files, and both development-time authoring skills.

Experimental MCP skill delivery

Add --experimental-mcp-skills alongside --agent-plugin to serve the generated companion skill from the Code Mode MCP server itself:

npm create codemodekit@latest my-code-mode -- \
  --mcp-name upstream \
  --mcp-command 'uvx my-mcp-server' \
  --agent-plugin \
  --experimental-mcp-skills

The generated server uses @olaservo/ext-skills to advertise io.modelcontextprotocol/skills under capabilities.extensions, implement skills/list and skills/get, and expose the skill plus its supporting files through resources/read. Discovery snapshots file bytes and SHA-256 digests once at startup, so restart the server after changing skills/. The dependency is pinned exactly because SEP-2640 and the package remain experimental.

OpenAI's Scan Tools importer recognizes this bounded SEP-2640 subset and imports a submission-time snapshot rather than reading live runtime resources. It accepts at most five uniquely named skills, 100 files per skill, 256 KiB for SKILL.md, 1 MiB per supporting file, 5 MiB per skill, and 8 MiB for the generated scan archive. Re-run Scan Tools after skill changes.

Every generated server can run over either downstream transport. npm start keeps stdio as the default for local MCP clients and the portable Agent Plugin. npm run start:http starts Streamable HTTP at http://127.0.0.1:3000/mcp with readiness at /healthz by default. Set CODEMODEKIT_HTTP_HOST, CODEMODEKIT_HTTP_PORT (or PORT), CODEMODEKIT_HTTP_PATH, and CODEMODEKIT_HTTP_HEALTH_PATH for deployment. Request/response operations do not need sticky sessions across replicas, though every pod owns its upstream connections, catalog, caches, and execution capacity. Binding a container to 0.0.0.0 additionally requires CODEMODEKIT_ALLOW_UNAUTHENTICATED_REMOTE_ACCESS=true; the setting only acknowledges exposure, so terminate TLS and enforce authentication at an ingress or gateway before publishing the stable HTTPS URL.

Cursor lifecycle

Cursor currently requires concrete executable and server paths for local plugins. The generated commands handle that adapter without changing the portable artifact:

npm run plugin:install:cursor
npm run plugin:status:cursor
npm run plugin:uninstall:cursor

Installation rebuilds first, copies the artifact beneath ~/.cursor/plugins/local, resolves the active Node executable, and reports that Cursor should be reloaded. Reinstall after source, policy, metadata, or catalog changes.

Plugin metadata

Use --plugin-name, --skill-name, --plugin-description, and --plugin-license with --agent-plugin to override the portable defaults. --experimental-mcp-skills also requires --agent-plugin because that workflow owns the packaged runtime skill.

Programmatic consumers can call scaffoldCodeModeMcp, scaffoldAgentPlugin, syncAgentPluginSkill, buildAgentPlugin, installProjectAuthoringSkills, and the Cursor lifecycle functions directly. The singular installProjectAuthoringSkill remains available for compatibility.