Prompt Forge MCP

One MCP entry point for better AI work. Prompt Forge turns short, vague requests into structured, context-aware task contracts that your AI host can execute.

✨ The idea

You write a simple request:

Build me a beautiful, modern restaurant website.

Prompt Forge decides what the request needs, gathers only useful context, improves the task definition, and returns a high-quality prompt for the AI model already connected to your MCP host.

Short request
    ↓
Intent & risk analysis
    ↓
Task expansion and missing-information checks
    ↓
Memory, local Context Engine, web, npm, GitHub, or connectors when useful
    ↓
Source-aware prompt contract
    ↓
Your host model continues the work

The user does not need to select MCP servers manually. Prompt Forge acts as the lightweight decision layer between the request and the model.

🚀 Quick start

Requires Node.js 20 or newer.

Run the interactive installer:

npx -y @dark_creative/prompt-forge-mcp

Use the arrow keys to move, press Space to select or deselect clients, and press Enter to install the selected configurations.

The installer includes a colored terminal interface with a highlighted active client, selection count, and clear success/error states. Use A to select all clients, N to clear the selection, Home/End to jump through the list, and Q or Esc to cancel.

The installer supports:

| Client | Installation method | | --- | --- | | Claude Desktop | Merges the user MCP configuration | | Claude Code | Uses claude mcp add when available | | Kilo Code | Updates the global Kilo MCP configuration | | Antigravity | Updates the Gemini/Antigravity MCP configuration | | OpenCode CLI + Desktop | Uses the shared global OpenCode MCP configuration | | ChatGPT | Use the optional Streamable HTTP mode described below |

Install one client directly

npx -y @dark_creative/prompt-forge-mcp setup --client claude-desktop
npx -y @dark_creative/prompt-forge-mcp setup --client claude-code
npx -y @dark_creative/prompt-forge-mcp setup --client kilo-code
npx -y @dark_creative/prompt-forge-mcp setup --client antigravity
npx -y @dark_creative/prompt-forge-mcp setup --client opencode

Start the MCP server directly

Use --server when an IDE or another MCP host starts Prompt Forge in the background:

npx -y @dark_creative/prompt-forge-mcp --server

On Windows, some hosts use npx.cmd instead of npx.

OpenCode CLI and Desktop

OpenCode's CLI and desktop app read the same global configuration. The installer first tries the native CLI command:

opencode mcp add --global prompt-forge -- npx -y @dark_creative/prompt-forge-mcp --server

If the OpenCode CLI is not available, Prompt Forge writes the equivalent entry to ~/.config/opencode/opencode.json (using npx.cmd on Windows and npx elsewhere). The interactive installer also adds a marked Prompt Forge routing block to OpenCode's global AGENTS.md, so ordinary user requests automatically pass through prompt-forge_orchestrate and drafted answers pass through prompt-forge_validate_output. Restart OpenCode after installation.

For a manual setup, copy config/clients/opencode.instructions.md into the global ~/.config/opencode/AGENTS.md or the project AGENTS.md, then copy config/clients/opencode.json into OpenCode's global configuration.

🧠 What Prompt Forge does

For every request, Prompt Forge can:

• classify the user's intent and task complexity;
• choose a suitable working mode: fast, balanced, or deep;
• detect missing information and state reasonable assumptions;
• expand a short request into actionable requirements;
• add deterministic specialist implementation guidance for frontend, motion, and high-end portfolio work;
• select the right context sources automatically;
• use saved preferences without exposing unnecessary memory;
• inspect documentation, package metadata, public repositories, or web pages when needed;
• remove irrelevant context to protect the token budget;
• preserve citations, source URLs, confidence, and execution details;
• return a deterministic fallback when a host capability or network source is unavailable;
• produce a prompt contract that the connected model can continue executing.

The host model remains responsible for the final generation. Prompt Forge does not download or run a local LLM.

🎨 Taste-inspired design policy and safe response compression

Prompt Forge includes a small, local policy layer inspired by two complementary ideas:

• Taste-style design direction: frontend requests receive an intentional preset, design dials, anti-slop checks, and a preflight checklist. The policy is automatically activated for portfolio, landing-page, UI, animation, Three.js, GSAP, and similar visual tasks.
• Caveman-style response control: concise requests can use a deterministic local compression pass that removes prose filler while preserving technical content byte-for-byte.

These are native Prompt Forge policies, not runtime dependencies on either external repository. No additional model, daemon, embedding service, or API key is required.

orchestrate returns designContract and responseStyleContract alongside the optimized prompt. You can also provide explicit overrides when an MCP host supports tool arguments:

