# Claude Orator Mcp

> 🪶 An MCP server for prompt optimization in Claude Code

- **Type:** MCP server
- **Install:** `agentstack add mcp-vvkmnn-claude-orator-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Vvkmnn](https://agentstack.voostack.com/s/vvkmnn)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** https://github.com/Vvkmnn/claude-orator-mcp

## Install

```sh
agentstack add mcp-vvkmnn-claude-orator-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# claude-orator-mcp

An [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for deterministic prompt optimization in [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Score prompts across 7 quality dimensions, auto-select from 11 [Anthropic techniques](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview), and return a structural scaffold. No LLM calls, no network, sub-millisecond.

[](https://www.npmjs.com/package/claude-orator-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-orator-mcp)

---

## install

**Requirements:**

[](https://claude.ai/code)

**From shell:**

```bash
claude mcp add claude-orator-mcp -- npx claude-orator-mcp
```

**From inside Claude** (restart required):

```
Add this to our global mcp config: npx claude-orator-mcp

Install this mcp: https://github.com/Vvkmnn/claude-orator-mcp
```

**From any manually configurable `mcp.json`**: (Cursor, Windsurf, etc.)

```json
{
  "mcpServers": {
    "claude-orator-mcp": {
      "command": "npx",
      "args": ["claude-orator-mcp"],
      "env": {}
    }
  }
}
```

There is **no `npm install` required** -- no external dependencies or databases, only deterministic heuristics.

However, if `npx` resolves the wrong package, you can force resolution with:

```bash
npm install -g claude-orator-mcp
```

## [skill](.claude/skills/claude-orator)

Optionally, install the skill to teach Claude when to proactively optimize prompts:

```bash
npx skills add Vvkmnn/claude-orator-mcp --skill claude-orator --global
# Optional: add --yes to skip interactive prompt and install to all agents
```

This makes Claude automatically optimize prompts before dispatching subagents, writing system prompts, or crafting any prompt worth improving. The MCP works without the skill, but the skill improves discoverability.

## [plugin](https://github.com/Vvkmnn/claude-emporium)

For automatic prompt optimization with hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace:

```bash
/plugin marketplace add Vvkmnn/claude-emporium
/plugin install claude-orator@claude-emporium
```

The **claude-orator** plugin provides:

**Hooks** (fires before subagent dispatch):

- Before Task -- Suggest prompt optimization before launching agents

**Commands:** `/reprompt-orator`

Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs.

## features

[MCP server](https://modelcontextprotocol.io/) with a single tool. Prompt in, optimized prompt out.

#### `orator_optimize`

Analyze a prompt across 7 quality dimensions, auto-select from 11 Anthropic techniques, and return a structurally optimized scaffold with before/after scores.

```
orator_optimize prompt="Write a function that sorts users"
  > Returns optimized scaffold with XML tags, output format, examples section

orator_optimize prompt="You are a helpful assistant" intent="system"
  > Returns role-assigned system prompt with structure and constraints

orator_optimize prompt="Extract all emails from this text" techniques=["xml-tags", "few-shot"]
  > Force-applies specific techniques regardless of auto-selection
```

**Score meter** (gradient fill bar):

```
🪶 3.2 ░░░▓▓▓▓▓▓▓▓ 7.8
   +xml-tags +few-shot +structured-output · 3 issues
   Wrapped in XML tags, added examples, specified output format
```

Three-zone bar: `░░░` (baseline) `▓▓▓▓▓` (improvement) `░░` (headroom to 10).

**Minimal case** (already well-structured):

```
🪶 ━━ already well-structured (8.4)
```

**Input:**

| Parameter    | Type     | Required | Description                                                                            |
| ------------ | -------- | -------- | -------------------------------------------------------------------------------------- |
| `prompt`     | string   | Yes      | The raw prompt to optimize                                                             |
| `intent`     | enum     | No       | `code \| analysis \| creative \| extraction \| conversation \| system` (auto-detected) |
| `target`     | enum     | No       | `claude-code \| claude-api \| claude-desktop \| generic` (default: `claude-code`)      |
| `techniques` | string[] | No       | Force-apply specific technique IDs                                                     |

**Output:**

| Field                | Type     | Description                                |
| -------------------- | -------- | ------------------------------------------ |
| `optimized_prompt`   | string   | Rewritten prompt scaffold (primary output) |
| `score_before`       | number   | Quality score of original (0-10)           |
| `score_after`        | number   | Quality score after optimization (0-10)    |
| `summary`            | string   | 1-line explanation of improvements         |
| `detected_intent`    | string   | Auto-detected intent category              |
| `applied_techniques` | string[] | Technique IDs applied                      |
| `issues`             | string[] | Detected problems                          |
| `suggestions`        | string[] | Actionable fixes                           |

The `optimized_prompt` is a structural scaffold. Claude refines it with domain knowledge, codebase context, and conversation history.

## methodology

How [claude-orator-mcp](https://github.com/Vvkmnn/claude-orator-mcp) [works](https://github.com/Vvkmnn/claude-orator-mcp/tree/main/src):

```
                🪶 claude-orator-mcp
                ════════════════════

                   orator_optimize
                   ──────────────

                      PROMPT
                        │
           ┌────────────┴────────────┐
           ▼                         ▼
     ┌───────────┐            ┌────────────┐
     │  Detect   │            │  Measure   │
     │  Intent   │            │ Complexity │
     └─────┬─────┘            └──────┬─────┘
           │                         │
     system > code >           word count +
     extraction >              clause depth
     analysis >                      │
     creative >                      │
     conversation                    │
     + disambiguation                │
     + fallback heuristics           │
           │                         │
           └────────────┬────────────┘
                        │
                        ▼
              ┌───────────────────┐
              │   Score Before    │
              │                   │
              │  clarity      20% │  strong verbs, single task
              │  specificity  20% │  named tech, constraints
              │  structure    15% │  XML tags, headers, lists
              │  examples     15% │  input/output pairs
              │  constraints  10% │  scope, edge cases
              │  output_fmt   10% │  format specification
              │  efficiency   10% │  no filler, no redundancy
              │                   │
              │  ░░░░░░░░░░  3.2  │
              └────────┬──────────┘
                       │
                       ▼
              ┌───────────────────┐       techniques?
              │ Select Techniques │◄──── (force override)
              │                   │
              │  when_to_use() ×  │  11 predicates
              │  intent match  ×  │  filtered
              │  score gaps    ×  │  sorted by impact
              │  cap at 4        │
              └────────┬──────────┘
                       │
                       ▼
              ┌───────────────────┐
              │ Template Assembly │
              │                   │
              │  role preamble    │  expert identity
              │  →       │  grounding data first
              │  →          │  XML-wrapped prompt
              │  →  │  constraints + gaps
              │  →      │  multishot I/O pairs
              │  → output format  │  format specification
              └────────┬──────────┘
                       │
                       ▼
              ┌───────────────────┐
              │   Score After     │
              │                   │
              │  ░░░▓▓▓▓▓▓▓░░ 7.8│
              └────────┬──────────┘
                       │
                       ▼
                    OUTPUT
              optimized_prompt
              + scores + techniques
              + issues + suggestions

     score meter (gradient fill bar):
     ─────────────────────────────────

     🪶 3.2 ░░░▓▓▓▓▓▓▓▓ 7.8
        +xml-tags +few-shot +structured-output
        Wrapped in XML, added examples, format

     ░░░  baseline    ▓▓▓  improvement    ░░  headroom
```

**7 quality dimensions** (weighted scoring, deterministic):

| Dimension        | Weight | Measures                                |
| ---------------- | ------ | --------------------------------------- |
| Clarity          | 20%    | Strong verbs, single task, no hedging   |
| Specificity      | 20%    | Named tech, numbers, constraints        |
| Structure        | 15%    | XML tags, headers, lists                |
| Examples         | 15%    | Input/output pairs, demonstrations      |
| Constraints      | 10%    | Negative constraints, scope, edge cases |
| Output Format    | 10%    | Format spec, structure definition       |
| Token Efficiency | 10%    | No filler, no redundancy                |

**11 Anthropic techniques** (auto-selected based on intent, scores, and complexity):

| ID                       | Name                                                                                                                         | Auto-selected when                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `chain-of-thought`       | [Let Claude Think](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-of-thought)                 | Analysis intent, complex tasks         |
| `xml-tags`               | [Use XML Tags](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags)                         | Long prompt + low structure score      |
| `few-shot`               | [Multishot Examples](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/multishot-prompting)            | Low example score + extraction/code    |
| `role-assignment`        | [System Prompts & Roles](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/system-prompts)             | System intent or low specificity       |
| `structured-output`      | [Control Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/fill-in-the-blank)           | Low output format score                |
| `prefill`                | [Structured Output Format](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prefill-claudes-response) | API target + extraction/code           |
| `prompt-chaining`        | [Chain Complex Tasks](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/chain-prompts)                 | Complex + multiple subtasks            |
| `uncertainty-permission` | [Say "I Don't Know"](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/ask-claude-for-rewrites)        | Analysis or extraction intent          |
| `extended-thinking`      | [Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)                                  | Complex + analysis/code intent         |
| `long-context-tips`      | [Long Context](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips)                    | Long prompt (>2000 chars or >50 lines) |
| `tool-use`               | [Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview)                                           | Prompt mentions tool/function calling  |

**Core algorithms:**

- **[Intent detection](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/analysis/detector.ts)** (`detectIntent`): Priority-ordered regex patterns across 6 categories: `system > code > extraction > analysis > creative > conversation`. Includes disambiguation (e.g., `system` + `code` signals resolves to `code`) and fallback heuristics for code blocks, "build me" patterns, and debugging language.
- **[Heuristic scoring](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/analysis/heuristics.ts)** (`scorePrompt`): 7-dimension weighted analysis. Each dimension 0-10, overall is weighted sum. Also generates flat `issues[]` and `suggestions[]` arrays.
- **[Technique selection](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/techniques/index.ts)** (`selectTechniques`): Each technique has a `when_to_use()` predicate. Auto-selected based on intent + scores + complexity. Sorted by impact, capped at 4.
- **[Template assembly](https://github.com/Vvkmnn/claude-orator-mcp/blob/main/src/optimize.ts)** (`optimize`): Builds structural scaffold from selected techniques. Context-first ordering: role → `` → `` → `` → `` → output format.

**Design principles:**

- **Single tool**: one entry point, minimal cognitive overhead
- **Deterministic**: same input, same output. No LLM calls, no network
- **Scaffold, not final**: the optimized prompt is structural; Claude adds substance
- **Lean output**: flat string arrays for issues/suggestions, no nested objects
- **Weighted dimensions**: clarity and specificity matter most (20% each)
- **Technique cap**: max 4 techniques per optimization (diminishing returns beyond)
- **Anti-pattern detection**: 12 Claude-specific anti-patterns + 20 industry patterns from 34 production AI tools
- **Zero dependencies**: only `@modelcontextprotocol/sdk` + `zod`

## alternatives

Every existing prompt optimization tool requires LLM calls, labeled datasets, or evaluation infrastructure. When you need structural improvement at zero latency (CI/CD, subagent dispatch, offline), they cannot help.

| Feature                | **orator**              | DSPy           | promptfoo       | TextGrad       | OPRO           | LLMLingua      | Anthropic Generator |
| ---------------------- | ----------------------- | -------------- | --------------- | -------------- | -------------- | -------------- | ------------------- |
| **Zero latency**       | **Yes (=20.0.0 (ES modules)
- **Runtime**: `@modelcontextprotocol/sdk`, `zod`
- **Zero external databases**: works with `npx`

**Development workflow:**

```bash
npm run build          # TypeScript compilation with executable permissions
npm run dev            # Watch mode with tsc --watch
npm run start          # Run the MCP server directly
npm run lint           # ESLint code quality checks
npm run lint:fix       # Auto-fix linting issues
npm run format         # Prettier formatting (src/)
npm run format:check   # Check formatting without changes
npm run typecheck      # TypeScript validation without emit
npm run test           # Lint + type check + vitest (25 tests)
npm run prepublishOnly # Pre-publish validation (build + lint + format:check)
```

**Git hooks (via Husky):**

- **pre-commit**: Auto-formats staged `.ts` files with Prettier and ESLint

Contributing:

- Fork the repository and create feature branches
- Follow TypeScript strict mode and [MCP protocol](https://modelcontextprotocol.io/specification) standards

Learn from examples:

- [Official MCP servers](https://github.com/modelcontextprotocol/servers) for reference implementations
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for best practices
- [Creating Node.js modules](https://docs.npmjs.com/creating-node-js-modules) for npm package development
- [Anthropic prompt engineering docs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) for technique details

## acknowledgments

Industry pattern

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Vvkmnn](https://github.com/Vvkmnn)
- **Source:** [Vvkmnn/claude-orator-mcp](https://github.com/Vvkmnn/claude-orator-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-vvkmnn-claude-orator-mcp
- Seller: https://agentstack.voostack.com/s/vvkmnn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.