Signalforge

npm version license

SignalForge is a local-first MCP prompt intent compiler. It turns vague user requests into task-specific, cost-aware prompts for Codex first, while keeping adapters for Claude Code, Cursor, ChatGPT, Kimi, and generic LLM workflows.

It is not another prompt prettifier. SignalForge detects intent, missing context, workflow shape, context waste, and likely failure modes before you spend a full model run.

The v2 direction adds RAG before generation: SignalForge can explicitly index trusted local docs, retrieve only the small snippets relevant to a rough request, and compile those snippets into the final agent prompt with source and trust labels.

What It Does

• Analyzes rough prompts for task type, clarity, missing context, and waste risks.
• Indexes trusted local project docs into .signalforge/context-index.json.
• Expands vague retrieval queries into concrete focus areas like UX, accessibility, performance, tests, and project setup.
• Retrieves budgeted, source-tagged context snippets before compilation.
• Compiles prompts for Codex, Claude Code, Cursor, ChatGPT, Kimi, or generic clients.
• Suggests split plans for large tasks instead of one expensive mega-prompt.
• Provides reusable prompt patterns for common workflows.
• Saves only user-approved patterns locally in .signalforge/patterns.json.
• Does not save raw prompts by default.

Install

Install from npm (recommended):

npm install -g signalforge-mcp

This exposes two commands: signalforge (CLI) and signalforge-mcp (the MCP server).

Or add it to a single project:

npm install signalforge-mcp

Build from source

git clone https://github.com/karthikeyGoli/signalforge.git
cd signalforge
npm install
npm run build

Run As An MCP Server

Codex:

codex mcp add signalforge -- signalforge-mcp

Claude Desktop / Claude Code style config:

{
  "mcpServers": {
    "signalforge": {
      "command": "signalforge-mcp"
    }
  }
}

If you prefer not to install globally, you can run it on demand with npx:

{
  "mcpServers": {
    "signalforge": {
      "command": "npx",
      "args": ["-y", "signalforge-mcp"]
    }
  }
}

MCP Inspector (from a source checkout):

npm run inspect

CLI Smoke Test

npm run smoke

Or run directly:

node dist/cli.js analyze "build me a portfolio app" --target codex
node dist/cli.js compile "build me a portfolio app" --target codex
node dist/cli.js index-context README.md AGENTS.md docs
node dist/cli.js compile "make my app better" --target codex --with-context
node dist/cli.js compile "compare these two startup ideas" --target kimi
node dist/cli.js pattern feature_build --target codex

Use With Kimi

Kimi does not need MCP support for this flow. Compile the prompt locally, then paste the output into Kimi:

node dist/cli.js compile "help me design an AI automation product" --target kimi

MCP Tools

• analyze_prompt: intent, clarity, missing context, waste risks, workflow.
• compile_prompt: ready-to-use prompt with assumptions, split plan, optional retrieved context, and cost-saving notes.
• index_context: index explicit local trusted docs or repo guidance for RAG-backed compilation.
• retrieve_context: retrieve budgeted source-tagged snippets from the local context index.
• get_prompt_pattern: reusable template for a use case.
• estimate_prompt_waste: likely failure mode and cheaper prompting route.
• save_pattern: store a user-approved pattern locally.
• list_patterns: list saved local patterns.

MCP Resources

• signalforge://patterns
• signalforge://adapters/codex
• signalforge://adapters/claude-code
• signalforge://adapters/cursor
• signalforge://adapters/chatgpt
• signalforge://adapters/kimi
• signalforge://adapters/generic
• signalforge://context/index
• signalforge://history/recent

RAG-Backed Compilation

SignalForge uses retrieval to improve the prompt, not to answer the user directly.

node dist/cli.js index-context README.md AGENTS.md docs
node dist/cli.js retrieve-context "make my app better"
node dist/cli.js compile "make my app better" --target codex --with-context

For vague requests, retrieval uses deterministic query expansion before scoring. For example, make my app better expands into focus terms such as ui, ux, accessibility, performance, responsive, tests, build, package, and agents. This keeps the system local and predictable while making it less dependent on exact keyword overlap.

The compiled prompt includes retrieved local context with source paths, trust labels, and a note that snippets are reference material rather than higher-priority instructions. This keeps the prompt grounded without letting random retrieved text override the user or client instructions.

Development

npm run test
npm run build
npm run smoke

The compiler, query expansion, and local retrieval are deterministic. Optional embeddings or LLM refinement can be added later behind an environment flag, but the core should remain useful without any API key.