Prompt Optimizer MCP
Prompt Optimizer MCP is a local-first MCP server for improving, inspecting, adapting, evaluating, comparing, and assembling AI agent prompts and context without requiring an API key.
Optimize vague or substantial prompts into bounded execution contracts while preserving intent.
Inspect prompts for intent, ambiguities, missing requirements, conflicts, and context issues without rewriting.
Adapt already-good prompts to specific target agent conventions like Codex, Claude Code, Cursor, and OpenCode.
Evaluate prompt quality using transparent heuristic diagnostics across clarity, specificity, goal preservation, and more.
Compare two prompts by heuristic dimensions and task context without declaring an arbitrary winner.
Rank, deduplicate, and budget supplied context while retaining critical items.
Build an execution instruction from an explicit goal, requirements, and constraints.
Explain caller-supplied optimization results and their pass decisions for auditing.
Suggest a proportional local optimization profile: minimal, balanced, or thorough.
Run locally by default with no network or API key; non-local modes may send redacted data to a configured provider.
Operate read-only and non-destructive with no server-side history retention.
Supports optional OpenAI-compatible provider APIs for remote model calls or a separate evaluator during prompt optimization, requiring trusted server configuration and explicit selection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Prompt Optimizer MCP improve this instruction, then execute it: fix auth"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Install an MCP server + portable Agent Skill. Your existing agent gains the ability to turn vague, complex or context-heavy requests into focused instructions, then execute them. No API key required.
Quick start · Install guides · Examples · API · Troubleshooting
Why Prompt Optimizer?
Small gaps in a request can become large implementation assumptions. Prompt Optimizer helps the agent clarify relevant requirements, preserve constraints and verify its work without turning every task into a lengthy specification.
Local-first and deterministic: useful optimization without network access or an external model.
Selective and proportional: complex tasks get structure; trivial requests stay out of the optimizer.
Repository-aware and scope-aware: reuse project conventions, avoid unnecessary abstractions and preserve the requested features.
Portable and inspectable: MCP, an instruction-only Agent Skill and a TypeScript SDK share one engine. Context ranking, compression and pass explanations are built in.
Related MCP server: universal-jev-mcp
How it works
Prompt Optimizer improves instructions. Your AI agent executes the work.
The skill decides whether optimization would help, reads only necessary repository context, calls optimize_prompt, then uses the validated result as an execution contract. The host implements and verifies that contract while respecting higher-priority instructions and explicit user requirements.
Supported AI agents
Host | MCP | Agent Skill | Evidence |
OpenAI Codex | Yes | Yes | Integration supported; MCP protocol tested |
Claude Code | Yes | Yes | Integration supported; MCP protocol tested |
Google Antigravity | Yes | Yes | CLI live tested, user-reported v0.1.x; IDE untested |
Cursor | Yes | Yes | Integration supported; MCP protocol tested |
OpenCode | Yes | Yes | Integration supported; MCP protocol tested |
Generic MCP hosts | Yes | If supported by host | Protocol tested; portable skill available |
Protocol tests use the official MCP client; they do not substitute for live testing each host. Agent names identify integrations and imply no endorsement. See the compatibility matrix and evidence.
Quick start
With Node.js 22+, check the package and local server health:
npx -y prompt-optimizer-mcp-engine@0.1.1 --version
npx -y prompt-optimizer-mcp-engine@0.1.1 doctorInstall MCP
Codex:
codex mcp add prompt-optimizer -- npx -y prompt-optimizer-mcp-engine@0.1.1Claude Code, project scope:
claude mcp add --transport stdio --scope project prompt-optimizer -- npx -y prompt-optimizer-mcp-engine@0.1.1For Antigravity, Cursor, OpenCode and other clients, use the host guides. Stdio and Streamable HTTP are supported.
Install Agent Skill
The skill teaches the host when and how to optimize. Install the package globally to access its portable installer; from your target project, in a POSIX shell:
npm install --global prompt-optimizer-mcp-engine@0.1.1
PROMPTOPT_ROOT="$(npm root -g)/prompt-optimizer-mcp-engine"
node "$PROMPTOPT_ROOT/scripts/install-skill.mjs" --agent codex --scope project --project "$PWD"Replace codex with claude-code, antigravity, cursor, opencode or generic as appropriate. Antigravity CLI global installs use --agent antigravity-cli --scope user. The installer refuses to overwrite an existing skill: review and refresh a previous copy when upgrading. Updating npm alone does not update a copied skill.
Restart the host. For a quick discovery test, ask: “Use Prompt Optimizer's inspect_prompt tool to analyze ‘fix auth’ without executing it.” For explicit optimization: “Use the prompt-optimizer skill to optimize this task, then execute it: …”
Install guides
Codex · Claude Code · Google Antigravity · Cursor · OpenCode · Generic MCP / VS Code / Gemini · Local build · Portable Agent Skill
Example: request → contract → execution
Before, from the Antigravity CLI field test:
Buat dashboard admin untuk platform AI yang menampilkan penggunaan token,
status model, biaya, dan riwayat request.
Gunakan Next.js dan sesuaikan dengan project yang sudah ada.In the user's v0.1.1 fresh-session replay, the skill recognized this multi-feature, repository-aware task and invoked optimize_prompt before implementation.
Optimized guidance, abbreviated and representative rather than a verbatim trace:
Build the requested Next.js admin dashboard within the existing project. Cover token usage, model status, costs and request history. Reuse existing components and conventions. Keep changes focused; include responsive behavior, accessibility and relevant interaction states. Run the appropriate checks and report the result.
Execution: the same host agent implements that scope. It should not invent a prompt studio, model registry, webhook system or other major features. Necessary repository-specific details may be added to carry out the task.
Selective optimization
Request | Expected skill decision |
“Buat dashboard AI modern pakai Next.js.” | Optimize before implementation |
“Fix authentication ini dan rapikan arsitekturnya.” | Optimize and surface scope/constraints |
“Ubah warna tombol utama jadi merah.” | Skip; make the direct edit |
“Apa arti dependency?” / “jalankan npm run build” | Skip; answer or execute directly |
“Optimize this prompt…” | Optimize explicitly |
A successful result stays the execution contract, not a starting point for a broader specification. Normally use one primary optimization pass; do not recursively optimize its output or run all nine tools on every task. Automatic discovery remains host-controlled. Activation troubleshooting.
Tools
MCP tool | Purpose |
| Improve a request with proportional execution guidance |
| Analyze intent, gaps, conflicts and context without rewriting |
| Apply documented target-agent conventions |
| Return clearly labeled heuristic quality diagnostics |
| Compare strengths and weaknesses by dimension |
| Rank, deduplicate and budget relevant context |
| Assemble explicit task information into instructions |
| Explain supplied optimization records |
| Recommend a proportional local profile |
Also available: five read-only resources and five optional task templates. Full API.
Architecture
The independent TypeScript core powers the MCP server and SDK. The portable skill contains workflow guidance, not a duplicate optimization engine. Tools work without skills; skills offer a lightweight fallback without MCP.
import { PromptOptimizer } from 'prompt-optimizer-mcp-engine';
const result = await new PromptOptimizer().optimize({
prompt: 'buat dashboard ai keren pake nextjs',
targetAgent: 'codex',
profile: 'balanced',
mode: 'local',
});
console.log(result.optimizedPrompt);Architecture · Optional OpenAI-compatible, Anthropic and Gemini providers
Security and privacy
Local mode makes no remote model requests and needs no API key. No telemetry is collected. Remote AI requires explicit configuration and mode selection. Context is untrusted data; optimizer advice cannot override higher-priority instructions or host approvals.
Secret redaction is defense-in-depth, not a guarantee. Classification, conflict checks, token estimates and quality diagnostics are heuristic. They do not prove semantic fidelity or safe execution. Security model · Report a vulnerability
Development
pnpm install --frozen-lockfile
pnpm build
pnpm check
pnpm examples
pnpm run doctorVerification · Release process · Reference projects and licenses
Roadmap
Broaden live host coverage, benchmark multilingual intent preservation and improve context provenance. New capabilities must preserve selective activation and bounded scope.
Contributing
Bug reports, reproducible host traces and focused contributions are welcome. See CONTRIBUTING.md and the code of conduct.
License
MIT. Built for the open agent ecosystem.
Available Tools
9 toolsadapt_promptBRead-onlyIdempotent
Add documented host guidance to an already good instruction. Use when changing agent environments; not for expanding task scope.
Inputs: prompt (required), targetAgent (required), audience. Returns: ir, changes, context, metadata, +8 more
build_agent_instructionARead-onlyIdempotent
Assemble an execution instruction from an explicit goal, requirements, and constraints. Use for multi-part tasks; does not execute them.
Inputs: goal (required), context, constraints, targetAgent, +1 more. Returns: ir, changes, context, metadata, +8 more
compare_promptsARead-onlyIdempotent
Compare two instructions by heuristic dimensions and task context. Use to inspect trade-offs; does not declare an arbitrary winner.
Inputs: promptA (required), promptB (required), taskContext. Returns: kind, promptA, promptB, conclusion, +2 more
compress_contextARead-onlyIdempotent
Rank, deduplicate, and budget supplied context while retaining critical items. Use for noisy context; do not expect semantic summarization or instruction promotion.
Inputs: context (required), query, maxTokens. Returns: items, droppedIds, diagnostics, afterEstimated, +3 more
evaluate_promptBRead-onlyIdempotent
Explain instruction quality using transparent heuristic diagnostics. Use for review, not as a scientific benchmark or proof of correctness.
Inputs: prompt (required), originalPrompt. Returns: kind, metrics, limitations, estimatedTokens
explain_optimizationARead-onlyIdempotent
Explain a supplied optimization result and its pass decisions. Use for audit; the server stores no history and does not authenticate caller-supplied results.
Inputs: result (required). Returns: applied, skipped, summary, provenance, +1 more
inspect_promptARead-onlyIdempotent
Inspect intent, ambiguity, conflicts, and context without rewriting. Use to diagnose instructions; skip simple factual questions.
Inputs: prompt (required), context. Returns: ir, intent, conflicts, ambiguities, +3 more
optimize_promptARead-only
Improve a vague or substantial task before execution. Preserves the request and adds bounded guidance. Skip trivial or exact-wording requests. Local by default; non-local mode may send redacted data to a configured provider.
Inputs: prompt (required), mode, context, explain, +6 more. Returns: ir, changes, context, metadata, +8 more
suggest_optimization_profileBRead-onlyIdempotent
Choose a proportional local optimization profile for a task. Use when complexity is unclear; does not select a paid model.
Inputs: prompt (required). Returns: mode, reason, profile
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct purposes, and the descriptions actively draw boundaries (inspect vs evaluate vs optimize, skip trivial requests, not for scope expansion). However, the trio inspect_prompt/evaluate_prompt/optimize_prompt shares enough surface area that an agent could still hesitate over which applies to a borderline prompt.
Every tool follows a clean verb_noun snake_case pattern (inspect_prompt, optimize_prompt, compress_context, build_agent_instruction). The only deviation is the plural noun in compare_prompts, which is trivial and natural.
Nine tools is well within the ideal range and each maps to a distinct capability in the prompt-engineering lifecycle. No filler or redundant tools are apparent.
The surface covers diagnosis, optimization, adaptation, evaluation, comparison, context compression, instruction building, and audit explanation — a broad, coherent set. Minor gaps exist, such as no persistence/history or explicit application/validation step, but the server states these are intentional.
Maintenance
Related MCP Connectors
Turn PRDs and product ideas into structured specs so coding agents build your intent, not theirs.
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Turns vague automation requests into tool stacks, prompts, QA checks, and human boundaries.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables local-first model routing and persistent tool library management, allowing automated workflow detection and conversion of stable patterns into reusable tools.40Mozilla Public 2.0
- AlicenseAqualityBmaintenanceEnables coding agents to compact conversation contexts verbatim, make fast decisions through choice, boolean, and rubric scoring, and enforce command safety guardrails.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables personal AI agents to perceive ambient context, retain episodic memory with decay, act proactively, and route routine decisions through fast System-1 reflexes while escalating ambiguous multi-hop plans to frontier LLMs. Includes reversible execution checkpoints, token budgets, and local-first memory retention, and plugs into MCP clients like Claude Desktop, Cursor, and Windsurf.7MIT
- AlicenseCqualityBmaintenanceEnables ordinary LLMs to be augmented fully offline — with no API keys or external services — through model-aware guardrails, exemplar retrieval, structured self-critique, compliance scoring, and an allowlisted verification runner. Also provides hybrid knowledge-base search, decaying long-term memory, and persistent plan/task management across 54 MCP tools usable from any MCP client such as OpenCode, Claude Desktop, Cursor, or VS Code.62MIT