@czap/mcp-server

An MCP (Model Context Protocol) server that exposes the czap command catalog as tools, resources, and prompts over stdio or HTTP, so AI agents can run the same commands the czap CLI does.

You usually don't install this directly — it arrives as a dependency of liteship, and the czap mcp verb launches it. Install liteship (or this package alongside @czap/cli) instead, unless you're embedding the server in your own process via start().

Install

pnpm add @czap/cli @czap/mcp-server   # `czap mcp` dynamically loads this package

effect (>= 4.0.0-beta.32) is a required peer dependency: pnpm add effect@beta. @czap/cli is not a peer — this package never imports the CLI.

30 seconds

import { start } from '@czap/mcp-server';

await start(); // stdio transport (default)
// await start({ http: ':3838' }); // HTTP transport instead

The process stays alive serving MCP JSON-RPC on stdin/stdout. For Claude Desktop-style MCP hosts, skip the code and point the host at the launcher:

{ "mcpServers": { "czap": { "command": "czap", "args": ["mcp"] } } }

After the host connects, its tools/list call returns the czap command catalog.

Tools

tools/list is authoritative, but so you know what's there before you connect — the MCP-exposed subset (explicit opt-in via mcpExposed; blocking/interactive verbs like gauntlet and ship are deliberately CLI-only):

| Tool | What it does | |---|---| | capsule.list | List the capsules in the factory registry | | capsule.inspect | Inspect one capsule — its arm, contract, and receipt | | capsule.verify | Verify a capsule is fresh (regeneration-diff check) | | scene.compile | Compile a scene contract to a CompiledScene | | scene.render | Render a compiled scene to frames | | scene.verify | Verify a scene contract resolves | | asset.analyze | Run analysis projections on an asset (beats / onsets / waveform) | | asset.verify | Verify an asset declaration decodes |

Each tool runs the same handler as the matching czap <verb> (one registry, two skins — @czap/command), so a tool call and a terminal verb are byte-identical. Input/output schemas are in the API reference.

Where it sits

This is a protocol adapter over @czap/command — the shared command registry the CLI also projects, so a tool call and a terminal verb run the identical handler. @czap/core supplies the command and receipt types, and @czap/compiler backs the MCP-app manifest resource. It deliberately has no bin and never imports @czap/cli; the two are sibling skins, connected only by the CLI's dynamic import in czap mcp. See the package surfaces map for the full layout.

If it does nothing

A stdio MCP server prints nothing at startup — silence is normal, not a hang. It answers JSON-RPC requests on stdin; if your MCP host shows no tools, check that both @czap/cli and @czap/mcp-server are installed in the same project and on the same version, since czap mcp resolves this package from where the CLI runs.

Docs

• Getting started
• Capsule factory — the dispatch model behind the tools
• Glossary — the vocabulary used above
• API reference — generated from source

Part of LiteShip — powered by the CZAP engine (Content-Zoned Adaptive Projection), distributed as @czap/* packages.