A local MCP server that gives Claude 8 Claude-native prompt-engineering tools — scaffold, improve, critique, eval, chain, generate examples, apply techniques, look up concepts — backed by a 55-file knowledge base curated from dair-ai/Prompt-Engineering-Guide and Anthropic's prompt engineering docs.
No API key required by default. The tools use MCP sampling to call back into the same Claude that's running your session (Claude Code or Desktop). Optional Azure OpenAI fallback for environments that don't support sampling.
┌──────────────────────┐ ┌─────────────────────┐
│ Claude Code │ stdio │ │ sampling/createMessage
│ Claude Desktop │◀────────│ prompt-mcp │◀──────────┐
└─────┬────────────────┘ │ (Node, local) │ │
│ │ │ │
│ user says "scaffold a │ 8 tools │ │
│ prompt for..." │ 55-file KB │ │
▼ └─────────────────────┘ │
tool call ─────────────────────────────────────────────────────────┘
(the tool asks the host Claude to do the LLM work — zero extra cost)
optional, only when sampling isn't available:
┌─────────────────────┐
│ prompt-mcp │──▶ Azure OpenAI gpt-5.5
└─────────────────────┘ (your key)
Most prompt-engineering tools are generic. Claude has specific levers — XML tags, <thinking> blocks, prefilling, document-first ordering, extended thinking — that a generic tool dilutes. The 8 tools in this server are tuned for those levers, and the KB is annotated with claude_notes: for every technique.
The tool calls Claude (or any model — see providers). The MCP layer sits between your editor and your prompts so you can scaffold → critique → improve → eval without leaving chat.
Honest take from someone who built the tool: most prompting should stay free-range. Reach for prompt-mcp only when you've typed the same prompt 3+ times and gotten slightly different output each time.
Default to free-range. Just type what you want to Claude.
- One-off tasks
- Exploration ("I'm not sure what I want yet")
- Quick Q&A, summaries, rewrites
- Creative writing where surprise matters
- Anything where Claude's clarifying questions are useful
Reach for prompt-mcp when 2+ of these are true:
- You'll run the task 3+ times
- Someone else needs to run it and get the same shape output
- Output is parsed or consumed by another tool (eval runner, doc generator, downstream prompt)
- Failure has real cost (investor doc, customer email, legal review, financial check)
- You want to schedule or automate it
- You've already felt the prompt drift between attempts
| Task | Templated? |
|---|---|
| "Rewrite this paragraph less corporately" | No — free-range, one shot |
| "What are the 3 biggest objections from a Series B partner?" | No — exploration |
| Weekly investor update | Yes — recurring + multi-stakeholder |
| Discovery call prep | Yes — recurring, team uses it |
| Monthly Fireflies call review | Yes — multi-step + parseable contracts |
| Customer-intro 1-pager | Yes — you'll send N of these |
| Financial-model pressure-test | Yes — high stakes + evidence rules required |
| Data-room DD audit | Yes — repeat per investor + consistency matters |
| "Brainstorm a Series B pitch narrative" | No — creative, exploratory |
| Candidate rejection email | Yes if you reject >2/week, otherwise no |
The tool's biggest risk is becoming engineering theatre. Building a perfect prompt for something you'll do once is procrastination. The value shows up in the 2nd, 5th, 20th run.
Don't template prematurely. Don't free-range the things you do every week.
| Slash invocation | Tool name | Purpose | Calls LLM? |
|---|---|---|---|
| "Scaffold a prompt that..." | scaffold_prompt |
Generate a structured Claude-native prompt from a one-line task. | yes |
| "Improve this prompt..." | improve_prompt |
Critique then rewrite an existing prompt. | yes |
| "Critique this prompt..." | critique_prompt |
Static lint + LLM checklist review. | yes |
"Apply cot / xml-tags / ..." |
apply_technique |
One of 10 deterministic transforms. | no |
| "Generate examples for..." | generate_examples |
n multishot examples (with edge + negative). | yes |
| "Build an eval for..." | build_eval |
6–20 case eval suite + rubric + YAML. | yes |
| "Design a chain for..." | design_chain |
Decompose a hard task into 2–10 prompt steps + mermaid diagram. | yes |
"Explain extended-thinking" |
explain_concept |
KB reference card lookup. | no |
LLM tools take ~5–40s per call on gpt-5.5 (reasoning model). Disk-cached on inputs, so re-runs are instant. See EXAMPLES.md for worked walk-throughs of each.
git clone https://github.com/rtalari-ruby/prompt-mcp.git
cd prompt-mcp
npm install
npm run buildThat's it for the default flow. No .env setup needed — the tools will use your running Claude session via MCP sampling. Skip to step 2.
One command:
claude mcp add --scope user prompt node $(pwd)/dist/server.jsVerify:
claude mcp list
# → prompt: node /path/to/prompt-mcp/dist/server.js - ✓ ConnectedThe tools are available in every project from now on. Restart any open Claude Code sessions to pick them up.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create it if it doesn't exist):
{
"mcpServers": {
"prompt": {
"command": "node",
"args": ["<absolute-path-to-prompt-mcp>/dist/server.js"]
}
}
}Restart Claude Desktop. The tools appear in the slash-command palette.
Requires the HTTP transport and an OAuth wrapper — see REMOTE.md. For most users, Claude Desktop is the easier path and identical experience.
After wiring, in a fresh chat:
"Explain
chain-of-thoughtfrom the prompt KB."
You should get a reference card with TL;DR, when-to-use, when-not-to-use, Claude-specific notes, pattern, and example. That hits explain_concept — KB lookup, no LLM, instant. If you see this, the connection is good.
Then try:
"Use scaffold_prompt to build a prompt that extracts the top 3 customer pain points from a support call transcript."
First run: ~25s (gpt-5.5 reasoning). Cached after.
A reusable workflow for any company brief, customer-intro doc, or investor handout:
-
In Claude Code or Desktop, ask:
"Use scaffold_prompt to build a prompt that takes attached materials (deck, website, FAQ) and produces a 1-page markdown brief with hook, problem, solution, ICP, proof points, ask, and contact. Anti-fabrication: only claim what's in the materials."
-
The tool returns a full prompt with
{{materials}},{{audience}}placeholders, XML structure, output contract, and escape hatch. -
Save the prompt as a template (we keep templates/ for this).
-
In a new chat: drag your materials in, paste the template with vars filled, send.
A worked version of this — templates/relvino-customer-intro-1pager.md — ships with the repo as a concrete example.
55 markdown files organized by category:
kb/
├── techniques/ (25 files: cot, few-shot, react, tot, rag, prompt-chaining, ...)
├── claude-specific/ (10 files: xml-tags, prefilling, extended-thinking, ...)
├── failure-modes/ (6 files: vague-instructions, missing-output-contract, ...)
├── checklists/ (2 files: prompt-review, eval-design)
├── applications/ (9 files: coding, function-calling, generating, ...)
└── risks/ (3 files: adversarial, biases, factuality)
Each file has frontmatter (id, title, category, tags, sources, when_to_use, when_not_to_use, claude_notes, related) and a Markdown body.
Re-pull sources:
npm run scrape # dair-ai + Anthropic
npx tsx scripts/enrich-kb.ts # LLM-fill any TODO frontmatter (~$0.50 one-time)Add your own technique? Drop a kb/<category>/your-technique.md with frontmatter. The loader picks it up on next server restart.
Two backends, chosen automatically at call time:
When a tool runs inside Claude Code or Claude Desktop, it calls sampling/createMessage back through the MCP transport. The host Claude does the LLM work using whichever model your session is running. The tool gets the response and renders it.
- Cost: counted against your existing Claude subscription. No separate API spend.
- Key: none required.
- Model: whatever you're running in the session (Opus / Sonnet / Haiku).
- UX note: the host may show a one-time approval per session ("the prompt server wants to ask Claude to do X — allow?"). Approve once; it remembers.
For environments without sampling support (HTTP server hit directly, scripts like enrich-kb.ts, future raw MCP clients), the server falls back to whatever's configured in .env:
LLM_PROVIDER=azure-openai
AZURE_OPENAI_ENDPOINT=https://YOUR-RESOURCE.cognitiveservices.azure.com/
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_DEPLOYMENT=gpt-5.5-3
AZURE_OPENAI_API_VERSION=2024-12-01-previewThe Azure backend uses the chat-completions REST API directly via fetch — no SDK, no provider abstraction.
- KB tools (
explain_concept,apply_technique): free, instant either way. - Single-call LLM tools: ~$0.005–$0.05 per call on
gpt-5.5. - Heavy LLM tools: up to ~$0.10.
- All disk-cached on inputs — re-runs are free.
When using sampling, your tool calls show up in your Claude usage instead. No new bill.
Replace src/llm/client.ts (~150 lines). Keep the same chat(messages, opts) signature. Wire @anthropic-ai/sdk's messages.create() underneath. Everything downstream is provider-agnostic.
| Problem | Cause / Fix |
|---|---|
/mcp doesn't show prompt |
Server failed to start. Run node dist/server.js < /dev/null manually — it should print prompt-mcp ready (8 tools, stdio) to stderr. Errors will tell you what's missing. |
| "no sampling-capable host and no AZURE_OPENAI_* in env" | Your MCP client doesn't support sampling AND you haven't set up the Azure fallback. Either upgrade Claude Code/Desktop, or add AZURE_OPENAI_* to .env. |
| Sampling permission prompt every call | Some hosts ask once per session, some ask each time. Look in your Claude Code settings for a "trust this MCP server's sampling" toggle. |
| First LLM call is slow | Expected. The host's reasoning model can take 5–40s on heavy tools. Subsequent identical calls hit the disk cache and return instantly. |
| Tool returns JSON-parse error | Rare. The model occasionally wraps JSON in prose. Just re-run — the cache misses on the next phrasing. |
| Want to clear the cache | rm -rf .cache/llm. Next runs will hit the LLM fresh. |
| KB changed but server doesn't see it | Restart Claude Code/Desktop. The KB loads once at startup. |
npm run dev # tsx, no build — fastest iteration on stdio
npm run dev:http # tsx for HTTP transport
npm run build # tsc → dist/
npm test # build + smoke
# individual smokes
npx tsx scripts/smoke/run-all.ts # MCP server lists 8 tools
npx tsx scripts/smoke/kb.ts # KB index works
npx tsx scripts/smoke/technique.ts # all 10 deterministic transforms
npx tsx scripts/smoke/llm-tools.ts # all 6 LLM tools (uses cache after first run)Project layout:
prompt-mcp/
├── src/
│ ├── server.ts # stdio entry
│ ├── http-server.ts # HTTP entry (claude.ai / remote)
│ ├── build-server.ts # shared tool registration
│ ├── tools/ # 8 tool implementations
│ ├── kb/ # loader + in-memory index
│ └── llm/ # provider client + .env loader
├── kb/ # 55 Markdown files (the knowledge base)
├── templates/ # ready-to-use prompt templates
├── scripts/
│ ├── scrape-*.ts # one-shot KB scrapers
│ ├── enrich-kb.ts # LLM fill of TODO frontmatter
│ └── smoke/ # phase smoke tests
├── README.md # this file
├── EXAMPLES.md # worked example per tool
├── REMOTE.md # HTTP transport / ngrok / claude.ai web
└── .mcp.json # Claude Code snippet template
- Never commit
.env. It's in.gitignore. The Azure key and bearer token live there. - The HTTP server refuses to start without
PROMPT_MCP_TOKEN(no anonymous public access). Generate one withopenssl rand -hex 24. - If you fork this and run a public instance, rotate the token regularly and watch your LLM quota — the token is the only thing between the internet and your API spend.
- All LLM responses are cached on disk (
.cache/llm/). These caches may contain prompts you've reviewed. They're gitignored, but be aware.
Drop-in prompts under templates/ — copy, fill the one labeled input (if any), send. You don't need the MCP server wired to use these — they're just markdown you paste into Claude Code or Desktop. See the engineering templates index for the dev set.
Low-variable — most auto-detect the repo, PR, branch, and test command. Each spawns parallel sub-agents where it helps and ends with a merge-ready verdict.
- 🐛
fix-bug.md— Reproduce with a failing test, isolate, fix, confirm the test passes and nothing else broke. - ♻️
refactor.md— Behavior-preserving cleanup. Green tests before and after, small reviewable commits, no scope creep. - ✨
implement-feature.md— Clarify acceptance criteria → plan → implement in small commits → test → self-review. - 🔍
review-pr.md— Multi-lens review (correctness / security / performance / readability / tests) in parallel, then a synthesized verdict. - 🤝
handoff-feedback.md— Take a colleague's feedback, verify prior work, fix, and emit a PR description + a Slack message back to them. - 🔁
bugbot-loop.md— Loop fetch → classify → fix → verify → push → wait until Bugbot is clean. Zero fill-ins. - 🧹
modularize-cleanup.md— Safely delete proven-dead code and modularize a sprawling area. Only deletes what's provably unused; flags the rest.
- 📞
fireflies-call-analysis.md— Audit every Fireflies meeting transcript in a date range. Classifies each as Sales / Customer / Internal / Other, scores Sales+Customer calls across 5 quality dimensions with cited evidence, produces per-call action items, then rolls up into a team-level scorecard. 5-step chain with strict JSON contracts. - 🤝
relvino-customer-intro-1pager.md— One-page customer-intro brief for an investor to forward. Anti-fabrication: only claims what's in the attached materials. - 💰
financial-model-pressure-test.md— Unbiased CFO-grade pressure-test of a financial model AND an analyst's feedback on it. Evidence-cited PASS / CONDITIONAL_PASS / FAIL verdict. - 🗄️
relvino-data-room-audit.md— Full DD audit of a data room folder. G/Y/R scorecard across 10 categories, file-cited gaps and risks, diligence-blocker list.
Add your own — they're just markdown. The pattern is: <system> role + <context> (with defaults) + <workflow> + <output_contract> + <escape_hatch>.
- Open Claude Code or Claude Desktop (for engineering templates, open it in the repo).
- Drag in any source materials (PDFs, docs, spreadsheets) if the template needs them.
- Open the template file, copy the block under "The prompt".
- Paste into Claude. Replace the one labeled input if there is one (or write "see attached files").
- Send.
For iterating on a template (tighten tone, add a section, change the rubric), say:
"Use
critique_prompton this prompt, thenimprove_prompt. Focus on<your focus>."
You'll get a diff with what changed and why.
- Knowledge base techniques: dair-ai/Prompt-Engineering-Guide (MIT). Re-organized into Claude-aware reference cards.
- Claude-specific patterns: Anthropic's prompt-engineering docs. Summarized and Claude-noted in this repo's KB.
- MCP SDK: @modelcontextprotocol/sdk.
MIT. See LICENSE.