BlindWrite MCP 🖋️

Think with Claude, Write with OpenRouter. Production-grade Model Context Protocol (MCP) server for blind, bias-free AI writing benchmarks and high-speed token-saving writing delegation inside Claude Desktop.

Just want to install it? See INSTALL.md for step-by-step setup only.

Custom instructions to prevent Claude bypassing BlindWrite MCP? See CLAUDE_PROMPT.md — paste it into Claude Desktop's Custom Instructions so drafting always delegates to writer_generate, even if skill routing fails.

Looking for the full content production pipeline? Jump to Section 7: Autonomous Content Production Pipeline (/create-content) to produce complete, audited, publish-ready articles with DataForSEO, Firecrawl, and OpenRouter in a single command.

1. Problem & Purpose

Writers, marketers, and knowledge workers face two major challenges when using LLMs for writing:

1. Token Inefficiency & Cost: Asking Claude to generate thousands of words of draft text burns through Claude output limits and tokens rapidly.

2. Brand Bias in Model Selection: When picking an AI model, brand names ("GPT-4o", "Claude 3.5 Sonnet") skew perception, even when lightweight, focused models might write better copy for your specific voice.

BlindWrite MCP introduces the "Think with Claude, Write with OpenRouter" hybrid workflow:

• Claude for Thinking & Strategy: Claude handles deep reasoning, structural outlines, audience angles, and critical review.

• OpenRouter for Heavy Writing: Claude delegates long-form drafting directly via writer_generate to your top-ranked OpenRouter model (GLM 5.3), generating drafts in seconds while saving thousands of Claude generation tokens.

• Blind A/B Benchmarking: When testing styles, competing frontier models generate blind drafts (Response A vs Response B) with zero brand leakage. You vote, and the Bradley-Terry MLE & Elo engine trains your personal leaderboard!

• Preference Analytics: Discovers empirical writing metrics (conciseness, bulleted structure, formality) to show why your top models resonate with you.

Related MCP server: panel-review MCP server

2. Architecture

 ┌─────────────────────────────────────────────────────────────┐
 │                 Claude Desktop (Client UI)                  │
 └──────────────────────────────┬──────────────────────────────┘
                                │
                                │ stdio JSON-RPC (MCP)
                                ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                       BlindWrite MCP                        │
 │                                                             │
 │  ┌───────────────────────────────────────────────────────┐  │
 │  │                    MCP Tools Layer                    │  │
 │  │  10 Tools • Zod Schemas • Strict Blindness Gating     │  │
 │  └───────────────────────────┬───────────────────────────┘  │
 │                              │                              │
 │  ┌───────────────────────────▼───────────────────────────┐  │
 │  │                 Domain Services Layer                 │  │
 │  │  - BenchmarkService    - Duel & RandomizationService  │  │
 │  │  - VotingService       - Bradley-Terry & Elo Engine   │  │
 │  │  - AnalyticsService    - OpenRouterClient & Cost      │  │
 │  └─────────────┬───────────────────────────┬─────────────┘  │
 │                │                           │                │
 │                ▼                           ▼                │
 │  ┌──────────────────────────┐ ┌──────────────────────────┐  │
 │  │   SQLite Data Layer      │ │    OpenRouter Gateway    │  │
 │  │  - WAL mode & Pragma FK  │ │  - Latency measurement   │  │
 │  │  - Repositories: Tasks,  │ │  - Token & cost tracking │  │
 │  │    Models, Outputs,      │ │  - Error & retry policy  │  │
 │  │    Battles, Votes        │ └────────────┬─────────────┘  │
 │  └──────────────────────────┘              │                │
 └────────────────────────────────────────────┼────────────────┘
                                              │ HTTPS
                                              ▼
                               ┌─────────────────────────────┐
                               │       OpenRouter API        │
                               │ ┌─────────┬─────────┬─────┐ │
                               │ │ Claude  │ GPT-4o  │ ... │ │
                               │ └─────────┴─────────┴─────┘ │
                               └─────────────────────────────┘

Critical Stdio Hygiene: Standard output (stdout) is strictly reserved for MCP JSON-RPC protocol packets. All internal diagnostics, logging, and error output route exclusively to stderr, guaranteeing that Claude Desktop never crashes from corrupted transport data.

3. The 11 MCP Tools

4. Pre-Seeded Writing Categories & Models

Writing Categories

• General Writing

• Emails (Cold outreach, executive memos, customer service)

