mcpill

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

Renamed from @ruco-ai/mcpill — if you have the scoped package, run npm uninstall -g @ruco-ai/mcpill && npm install -g mcpill.

Install

npm install -g mcpill

Workflows

PILL-first (recommended for new servers)

Describe your server in plain English, let Claude generate the source files.

mcpill init                        # scaffolds PILL.md + example source files
# fill PILL.md                     # describe your server: tools, resources, prompts
# tell Claude: "Build this PILL.md" # agent generates source files + runs compile
mcpill run                         # start the server

PILL.md embeds the agent instructions — Claude knows exactly what to generate and how.

Direct edit (for devs who know the pill format)

mcpill init          # scaffolds server.md + tools/ + prompts/
# edit source files  # tools/*.md, prompts/*.md, server.md
mcpill compile       # compile source → .{name}/ pill artifact
mcpill run           # start the server

Commands

mcpill init

Scaffolds a new project in the current directory:

• PILL.md — intent-level spec; fill this and hand to Claude to generate source files
• .mcpill/pill-agent-guide.md — agent instructions read by Claude when building from PILL.md
• .mcpill/server.md — server config + resources
• .mcpill/server/prompts/greeting.md — example prompt
• .mcpill/server/hooks/example-hook.md — stub hook file (see file for format; all fields commented out by default)
• .mcpill/HELLO-MCP.md — ready-to-run example (copy into PILL.md to try it)
• .claude/commands/create-pill.md — /create-pill slash command; say /create-pill in Claude Code to start the guided pill-creation workflow
• package.json — { type: "module", dependencies: { mcpill-runtime } } — deps are installed automatically by mcpill compile and mcpill validate

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 compile --no-hooks   # skip writing PreToolUse hook to .claude/settings.json

Compile also writes a PreToolUse hook into .claude/settings.json that warns Claude to use the pill's MCP tools instead of native file tools (Read, Bash, etc.). Hook mappings are read from two sources, merged at compile time — rerun mcpill compile after any change:

• PILL.md (recommended) — add a replaces field to any ## Tool: section:

  ## Tool: read-chunks
  
  description: Read a file by token-sized chunks.
  replaces: Read
  behavior: |
    ...

• AGENT.md — a ## Tools table with a Replaces column (existing format). AGENT.md wins on name conflicts.

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 'mcpill-runtime';
runPill();

3. Merges into package.json: sets type: "module", bin, and dependencies["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.

Pill source format

server.md

## Config
name: my-server
transport: stdio

## Resources
uri: info://status
name: Status
---
The server is running.

tools/{name}.md

# tool-name

Description of what the tool does

## Parameters

- param (string): Description of the parameter

## Handler

\`\`\`js
async ({ param }) => {
  return { content: [{ type: "text", text: param }] };
}
\`\`\`

prompts/{name}.md

# prompt-name

Description of the prompt

## Args

- name (string): The name to greet

## Message

> user: Say hello to {{name}}