{
  "request": "Build a cinematic Three.js portfolio.",
  "designPreset": "cinematic-editorial",
  "responseStyle": "detailed"
}

For an allowed concise response, call compress_output and then call validate_output again. The compressor protects code, commands, URLs, paths, identifiers, errors, citations, and security warnings. Security, credential, deletion, migration, deployment, and other clarity-critical requests automatically keep normal detail.

📚 A Context7-style engine built into the project

Prompt Forge does not depend on the original Context7 service. It includes its own local-first Context Engine for documentation and project knowledge.

Source
  → sanitize HTML/Markdown
  → split into meaningful sections
  → attach library, version, title, and URL metadata
  → build a lightweight local index
  → search with lexical + trigram similarity
  → boost exact phrases, headings, scope, and source agreement
  → return compact citations with confidence

The Context Engine supports:

• local Markdown and text documents;
• public documentation URLs;
• npm package metadata and README files;
• library and version-aware indexing;
• section-aware citations;
• hybrid and lexical search modes;
• lightweight similarity without downloading embedding models;
• source confidence and agreement signals;
• stale-source detection and refresh;
• persistent local indexes with atomic writes and process locks;
• bounded memory, document, chunk, response, and timeout limits;
• protection against private-network URLs, unsafe redirects, and oversized responses.

When automatic indexing is enabled, common packages such as React, TypeScript, Next.js, Vue, Svelte, Express, NestJS, Vite, Zod, Tailwind CSS, and Three.js can be discovered from npm metadata when the request needs them. fast mode never performs network-backed indexing.

For documentation-oriented requests, Prompt Forge also has curated official endpoints for common libraries including React, TypeScript, Next.js, Vue, Svelte, Three.js, GSAP, Anime.js, Playwright, Prisma, and more. It fetches those pages directly into the local index and keeps an official-documentation result in the final context. A package README or manifest is not accepted as a substitute when a curated official source is required but unavailable.

⚙️ Working modes

| Mode | Behaviour | Best for | | --- | --- | --- | | fast | Local-only, no network-backed source calls | Quick edits, simple prompts, offline work | | balanced | Selective context and lightweight documentation lookup | Most development and content tasks | | deep | More source gathering, deeper public-page inspection, and stronger validation | Research, unfamiliar libraries, complex multi-step work |

The mode is selected automatically, but the orchestrate tool can also receive an explicit mode.

🛠️ MCP tools

Orchestration

| Tool | Purpose | | --- | --- | | orchestrate | Analyze, plan, route context, and generate the final optimized prompt contract | | validate_output | Check a drafted answer for task coverage, source evidence, required failures, output format, score threshold, and obvious credential leakage | | compress_output | Conservatively remove prose filler from concise drafts while preserving protected technical content | | explain_decision | Explain which sources would be selected and why | | health_check | Report version, limits, memory, Context Engine, and connector health |

Context Engine

| Tool | Purpose | | --- | --- | | index_context_source | Add Markdown or text content to the local index | | index_context_url | Fetch and index a public documentation URL | | index_context_package | Index npm metadata and README content | | search_context | Search indexed documentation with citations and confidence | | context_stats | Show index size and usage statistics | | list_context_sources | List indexed sources and versions | | refresh_context_source | Refresh a stale or selected source | | remove_context_source | Remove a library, version, or URL from the index | | clear_context | Clear the local Context Engine index |

Memory and prompt history

| Tool | Purpose | | --- | --- | | remember_preference | Save an explicit user preference locally | | get_memory | Read stored preferences when relevant | | prompt_history | List previously generated prompt contracts | | favorite_prompt | Add or remove a prompt from favorites | | clear_memory | Clear stored preferences | | clear_history | Clear saved prompt history |

Connectors

| Tool | Purpose | | --- | --- | | list_connectors | Show configured connector status without exposing secrets | | External MCP connectors | Optionally connect to other MCP servers when a task genuinely needs them |

🔎 Source routing

Prompt Forge uses a layered source strategy:

1. Understand the request and its constraints.
2. Check relevant local memory and conversation context.
3. Search the local Context Engine first.
4. For known libraries, prefer curated official documentation over general web discovery.
5. Use npm, public GitHub, direct web pages, or DuckDuckGo only when useful.
6. Ask for connector approval when a configured external connector requires it.
7. Keep only relevant, trusted, bounded context.
8. Return a source-aware prompt contract for the host model and a final-answer validation contract.

Built-in public readers are intentionally lightweight:

