Content
# Claude Prompts MCP Server
<div align="center">
<img src="assets/logo.png" alt="Claude Prompts MCP Server Logo" width="200" />
[](https://www.npmjs.com/package/claude-prompts)
[](https://www.gnu.org/licenses/agpl-3.0)
**An MCP workflow server.**
Craft reusable prompts with validation and reasoning guidance.<br>
Orchestrate agentic workflows with a composable operator syntax.<br>
Export as native skills.
[Quick Start](#quick-start) · [What You Get](#what-you-get) · [Compose Workflows](#compose-workflows) · [Run Anywhere](#run-anywhere) · [Docs](#documentation)
</div>
<div align="center">
<img src="assets/demos/hero-demo.gif" alt="Chain workflow with gate validation — prompt executes through hooks, gate catches missing field on first attempt then self-corrects" width="720" />
<sub>Chain + gate validation in action (haiku model) — gates catch errors and guide self-correction, even on the cheapest model</sub>
</div>
### 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'
```
<details>
<summary>Development setup</summary>
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.
</details>
**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'`
---
<details>
<summary><strong>VS Code / Copilot</strong></summary>
[](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"]
}
}
}
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
[](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"]
}
}
}
```
</details>
<details>
<summary><strong>OpenCode</strong></summary>
**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).
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
**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).
</details>
<details>
<summary><strong>Other Clients</strong> (Codex, Windsurf, Zed)</summary>
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](docs/guides/client-integration.md)
- [Client Capabilities Reference](docs/reference/client-capabilities.md)
</details>
<details>
<summary><strong>From Source</strong> (developers only)</summary>
```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).
</details>
### 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.
<details>
<summary><strong>Config examples per client</strong></summary>
**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"
}
}
}
}
```
</details>
See [CLI Configuration](docs/reference/mcp-tools.md#cli-configuration) for all env vars including fine-grained path overrides (`MCP_PROMPTS_PATH`, `MCP_GATES_PATH`, etc.).
---
<details>
<summary><strong>See the dashboard</strong> — system status overview</summary>
<br>
<img src="assets/demos/status-demo-3x.gif" alt="System status demo showing loaded prompts, gates, methodologies, and active configuration" width="720" />
<sub>Loaded resources, active configuration, and server health at a glance</sub>
</details>
---
## What You Get
Four resource types you author, version, and compose into workflows.
<details>
<summary><strong>See the catalog</strong> — listing all available prompts</summary>
<br>
<img src="assets/demos/resource-list-demo.gif" alt="Listing all available prompts across 11 categories using the resource_manager tool" width="720" />
<sub>90 prompts across 11 categories — all hot-reloadable and versionable</sub>
</details>
### 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](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](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](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
```
<details>
<summary><strong>See the chain</strong> — phases completing back-to-back</summary>
<br>
<img src="assets/demos/hero-chain-demo.gif" alt="Chain phases 3-4 executing back-to-back, compounding reasoning across steps before rendering final output" width="720" />
<sub>Phases compound reasoning across steps — each step builds on validated output from the previous one</sub>
</details>
<details>
<summary><strong>See the output</strong> — tech evaluation chain with context7 research</summary>
<br>
<img src="assets/demos/chain-workflow-demo.gif" alt="Tech evaluation chain researching Zod via context7, producing a scored assessment table with security, performance, DX, integration, and ecosystem ratings" width="720" />
<sub>Context7 fetches live library docs mid-chain — final output is a structured assessment with sources</sub>
</details>
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](docs/concepts/chains-lifecycle.md) · [MCP Tools Reference](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](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](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.
<details>
<summary><strong>See the export</strong> — dry-run compile + skill preview</summary>
<br>
<img src="assets/demos/skills-export-demo.gif" alt="Skills export dry-run compiling prompts to native skill files, then bat preview of the generated review skill with phases, gates, and arguments" width="720" />
<sub>Dry-run compiles YAML templates into native client skills — review before writing</sub>
</details>
> [!TIP]
> The [Skills Sync Guide](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.
<details>
<summary>What hooks do</summary>
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](.) (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](hooks/README.md)
</details>
---
<details>
<summary><strong>Syntax Reference</strong></summary>
| 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](docs/reference/mcp-tools.md) for full command documentation.
</details>
<details>
<summary><strong>The Three Tools</strong></summary>
| 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")
```
</details>
---
## 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](docs/tutorials/build-first-prompt.md) |
| Chain multi-step workflows | [Chains Lifecycle](docs/concepts/chains-lifecycle.md) |
| Add validation to workflows | [Gates Guide](docs/guides/gates.md) |
| Use or create reasoning frameworks | [Methodologies Guide](docs/guides/methodologies.md) |
| Use autonomous verification loops | [Ralph Loops](docs/guides/ralph-loops.md) |
| Configure per-client MCP installs and `--client` presets | [Client Integration Guide](docs/guides/client-integration.md) |
| Compare client profile mapping and limitations | [Client Capabilities Reference](docs/reference/client-capabilities.md) |
| Export skills to other clients | [Skills Sync](docs/guides/skills-sync.md) |
| Configure the server | [CLI & Configuration](docs/guides/cli.md) |
| Let the AI pick resources automatically | [Judge Mode Guide](docs/guides/judge-mode.md) |
| Look up MCP tool parameters | [MCP Tools Reference](docs/reference/mcp-tools.md) |
| Look up prompt YAML fields | [Prompt YAML Schema](docs/reference/prompt-yaml-schema.md) |
| Understand the architecture | [Architecture Overview](docs/architecture/overview.md) |
| Fix common issues | [Troubleshooting](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](CONTRIBUTING.md) for workflow details.
---
## License
[AGPL-3.0](LICENSE)