• Business Writing (Proposals, pitches, quarterly summaries)

• Creative Writing (Narrative storytelling, dialogue, fiction)

• Marketing (Ad copy, landing pages, taglines)

• Summarization (Executive briefs, meeting notes)

• Rewriting (Tone shifting, simplifying complex text)

• Technical Writing (API documentation, engineering RFCs)

• Persuasive Writing (Op-eds, debate arguments, sales letters)

• Research Writing (Literature synthesis, analytical essays)

• Social Media (Threads, LinkedIn posts, announcements)

• Instruction Following (Constraint adherence, exact formatting)

Seed Model (OpenRouter)

• GLM 5.3 (z-ai/glm-5.3)

5. Quickstart & Installation

Option A: 1-Line Autonomous Remote Installer (Fastest — No Git Clone Required)

Run a single command in your terminal. It will automatically check/install Node.js & Git, clone into your user directory, build the project, prompt for your OpenRouter key, auto-install the Writing Orchestrator Skill, and configure Claude Desktop:

Windows (PowerShell):

irm https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.ps1 | iex

(Tip: You can pre-supply your key to make it 100% headless: $env:OPENROUTER_API_KEY="sk-or-v1-..."; irm https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.ps1 | iex)

macOS & Linux (Terminal):

curl -fsSL https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.sh | bash

(Tip: Or headless: OPENROUTER_API_KEY="sk-or-v1-..." curl -fsSL https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.sh | bash)

Manual Skill Installation (If using 1-Line Remote Installer):

While the remote installer automatically registers the MCP server in claude_desktop_config.json, you can also manually install or upload the Writing Orchestrator Skill to your Claude environment:

1. Claude Desktop App (Account Upload via UI — ZIP or Direct MD):

   • In Claude Desktop, open Customize > Skills from the sidebar.

   • Click the + button and choose "Upload a skill".

   • You can upload either:

     • ZIP Archive: Select writing-orchestrator.zip (located at %LOCALAPPDATA%\BlindWrite_MCP\skills\writing-orchestrator.zip on Windows, or ~/.blindwrite-mcp/skills/writing-orchestrator.zip on macOS/Linux). If you manually zip the folder on Windows, right-click writing-orchestrator folder → Compress to ZIP file (or use 7-Zip).

     • Direct .md File (No ZIP needed!): Directly select SKILL.md from your skills/writing-orchestrator/SKILL.md folder.

   • Ensure the skill toggle is switched ON (synced directly to your Anthropic account in the cloud).

2. Claude Code / Terminal Integration (Local Filesystem):

   • Windows (PowerShell):

     New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\writing-orchestrator"
     Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/skills/writing-orchestrator/SKILL.md" -OutFile "$HOME\.claude\skills\writing-orchestrator\SKILL.md"

   • macOS / Linux (Bash):

     mkdir -p ~/.claude/skills/writing-orchestrator && curl -fsSL https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/skills/writing-orchestrator/SKILL.md -o ~/.claude/skills/writing-orchestrator/SKILL.md

3. Zero-Setup Native MCP Prompt:

   • The installer already configures Claude Desktop to expose the /writing-orchestrator MCP Prompt natively. You can type /writing-orchestrator directly in any chat without copying any files!

Option B: Local 1-Click Setup (If already cloned)

On Windows:

Simply run setup.bat (or double-click it in File Explorer):

setup.bat

• Auto-installs Node.js via winget if not detected on your system.

• Installs dependencies (npm install).

• Compiles TypeScript (npm run build).

• Prompts for your OpenRouter API key.

• Automatically merges the configuration into %APPDATA%\Claude\claude_desktop_config.json (with automatic backup).

• Auto-installs the Writing Orchestrator Skill into ~/.claude/skills/writing-orchestrator and agent environments.

On macOS / Linux:

chmod +x setup.sh
./setup.sh
# or after npm install:
npm run setup

Option C: Manual Setup

1. Clone and Install:

git clone https://github.com/ygstudio-game/BlindWrite_MCP.git
cd BlindWrite_MCP
npm install

2. Configure Environment:

cp .env.example .env

Edit .env and set OPENROUTER_API_KEY=sk-or-v1-....

3. Build and Run Setup Wizard:

npm run build
npm run setup

The interactive wizard will automatically resolve exact paths and update Claude Desktop for you!

🔄 How to Update BlindWrite MCP

To update your existing installation to the latest version:

