--- slug: "claude-prompts-mcp" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/minipuft/claude-prompts-mcp@main/README.md" repo: "https://github.com/minipuft/claude-prompts-mcp" source_file: "README.md" branch: "main" --- # Claude Prompts MCP Server
Claude Prompts MCP Server Logo [![npm version](https://img.shields.io/npm/v/claude-prompts.svg?style=for-the-badge&logo=npm&color=0066cc)](https://www.npmjs.com/package/claude-prompts) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-00ff88.svg?style=for-the-badge&logo=gnu)](https://www.gnu.org/licenses/agpl-3.0) **An MCP workflow server.** Craft reusable prompts with validation and reasoning guidance.
Orchestrate agentic workflows with a composable operator syntax.
Export as native skills. [Quick Start](#quick-start) · [What You Get](#what-you-get) · [Compose Workflows](#compose-workflows) · [Run Anywhere](#run-anywhere) · [Docs](#documentation)
Chain workflow with gate validation — prompt executes through hooks, gate catches missing field on first attempt then self-corrects Chain + gate validation in action (haiku model) — gates catch errors and guide self-correction, even on the cheapest model
### What your AI client gives you — and what this server adds | Your client already does | This server adds | | -------------------------- | ------------------------------------------------------------------------------------- | | Run a prompt | Compose prompts with validation, reasoning guidance, and formatting in one expression | | Single-shot skills | Multi-step workflows that thread context between steps | | Execute subagents | Hand off mid-chain steps to agents with full workflow context | | Client-native skill format | Author once as YAML, export to any client with `skills:export` | | Manual prompt writing | Versioned templates with hot-reload, rollback, and history | | Trust the output | Validate output between steps — self-evaluation and shell commands | --- ## Quick Start ### Claude Code (Recommended) ```bash # Add marketplace (first time only) /plugin marketplace add minipuft/minipuft-plugins # Install /plugin install claude-prompts@minipuft # Try it >>tech_evaluation_chain library:'zod' context:'API validation' ```
Development setup Load plugin from local source for development: ```bash git clone https://github.com/minipuft/claude-prompts ~/Applications/claude-prompts cd ~/Applications/claude-prompts/server && npm install && npm run build claude --plugin-dir ~/Applications/claude-prompts ``` Edit hooks/prompts → restart Claude Code. Edit TypeScript → rebuild first.
**Custom prompts**: Use `--init=~/my-prompts` to create a workspace with starter templates you own. Prompts created via `resource_manager` are saved to your active resources directory. See [Custom Resources](#custom-resources). --- ### Claude Desktop **Option A: GitHub Release** (recommended) 1. Download `claude-prompts-{version}.mcpb` from [Releases](https://github.com/minipuft/claude-prompts/releases/latest) 2. Drag into Claude Desktop Settings → MCP Servers 3. Done The `.mcpb` bundle is self-contained (~5MB) — no npm required. **Option B: NPX** (auto-updates) Add to your config file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest", "--client", "claude-code"] } } } ``` Restart Claude Desktop and test: `>>research_chain topic:'remote team policies'` ---
VS Code / Copilot [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=claude-prompts&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22claude-prompts%40latest%22%5D%7D&quality=stable) Click the badge above for one-click install, or add manually to `.vscode/mcp.json`: ```json { "servers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest"] } } } ```
Cursor [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-F14F21?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=claude-prompts&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsYXVkZS1wcm9tcHRzQGxhdGVzdCJdfQ==) Click the badge above for one-click install, or add manually to `~/.cursor/mcp.json`: ```json { "mcpServers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest", "--client=cursor"] } } } ```
OpenCode **Option A: Plugin install** (recommended — includes hooks) ```bash npm install -g opencode-prompts opencode-prompts install ``` The installer configures hooks (chain tracking, gate enforcement, state preservation), plugin registration, and MCP server. See [opencode-prompts](https://github.com/minipuft/opencode-prompts) for what hooks provide. **Option B: MCP server only** (manual config, no hooks) Add to `~/.config/opencode/opencode.json`: ```json { "mcp": { "claude-prompts": { "type": "local", "command": [ "npx", "-y", "claude-prompts@latest", "--transport=stdio", "--client=opencode" ] } } } ``` You'll have the three MCP tools but no chain tracking, gate enforcement, or state preservation across compactions. To load your own prompts, add an `environment` key — see [Custom Resources](#custom-resources).
Gemini CLI **Option A: Extension install** (recommended — includes hooks) ```bash # Enable hooks (first time only — skip if already enabled) echo '{"hooks": {"enabled": true}}' > ~/.gemini/settings.json # Install extension gemini extensions install https://github.com/minipuft/gemini-prompts ``` The extension registers the MCP server and adds hooks for `>>` syntax detection, chain tracking, and gate reminders. See [gemini-prompts](https://github.com/minipuft/gemini-prompts) for what hooks provide. **Option B: MCP server only** (manual config, no hooks) Add to `~/.gemini/settings.json`: ```json { "mcpServers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest", "--client=gemini"] } } } ``` You'll have the three MCP tools but no `>>` syntax detection, chain tracking, or gate reminders. To load your own prompts, add an `env` key — see [Custom Resources](#custom-resources).
Other Clients (Codex, Windsurf, Zed) Add to your MCP config file with a `--client` preset for deterministic handoff guidance: | Client | Config Location | Recommended `--client` | | -------- | ----------------------------------------- | ----------------------- | | Codex | `~/.codex/config.toml` | `codex` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `cursor` (experimental) | | Zed | `~/.config/zed/settings.json` → `mcp` key | `unknown` | **JSON-based configs (Windsurf/Zed):** ```json { "mcpServers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest", "--client=cursor"] } } } ``` **Codex (`~/.codex/config.toml`):** ```toml [mcp_servers.claude_prompts] command = "npx" args = ["-y", "claude-prompts@latest", "--client=codex"] ``` Supported presets: `claude-code`, `codex`, `gemini`, `opencode`, `cursor`, `unknown`. For complete per-client setup and limitations: - [Client Integration Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/client-integration.md) - [Client Capabilities Reference](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/client-capabilities.md)
From Source (developers only) ```bash git clone https://github.com/minipuft/claude-prompts.git cd claude-prompts/server npm install && npm run build && npm test ``` Point your MCP config to `server/dist/index.js`. The esbuild bundle is self-contained. **Transport options**: `--transport=stdio` (default), `--transport=streamable-http` (HTTP clients).
### Custom Resources **Use your own prompts, gates, methodologies, and styles.** Two approaches depending on whether you want the bundled resources or not: **Option A: Own workspace** (recommended for full control) Create a workspace with starter templates, then point your MCP config to it: ```bash npx -y claude-prompts@latest --init=~/my-prompts ``` This creates `~/my-prompts/resources/` with starter prompts you own. Set `MCP_WORKSPACE` or `MCP_RESOURCES_PATH` to use it. Prompts created via `resource_manager` are saved here. Your AI can update them through MCP — no manual editing needed. **Option B: Plugin install** (bundled resources + hooks) Plugin installs (Claude Code, OpenCode, Gemini) set `MCP_WORKSPACE` automatically and ship the bundled 90+ prompts, gates, and methodologies. Prompts created via `resource_manager` are saved to the plugin's resources directory. > [!IMPORTANT] > **`MCP_RESOURCES_PATH`** sets the base resources directory (replaces the package default). > **`MCP_WORKSPACE`** enables overlay — custom resources in your workspace are loaded **alongside** bundled ones. Prompts, gates, methodologies, and styles with the same ID as bundled ones take priority.
Config examples per client **Claude Desktop / VS Code / Cursor** (JSON with `env`): ```json { "mcpServers": { "claude-prompts": { "command": "npx", "args": ["-y", "claude-prompts@latest"], "env": { "MCP_RESOURCES_PATH": "/path/to/your/resources" } } } } ``` **OpenCode** (JSON with `environment`): ```json { "mcp": { "claude-prompts": { "type": "local", "command": ["npx", "-y", "claude-prompts@latest", "--transport=stdio"], "environment": { "MCP_RESOURCES_PATH": "/path/to/your/resources" } } } } ```
See [CLI Configuration](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/mcp-tools.md#cli-configuration) for all env vars including fine-grained path overrides (`MCP_PROMPTS_PATH`, `MCP_GATES_PATH`, etc.). ---
See the dashboard — system status overview
System status demo showing loaded prompts, gates, methodologies, and active configuration Loaded resources, active configuration, and server health at a glance
--- ## What You Get Four resource types you author, version, and compose into workflows.
See the catalog — listing all available prompts
Listing all available prompts across 11 categories using the resource_manager tool 90 prompts across 11 categories — all hot-reloadable and versionable
### Prompt Templates Versioned YAML with hot-reload. Edit a template, test it immediately — or ask your AI to update it through MCP. ``` >>code_review target:'src/auth/' language:'typescript' ``` ### Validation Rules (Gates) Criteria the AI checks its own output against. Blocking or advisory. ``` :: 'no false positives' :: 'cite sources with links' ``` Failed checks can retry automatically or pause for your decision. > [!TIP] > **Define your own checks.** See the [Gates Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/gates.md) for blocking vs advisory rules, retry behavior, and shell verification. ### Reasoning Guidance (Methodologies) Frameworks that shape how the AI thinks through a problem — not just what it outputs. 6 built-in, or create your own. ``` @CAGEERF # Context → Analysis → Goals → Execution → Evaluation → Refinement @ReACT # Reason → Act → Observe loops @5W1H # Who, What, Where, When, Why, How ``` > [!TIP] > **Create your own framework.** See the [Methodologies Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/methodologies.md) for built-in frameworks and custom authoring. ### Styles Response formatting and tone. ``` #analytical # Structured, evidence-based output #concise # Brief, action-focused ``` All resources are hot-reloadable, versioned with rollback history, and managed through the `resource_manager` tool. > [!TIP] > **Ready to build your own?** Start with the [Prompt Authoring Tutorial](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/tutorials/build-first-prompt.md). --- ## Compose Workflows The operator syntax wires resources together — chain steps, add validation inline, hand off steps to agents. ``` >>review target:'src/auth/' @CAGEERF :: 'no false positives' --> security_scan :: verify:"npm test" --> recommendations :: 'actionable, with code' ==> implementation ```
See the chain — phases completing back-to-back
Chain phases 3-4 executing back-to-back, compounding reasoning across steps before rendering final output Phases compound reasoning across steps — each step builds on validated output from the previous one
See the output — tech evaluation chain with context7 research
Tech evaluation chain researching Zod via context7, producing a scored assessment table with security, performance, DX, integration, and ecosystem ratings Context7 fetches live library docs mid-chain — final output is a structured assessment with sources
What happened: 1. Loaded the `review` template with arguments 2. Injected CAGEERF reasoning guidance 3. Added a validation rule (AI self-evaluates against it) 4. Chained output to the next step 5. Ran a shell command for ground-truth validation 6. Handed the final step off to a client-native subagent > [!TIP] > Chains support conditional branching, context threading, and agent handoffs. > [Chains Lifecycle](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/concepts/chains-lifecycle.md) · [MCP Tools Reference](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/mcp-tools.md) ### Verification Loops Ground-truth validation via shell commands — the AI keeps iterating until tests pass: ``` >>implement-feature :: verify:"npm test" loop:true ``` Implements, runs the test, reads failures, fixes, retries. Spawns a fresh context after repeated failures to avoid context rot. | Preset | Tries | Timeout | Use Case | | ----------- | ----- | ------- | ----------------- | | `:fast` | 1 | 30s | Quick check | | `:full` | 5 | 5 min | CI validation | | `:extended` | 10 | 10 min | Large test suites | > [!TIP] > **Autonomous test-fix cycles.** See [Ralph Loops](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/ralph-loops.md) for presets, timeout configuration, and context-rot prevention. ### Judge Mode Let the AI pick the right resources for the task: ``` %judge Help me refactor this authentication module ``` Analyzes available templates, reasoning frameworks, validation rules, and styles — applies the best combination automatically. > [!TIP] > **How judge mode selects resources.** See [Judge Mode Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/judge-mode.md) for scoring, overrides, and preview with `%judge`. --- ## Run Anywhere Author workflows as YAML templates. Export as native skills to your client. ```yaml # skills-sync.yaml — choose what to export registrations: claude-code: user: - prompt:development/review - prompt:development/validate_work ``` ```bash npm run skills:export ``` The `review` prompt becomes a `/review` Claude Code skill. `validate_work` becomes `/validate_work`. Same source, native experience — no MCP call required at runtime. Compiles to Claude Code skills, Cursor rules, OpenCode commands, and more. `npm run skills:diff` flags when exports drift from source.
See the export — dry-run compile + skill preview
Skills export dry-run compiling prompts to native skill files, then bat preview of the generated review skill with phases, gates, and arguments Dry-run compiles YAML templates into native client skills — review before writing
> [!TIP] > The [Skills Sync Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/skills-sync.md) covers configuration, supported clients, and drift detection. --- ### With Hooks Well-composed prompts carry their own structure. Hooks keep the experience consistent across models and long sessions.
What hooks do Route operator syntax to the right tool automatically. Track workflow progress across steps and long sessions. Enforce validation rules and step handoffs between agents. | Behavior | What happens | | ------------------- | ---------------------------------------------------- | | Prompt routing | `>>analyze` in conversation → correct MCP tool call | | Chain continuity | Injects step progress and continuation between steps | | Validation tracking | Tracks pass/fail verdicts across chain steps | | Agent handoffs | Routes `==>` steps to client-native subagents | | Session persistence | Preserves workflow state through context compaction | Hooks ship with the plugin install. Available for [Claude Code](https://github.com/minipuft/claude-prompts-mcp/tree/HEAD/.) (full), [OpenCode](https://github.com/minipuft/opencode-prompts) (full), [Gemini CLI](https://github.com/minipuft/gemini-prompts) (partial). Other clients: MCP tools only. → [hooks/README.md](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/hooks/README.md)
---
Syntax Reference | Symbol | Name | What It Does | Example | | :----: | :-------- | :------------------------ | :--------------------- | | `>>` | Prompt | Execute template | `>>code_review` | | `-->` | Chain | Pipe to next step | `step1 --> step2` | | `==>` | Handoff | Route step to agent | `step1 ==> agent_step` | | `*` | Repeat | Run prompt N times | `>>brainstorm * 5` | | `@` | Framework | Inject reasoning guidance | `@CAGEERF` | | `::` | Gate | Add validation criteria | `:: 'cite sources'` | | `%` | Modifier | Toggle behavior | `%clean`, `%judge` | | `#` | Style | Apply formatting | `#analytical` | **Modifiers:** - `%clean` — No framework/gate injection - `%lean` — Gates only, skip framework - `%guided` — Force framework injection - `%judge` — AI selects best resources → [MCP Tools Reference](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/mcp-tools.md) for full command documentation.
The Three Tools | Tool | Purpose | | ------------------ | ---------------------------------------------- | | `prompt_engine` | Execute prompts with frameworks and validation | | `resource_manager` | Create, update, version, and export resources | | `system_control` | Status, analytics, framework switching | ``` prompt_engine(command:"@CAGEERF >>analysis topic:'AI safety'") resource_manager(resource_type:"prompt", action:"list") system_control(action:"status") ```
--- ## How It Works ```mermaid %%{init: {'theme': 'neutral', 'themeVariables': {'background':'#0b1224','primaryColor':'#e2e8f0','primaryBorderColor':'#1f2937','primaryTextColor':'#0f172a','lineColor':'#94a3b8','fontFamily':'"DM Sans","Segoe UI",sans-serif','fontSize':'14px','edgeLabelBackground':'#0b1224'}}}%% flowchart TB classDef actor fill:#0f172a,stroke:#cbd5e1,stroke-width:1.5px,color:#f8fafc; classDef server fill:#111827,stroke:#fbbf24,stroke-width:1.8px,color:#f8fafc; classDef process fill:#e2e8f0,stroke:#1f2937,stroke-width:1.6px,color:#0f172a; classDef client fill:#f4d0ff,stroke:#a855f7,stroke-width:1.6px,color:#2e1065; classDef clientbg fill:#1a0a24,stroke:#a855f7,stroke-width:1.8px,color:#f8fafc; classDef decision fill:#fef3c7,stroke:#f59e0b,stroke-width:1.6px,color:#78350f; linkStyle default stroke:#94a3b8,stroke-width:2px User["1. User sends command"]:::actor Example[">>analyze @CAGEERF :: 'cite sources'"]:::actor User --> Example --> Parse subgraph Server["MCP Server"] direction TB Parse["2. Parse operators"]:::process Inject["3. Inject framework + gates"]:::process Render["4. Render prompt"]:::process Decide{"6. Route verdict"}:::decision Parse --> Inject --> Render end Server:::server subgraph Client["Claude (Client)"] direction TB Execute["5. Run prompt + check gates"]:::client end Client:::clientbg Render -->|"Prompt with gate criteria"| Execute Execute -->|"Verdict + output"| Decide Decide -->|"PASS → render next step"| Render Decide -->|"FAIL → render retry prompt"| Render Decide -->|"Done"| Result["7. Return to user"]:::actor ``` Command with operators → server parses and injects resources → client executes and self-evaluates → route: next step (pass), retry (fail), or return result (done). --- ## Documentation | I want to... | Go here | | -------------------------------------------------------- | ---------------------------------------------------------------------- | | Build my first prompt | [Prompt Authoring Tutorial](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/tutorials/build-first-prompt.md) | | Chain multi-step workflows | [Chains Lifecycle](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/concepts/chains-lifecycle.md) | | Add validation to workflows | [Gates Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/gates.md) | | Use or create reasoning frameworks | [Methodologies Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/methodologies.md) | | Use autonomous verification loops | [Ralph Loops](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/ralph-loops.md) | | Configure per-client MCP installs and `--client` presets | [Client Integration Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/client-integration.md) | | Compare client profile mapping and limitations | [Client Capabilities Reference](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/client-capabilities.md) | | Export skills to other clients | [Skills Sync](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/skills-sync.md) | | Configure the server | [CLI & Configuration](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/cli.md) | | Let the AI pick resources automatically | [Judge Mode Guide](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/judge-mode.md) | | Look up MCP tool parameters | [MCP Tools Reference](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/mcp-tools.md) | | Look up prompt YAML fields | [Prompt YAML Schema](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/reference/prompt-yaml-schema.md) | | Understand the architecture | [Architecture Overview](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/architecture/overview.md) | | Fix common issues | [Troubleshooting](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/docs/guides/troubleshooting.md) | --- ## Contributing ```bash cd server npm install npm run build # esbuild bundles to dist/index.js npm test # Run test suite npm run validate:all # Full CI validation ``` The build produces a self-contained bundle. `server/dist/` is gitignored — CI builds fresh from source. See [CONTRIBUTING.md](https://github.com/minipuft/claude-prompts-mcp/blob/HEAD/CONTRIBUTING.md) for workflow details. --- ## License [AGPL-3.0](https://github.com/minipuft/claude-prompts-mcp/tree/HEAD/LICENSE)