• DuckDuckGo provides API-key-free web search with bounded results, timeout, cache, and cooldown handling.
• Public GitHub reads repository trees, README/manifest files, and a small number of relevant text files without cloning the repository.
• Direct web reads an explicitly supplied public URL with HTML cleanup and redirect/private-network checks.
• npm provides package metadata and README context for supported libraries.

Public services can still apply their own availability or anonymous rate limits. Prompt Forge reports failures and falls back instead of turning a temporary source error into a broken orchestration.

If a request says not to use general web search, Prompt Forge suppresses DuckDuckGo and other discovery connectors but can still use a direct curated official documentation page. If a request says not to use the internet, network, or external sources, all network-backed retrieval is disabled.

💬 Conversation context and attachments

When the host supports it, the connected conversation can provide:

• previous conversation context;
• text attachments;
• file references;
• image context through host sampling capabilities.

Prompt Forge treats conversation, attachment, web, repository, and connector content as untrusted data, not as system instructions. This keeps README files, screenshots, and copied text from silently changing the orchestration policy.

Binary images are not copied into local memory or history. File URIs are read only under bounded size limits, and remote URLs are not fetched automatically unless the task explicitly routes them through a supported reader.

🔐 Security and privacy

• Local stdio mode is the default.
• No local embedding model or background crawler is installed.
• Memory, history, and Context Engine data stay on the user's machine.
• External connector secrets are read from environment variables and are never included in status output.
• HTTP responses, connector output, document size, and search results are bounded.
• Public and private-network targets are validated before fetching.
• Connector retries use bounded exponential jitter, concurrency limits, and circuit breakers.
• Optional ORCHESTRATOR_DATA_KEY enables encrypted local memory/history storage.
• Without that key, the project keeps the simpler local JSON format.

🌐 Optional Streamable HTTP mode

Local stdio is the recommended mode for Claude Desktop, Claude Code, Kilo Code, Antigravity, and OpenCode. A remote host such as ChatGPT needs a public, authenticated Streamable HTTP deployment.

Linux/macOS

MCP_TRANSPORT=streamable-http \
MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_PORT=8787 \
MCP_AUTH_TOKEN="use-a-random-token-at-least-24-characters" \
npx -y @dark_creative/prompt-forge-mcp --server

Windows PowerShell

$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HTTP_HOST = "0.0.0.0"
$env:MCP_HTTP_PORT = "8787"
$env:MCP_AUTH_TOKEN = "use-a-random-token-at-least-24-characters"
npx -y @dark_creative/prompt-forge-mcp --server

The MCP endpoint is /mcp. Put a public deployment behind TLS, a reverse proxy, and rate limiting. Do not expose a development machine directly to the internet.

🔧 Configuration

The package includes ready-to-copy templates in config/clients.

Example stdio configuration:

{
  "mcpServers": {
    "prompt-forge": {
      "command": "npx",
      "args": ["-y", "@dark_creative/prompt-forge-mcp", "--server"]
    }
  }
}

OpenCode uses this equivalent configuration shape:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "prompt-forge": {
      "type": "local",
      "command": ["npx", "-y", "@dark_creative/prompt-forge-mcp", "--server"],
      "enabled": true,
      "timeout": 20000
    }
  }
}

Useful orchestration options include:

| Option | Effect | | --- | --- | | useMemory | Include relevant saved preferences | | executeSources | Run selected local or external sources | | allowExternal | Disable external MCP calls | | autoIndexSources | Disable automatic npm/documentation indexing | | refreshStaleSources | Refresh stale local sources before searching | | requireApproval | Require approval for connector calls | | useHostSampling | Allow the host model to perform a final refinement pass | | saveHistory | Save the generated prompt contract locally |

📁 Local data locations

| Platform | Location | | --- | --- | | Windows | %APPDATA%\\ai-orchestrator-mcp | | macOS | ~/Library/Application Support/ai-orchestrator-mcp | | Linux | ~/.config/ai-orchestrator-mcp |

The legacy data directory is intentionally preserved for backward-compatible migration to Prompt Forge.

🧪 Development

npm install
npm run build
npm test

Additional local checks:

npm run dev        # Run the server from TypeScript
npm run benchmark  # Measure local p50/p95 latency
npm run stress     # Run high-pressure local mock tests
npm start          # Run the compiled server

The benchmark intentionally excludes host sampling, first-time npx installation, and live Web/GitHub latency. The stress suite uses local mock services and does not send requests to external providers.

📦 Package contents

The published package contains:

• compiled server and CLI files in dist/;
• client configuration templates in config/;
• this README and the MIT license.

The default runtime is intentionally small, bounded, and suitable for a single user's local machine.

📄 License

MIT © Prompt Forge MCP contributors