Method 1: Re-run the 1-Line Remote Installer (Fastest)

Simply re-run the 1-line command in your terminal. It will automatically detect your existing installation, pull the latest updates from GitHub, and rebuild:

• Windows (PowerShell):

  irm https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.ps1 | iex

• macOS / Linux (Bash):

  curl -fsSL https://raw.githubusercontent.com/ygstudio-game/BlindWrite_MCP/main/scripts/install.sh | bash

Method 2: Terminal Update

Navigate to your installation directory and pull the latest code:

• Windows (PowerShell):

  cd "$env:LOCALAPPDATA\BlindWrite_MCP"
  git fetch origin main
  git reset --hard origin/main
  npm install --ignore-scripts
  npm run build
  node scripts/setup.js --yes

• macOS / Linux (Bash):

  cd ~/.blindwrite-mcp
  git fetch origin main
  git reset --hard origin/main
  npm install --ignore-scripts
  npm run build
  node scripts/setup.js --yes

(If you cloned into a custom directory, run git pull origin main && npm run build inside that folder).

After Updating:

1. Restart Claude Desktop: Completely quit Claude Desktop (Right-click tray icon → Quit) and reopen it.

2. Skill Update (Optional): In Claude Desktop (Customize > Skills), re-upload writing-orchestrator.zip or SKILL.md to refresh your account skill.

6. Claude Desktop Configuration (Manual)

If you prefer to configure Claude Desktop manually instead of using npm run setup:

1. Open your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the blindwrite server:

