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 — registered while running, removed on exit

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 (transient — stops when you do)

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
• README.md — quickstart guide covering project layout and tool-editing 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 all hooks to .claude/settings.json

Compile also writes two auto-generated hooks into .claude/settings.json:

• PreToolUse — warns Claude to use the pill's MCP tools instead of native file tools (Read, Bash, etc.) when the pill declares a replaces field.

• UserPromptSubmit — on every user message, injects context instructing Claude to call the pill's first declared tool before responding. Present whenever the pill has at least one tool; no-op until ~/.<pill-name>/state.json sets enabled: true (written by <pill-name> install). 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.

Blocking hooks

For mandatory workflow steps, add a ## Hook: section to PILL.md with blocking: true. Compile generates a hard-enforcement gate instead of a soft reminder:

## Hook: my-hook

trigger: PreToolUse
blocking: true
required_tool: analyze-english
gate_window_seconds: 120
instructions: |
  Before calling any other tool, call mcp__my-pill__analyze-english first.

At runtime the gate script exits 1 (blocking the tool call) until mcp__{pill}__analyze-english has run within the window. After it runs, the flag script records the timestamp and the gate passes for gate_window_seconds seconds (default 120). Pill's own MCP tools are always allowed through. The gate is fail-open — if the pill's state file is missing, the gate passes.

required_tool must name a tool defined in the same pill; mcpill compile aborts with an error if it doesn't.

Non-blocking hooks and distribution

## Hook: entries without blocking: true but with a command field emit soft hooks (context injectors) to .claude/settings.json. They are also bundled into the standalone distribution: when an end user runs <pill> install --agent claude-code, these hooks are wired into their config automatically. Codex installs print a warning when the pill defines hooks that Codex cannot run.

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) — registered while running, removed on exit
mcpill run --transport http --port 3333

For stdio transport, the server entry is automatically written to Claude's config on start and removed on exit (SIGINT, SIGTERM, or normal process exit). HTTP transport is self-hosted — Claude connects to a URL, so no registration occurs.

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}}