Skip to main content
Glama

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 doctor

Install MCP

Codex:

codex mcp add prompt-optimizer -- npx -y prompt-optimizer-mcp-engine@0.1.1

Claude Code, project scope:

claude mcp add --transport stdio --scope project prompt-optimizer -- npx -y prompt-optimizer-mcp-engine@0.1.1

For 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

optimize_prompt

Improve a request with proportional execution guidance

inspect_prompt

Analyze intent, gaps, conflicts and context without rewriting

adapt_prompt

Apply documented target-agent conventions

evaluate_prompt

Return clearly labeled heuristic quality diagnostics

compare_prompts

Compare strengths and weaknesses by dimension

compress_context

Rank, deduplicate and budget relevant context

build_agent_instruction

Assemble explicit task information into instructions

explain_optimization

Explain supplied optimization records

suggest_optimization_profile

Recommend a proportional local profile

Also available: five read-only resources and five optional task templates. Full API.

Architecture

Selective optimization flow and the shared engine

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 doctor

Verification · 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 tools
adapt_promptB
Read-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_instructionA
Read-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_promptsA
Read-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_contextA
Read-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_promptB
Read-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_optimizationA
Read-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_promptA
Read-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_promptA
Read-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_profileB
Read-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

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      7
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      62
      MIT