mcpill

CLI for building, validating, and publishing MCP servers using the pill format.

Install

npm install -g mcpill

Author workflow

mcpill init       # scaffold server.md + tools/ + prompts/
# write your tools, prompts, resources
mcpill compile    # compile server.md → .<name>/ pill artifact
mcpill validate   # validate the pill artifact
mcpill run        # start the MCP server locally (dev)
mcpill pack       # prepare bin/server.js + package.json for npm
mcpill publish    # pack + npm publish

Commands

mcpill init

Scaffolds a new project in the current directory:

• server.md — Config + Resources in human-readable Markdown
• tools/echo.md — example tool
• prompts/greeting.md — example prompt
• .mcpill/ — pre-compiled pill artifact
• package.json — with pack and publish scripts ready

mcpill compile

Compiles server.md + tools/*.md + prompts/*.md into a .<name>/ pill artifact.

mcpill compile              # forward: source → pill
mcpill compile --to-md      # reverse: pill → source
mcpill compile --strict     # error on missing tool handlers (default: stub)

mcpill validate

Validates all pill directories (.<name>/) in the project root.

mcpill run

Starts the MCP server from the pill artifact.

mcpill run                        # stdio (default)
mcpill run --transport http --port 3333

mcpill pack

Prepares the pill for npm distribution:

1. Validates the pill artifact
2. Writes bin/server.js:

import { runPill } from '@ruco-ai/mcpill-runtime';
runPill();

3. Merges into package.json: sets type: "module", bin, and dependencies["@ruco-ai/mcpill-runtime"]. Does not overwrite existing name or version.

mcpill publish

Runs mcpill pack then publishes to npm.

mcpill publish                    # npm publish --access public
mcpill publish --access restricted

Options

All commands accept --dir <path> to target a directory other than the current working directory.