{
  "mcpServers": {
    "blindwrite": {
      "command": "node",
      "args": [
        "/absolute/path/to/BlindWrite_MCP/dist/index.js"
      ],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-openrouter-key-here",
        "DB_PATH": "/absolute/path/to/BlindWrite_MCP/data/blindwrite.sqlite",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Platform Path Examples:

• macOS / Linux: "/Users/yourname/projects/BlindWrite_MCP/dist/index.js"

• Windows: "C:\\Users\\yourname\\projects\\BlindWrite_MCP\\dist\\index.js" (ensure backslashes are escaped with \\)

3. Restart Claude Desktop. You will see the hammer icon with all 11 BlindWrite tools ready to use!

4. Writing Orchestrator Skill & Prompt:

   • Skill Source: Read the complete skill definition in skills/writing-orchestrator/SKILL.md.

   • Upload to Claude Desktop: In Claude Desktop (Customize > Skills > + > Upload a skill), upload either writing-orchestrator.zip or select SKILL.md directly (no zip required).

   • Manual ZIP Creation: If manually zipping the folder on Windows, right-click writing-orchestrator folder → Compress to ZIP file (or use 7-Zip).

   • Auto-Installed Local Folders: The setup script auto-populates %APPDATA%\Claude\skills\writing-orchestrator\SKILL.md, ~/.claude/skills/writing-orchestrator/SKILL.md, and project-level .claude/skills/.

   • Native MCP Prompt: The server natively registers the /writing-orchestrator prompt accessible directly inside Claude Desktop chat without uploading any files!

   • Project Instructions: For Claude Desktop Projects, copy CLAUDE_PROMPT.md into your Project's Custom Instructions.

   • How to invoke in chat: Simply tell Claude:

     "Use the writing-orchestrator skill to outline our strategy and draft..."
     or select the /writing-orchestrator prompt template from the chat input menu.

7. Autonomous Content Production Pipeline (/create-content)

One Invocation. One Publish-Ready Article.
The autonomous content pipeline orchestrates Claude, DataForSEO, Firecrawl, and OpenRouter into an uninterrupted end-to-end publishing pipeline. It handles preflight checks, intake, SERP/competitor research, quality checklist compilation, high-speed drafting, dual-gate AI/EEAT auditing, and automated revision loops with zero manual glue.

flowchart TD
    subgraph Phase0 [Phase 0: Preflight]
        P0A[Verify MCP Bridge] --> P0B[Resolve Site from Registry]
        P0B --> P0C[Verify Voice Doc]
        P0C --> P0D[Confirm Enabled Models]
    end

    subgraph Phase1 [Phase 1: Intake]
        P1A[Capture Topic & Constraints] --> P1B[Generate Job ID]
        P1B --> P1C[Load Content Profile]
    end

    subgraph Phase2 [Phase 2: Research & Brief]
        P2A[DataForSEO SERP Analysis] --> P2B[Firecrawl Competitor Extraction]
        P2B --> P2C[Compile MASTER_WRITING_BRIEF]
    end

    subgraph Phase3 [Phase 3: Checklist & Voice]
        P3A[Verbatim Quality Checklist] --> P3B[Verbatim Voice Requirements]
        P3B --> P3C[Assemble Prompt Architecture]
    end

    subgraph Phase4 [Phase 4: Draft & Revision Loop]
        P4A[OpenRouter Drafting via writing-orchestrator] --> P4B[Claude Dual-Gate Audit]
        P4B -->|Needs Revision max 3x| P4C[Targeted Fix Prompt]
        P4C --> P4A
    end

    subgraph Phase5 [Phase 5: Clean Delivery]
        P4B -->|Pass| P5A[Save to data/drafts/]
        P5A --> P5B[Log Job to data/jobs/]
        P5B --> P5C[Clean Markdown Output in Chat]
    end

    Phase0 --> Phase1 --> Phase2 --> Phase3 --> Phase4 --> Phase5

7.1 How to Run (Single Invocation)

In Claude Desktop or Claude Code, simply invoke /create-content:

/create-content

Site: example.com
Keyword: productivity tools for remote teams
Topic: Complete Guide to Remote Team Productivity
Content type: seo_article
Target length: 1500-2000 words
Special requirements: Include comparison table of key features and workflows

(Note: If your active Claude Project name matches the site, or if you omit Site:, the universal default profile is applied automatically).

7.2 The 6 Execution Phases

7.3 Site Configuration & Profiles

The create-content skill is 100% self-contained and works for any website or niche out of the box with built-in default and customizable profiles:

site: example.com
status: active # active | out_of_scope | blocked
voice_doc_path: "d:/path/to/voice-guidelines.md" # or inline voice guidelines
persona: "Senior Tech Journalist & Product Specialist"
hard_rules:
  - "Cite verifiable benchmark and workflow data."
  - "No artificial hype or marketing fluff."
content_profiles:
  seo_article:
    pre_writing_skill: semantic-seo-content
    voice_skill: heading-microcopy-writer
    target_length_default: "1800-2400 words"

7.4 Supported Drafting Model & Cost Breakdown

The pipeline exclusively uses GLM 5.3 configured for high-velocity drafting:

7.5 Stop Conditions & Escalation Handling

The pipeline stops and asks for human intervention only on critical edge cases:

• MCP Bridge Disconnected: If benchmark_list_models fails, it halts immediately without silent Claude fallback.

• Voice Document Missing / "PENDING": Halts to prevent generating content in an uncalibrated tone. Users can provide the file path or explicitly sign off on proceeding with generic voice.

• Out of Scope Site: Sites marked status: out_of_scope are rejected with the recorded reason.

• Escalation after 3 Loops: If an audit issue persists across 3 OpenRouter revisions, the pipeline offers three explicit options:

  1. Ship with the audit caveat noted.

  2. One-time exception: Claude directly polishes the remaining flagged lines.

  3. Re-draft with GLM 5.3.

8. Example Workflows in Claude Desktop

Workflow A: High-Conversion B2B Cold Outreach Email

Goal: Craft a personalized, high-response email while saving Claude output tokens.

You:

"Help me draft a 120-word cold outreach email to a VP of Sales about our developer platform. Use the writing-orchestrator skill to outline the strategy first and use writer_generate to draft it."

Claude (Thinking & Strategy Brain):

1. Analyzes the VP of Sales persona (time-poor, quota-focused, values proven ROI).

2. Formulates the prompt blueprint (Hook: shortening deal cycles by 40%; Body: 2 concrete metrics; CTA: 10-minute intro).

3. Delegates drafting: Calls writer_generate(category: "Emails", prompt: "...", max_tokens: 400).

4. OpenRouter generates the draft in ~800ms using your personal #1 model (GLM 5.3).

5. Zero-Tax Direct Delivery: Claude presents the generated email verbatim with the metrics badge (saved ~300 Claude output tokens, cost $0.0003), auto-saved to data/drafts/, without burning extra tokens on unprompted critique.

Workflow B: Technical Architecture RFC / Migration Spec

Goal: Generate a comprehensive 1,500-word engineering RFC with deep strategic framing.

You:

"We need an RFC for migrating our monolithic PostgreSQL database to a globally distributed database with zero downtime. Use the writing-orchestrator skill to structure the technical plan and delegate the drafting."

Claude (Thinking & Strategy Brain):

1. Produces an architectural breakdown:

   • Problem statement & current bottlenecks

   • Dual-write replication architecture & cutover sequence

   • Failure modes, rollback triggers, and data validation

2. Calls writer_generate(category: "Technical Writing", prompt: "Write section 2 and 3 covering dual-write synchronization and consistency models...", max_tokens: 2500).

3. OpenRouter streams the extensive technical draft in seconds.

4. Claude critically audits the draft, flags edge cases in network partition scenarios, and polishes the summary.

Workflow C: High-Converting SaaS Landing Page Copy

Goal: Draft hero headlines, subheads, and 3 value pillars.

You:

"Write landing page hero section copy and 3 core value pillars for an AI agent observability tool. Use the writing-orchestrator skill."

Claude (Thinking & Strategy Brain):

1. Outlines the positioning: Anti-hype, focused on debugging production hallucinations and latency spikes.

2. Calls writer_generate(category: "Marketing Copy", prompt: "Craft punchy H1 headline, 2-sentence subhead, and 3 customer-outcome pillars with proof points...", max_tokens: 800).

3. Displays the full landing page copy with clear visual hierarchy, ready for deployment.

Workflow D: Thought Leadership / Technical Blog Post

Goal: Write an engaging 800-word essay with a contrarian engineering thesis.

You:

"Draft an engineering blog post arguing why autonomous agent swarms will replace traditional CI/CD pipelines by 2027. Use the writing-orchestrator skill."

Claude (Thinking & Strategy Brain):

1. Establishes the contrarian hook, 3 narrative beats, and concrete code pipeline analogies.

2. Calls writer_generate(category: "Blog Posts", prompt: "...", max_tokens: 1500).

3. OpenRouter drafts the essay using your preferred style profile.

4. Claude reviews flow, rhythm, and tone, delivering an impactful publication-ready draft.

Workflow E: Blind A/B Benchmark Duel (Style Discovery)

Goal: Objectively determine which frontier model writes best for your personal voice without brand bias.

You:

"Benchmark the best models for writing an executive pitch email to CTOs."

Claude:

1. Calls benchmark_create_task(title: "CTO Pitch", category: "Emails", prompt: "...").

2. Calls benchmark_generate_outputs(taskId) to query competing models in parallel via OpenRouter.

3. Calls benchmark_start_duel(taskId) and displays anonymous options:

   Response A:
   [Anonymous output]

   Response B:
   [Anonymous output]

   Which response is more compelling, A or B?

4. You vote: "Response A is punchier and highlights developer productivity much better."

5. Claude calls benchmark_submit_vote(battleId, choice: "A").

6. When satisfied, you ask: "Reveal results!"

7. Claude calls benchmark_get_results(taskId, reveal: true):

   • Response A was Claude 3.5 Sonnet (Score: 1240, Latency: 780ms)

   • Response B was GPT-4o (Score: 1195, Latency: 910ms)

8. Claude calls benchmark_get_leaderboard and benchmark_analyze_preferences to update your personal ranking!

9. Mathematical Ranking Details

Bradley-Terry Maximum Likelihood Estimation (MLE)

Pairwise choice probabilities follow: $$P(i \succ j) = \frac{\pi_i}{\pi_i + \pi_j} = \frac{e^{\beta_i}}{e^{\beta_i} + e^{\beta_j}}$$

The model latent parameters $\pi$ are solved using the iterative Minorization-Maximization (MM / Hunter 2004) algorithm with Laplace prior regularization ($\alpha = 1.0$) for numerical stability with disconnected matchup graphs: $$\pi_i^{(t+1)} = \frac{W_i + \alpha}{\sum_{j \ne i} \frac{N_{ij}}{\pi_i^{(t)} + \pi_j^{(t)}} + \alpha}$$

• Uncertainty Quantification: Standard errors are derived from the observed Fisher Information matrix:

  • $< 5$ battles: Preliminary (High Uncertainty)

  • $5–15$ battles: Emerging (Moderate Uncertainty)

  • $> 15$ battles: Established (High Confidence)

10. Testing

The project includes an extensive test suite verifying mathematical correctness, zero-bias coin toss distributions, strict anonymity boundaries, and end-to-end tournament simulations:

# Run all unit and integration tests
npm test

# Run tests in watch mode
npm run test:watch

11. License

MIT © Yadnyesh Borole.