@houtini/fanout-mcp

v0.2.5

Published

23 days ago

Advanced content gap analysis using Query Decomposition, Keyword Fan-Out, and Self-RAG for Generative Engine Optimization (GEO)

Fan-Out MCP

Advanced content gap analysis for the AI search era

Analyze your content to discover what user queries it covers (and misses) using the same techniques AI search engines use internally.

Why This Matters

The problem: Traditional SEO focused on keywords and backlinks. AI search engines (ChatGPT, Perplexity, Gemini) don't work that way. They evaluate whether your content can answer user queries - across dozens of query variations you've probably never considered.

The solution: This MCP uses research-backed techniques from Google and academic papers to:

Decompose complex topics into the actual questions users ask
Generate query variations using Google's patented fan-out methodology
Assess whether your content can answer each query (with evidence)
Identify specific gaps and provide actionable recommendations

The result: Content optimized for Generative Engine Optimization (GEO) - answering the queries AI search engines need to cite your work.

What It Does

Three Analysis Modes

1. Content-Only Analysis (Default) Analyzes what questions your content naturally answers based on structure and topics.

Analyze https://your-site.com/article with standard depth

2. Hybrid Analysis (Content + Keyword Targeting) Combines content analysis with keyword-specific query variants. This is the power mode.

Analyze https://your-site.com/article with target_keyword "direct drive racing wheels"

Generates 15-25 query variants by default across 5 types:

Equivalent - "sim racing wheels", "racing simulator wheels"
Specification - "Fanatec DD Pro review", "8Nm direct drive wheel"
Follow-Up - "how to calibrate racing wheel", "mounting options"
Comparison - "Fanatec vs Thrustmaster", "belt drive vs direct drive"
Clarification - "what is direct drive technology", "how does FFB work"

3. Keyword-Only Analysis Focus purely on keyword variants, skip content inference (50% faster).

Analyze https://your-site.com/article with target_keyword "sim racing" and fan_out_only true

The Output

Interactive visual dashboard showing:

Coverage score (0-100) with specific gaps identified
Query-by-query assessment with evidence quotes
Prioritized recommendations (what to add/improve)
Technical metrics (quality scores, performance data)

Plus detailed markdown report with all data.

Installation

Prerequisites

Claude Desktop (or any MCP-compatible client)
Anthropic API key
Node.js 18+ (for local build only)

Quick Setup (Recommended)

The fastest way to get started - no cloning or building required:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "fanout": {
      "command": "npx",
      "args": ["-y", "@houtini/fanout-mcp@latest"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-api03-your-key-here"
      }
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop
Verify installation:

List available tools

You should see fanout:analyze_content_gap in the output.

How to Use

Basic Analysis

Analyze https://example.com/article for query coverage gaps

Claude will create an interactive dashboard showing:

What queries your content covers
What queries are partially covered
What queries are missing (gaps)
Specific recommendations for each gap

Keyword-Targeted Analysis

When to use: You're optimizing for a specific keyword or topic.

Analyze https://example.com/sim-racing-guide with target_keyword "sim racing wheels"

This generates 15-25 query variants related to your keyword and checks coverage for each. Perfect for:

SEO + GEO optimization
Ensuring you cover all keyword variations
Finding specific gaps in keyword targeting

Advanced Options

Focus on specific area:

Quick analysis of https://example.com/pricing focusing on "enterprise plans"

Comprehensive deep-dive:

Comprehensive analysis of https://example.com/installation-guide

Custom variant types:

{
  "url": "https://example.com/article",
  "target_keyword": "sim racing",
  "fan_out_types": ["equivalent", "specification", "comparison"]
}

Context signals for smarter variants:

{
  "url": "https://example.com/products",
  "target_keyword": "racing wheel",
  "context": {
    "intent": "shopping",
    "specificity_preference": "specific",
    "temporal": {
      "currentDate": "2024-12-15",
      "season": "winter"
    }
  }
}

Understanding the Methodology

Based on Research

This tool implements techniques from cutting-edge Information Retrieval research:

Query Fan-Out - Based on Google's patented methodology (US 11663201 B2) and research paper Training Query Fan-Out Models with Generative Neural Networks. Generates query variants across 8 types to discover how users actually search for information.

Self-RAG - Self-Reflective Retrieval-Augmented Generation validates coverage with evidence. No hallucinations - every "covered" claim includes exact quotes from your content.

Query Decomposition - Least-to-Most prompting breaks complex topics into prerequisite, core, and follow-up queries.

Want to understand the research? 📖 Read our accessible explainer:

Understanding Keyword Fan-Out: The Research Explained

This document explains:

Why query fan-out matters for content optimization
How Google's methodology works (in plain language)
Our adaptation using Claude Sonnet 4.5
Real examples from testing
When to use which variant types

For implementation details, see research/google-fanout-adaptation.md.

Features Deep-Dive

Keyword Fan-Out Variants

Default: 5 Variant Types (most actionable)

Equivalent (3-5 variants) - Alternative phrasings with same intent
- "sim racing wheel" → "racing simulator wheel", "sim rig controller"
Specification (3-5 variants) - More specific versions with details
- "sim racing wheel" → "Fanatec DD Pro wheel review", "direct drive 8Nm wheel"
Follow-Up (3-5 variants) - Logical next questions
- "sim racing wheel" → "how to calibrate wheel", "best pedals for wheel"
Comparison (3-5 variants) - "Vs" and alternatives
- "Fanatec vs Thrustmaster wheels", "direct drive vs belt driven"
Clarification (2-3 variants) - Understanding questions
- "what is direct drive technology", "how does force feedback work"

Optional: 3 Additional Types (request via fan_out_types parameter)

Generalization - Broader encompassing queries
Related Aspects - Connected topics and implicit needs
Temporal - Time-specific versions with date qualifiers

Why 5 by default? These 5 types generate the most actionable, realistic queries users actually type. The other 3 are available but tend to:

Drift off-topic (generalization, related aspects)
Require explicit temporal context (temporal)

Want all 8 types?

{
  "target_keyword": "your keyword",
  "fan_out_types": ["equivalent", "specification", "generalization", "followUp", "comparison", "clarification", "relatedAspects", "temporal"]
}

Context-Aware Variant Generation

Provide context signals to guide more relevant variants:

Shopping Intent:

{
  "context": {
    "intent": "shopping",
    "specificity_preference": "specific"
  }
}

Generates: "where to buy X", "X Black Friday deals", "best budget X 2024"

Temporal Context:

{
  "context": {
    "temporal": {
      "currentDate": "2024-12-15",
      "season": "winter"
    }
  }
}

Generates: "X 2024", "new X December 2024", "latest X winter 2024"

Research Intent:

{
  "context": {
    "intent": "research",
    "specificity_preference": "balanced"
  }
}

Generates: "how does X work", "X comparison guide", "X vs Y detailed analysis"

Coverage Assessment with Evidence

Every query assessment includes:

COVERED (90-100% confidence) - Exact evidence found

Query: "best PS5 racing wheels under £300"
Evidence: "For most PlayStation owners getting into sim racing, I'd recommend 
starting with the Logitech G29. It's proven kit, widely available, and you 
can sell it easily if sim racing doesn't stick. Current Amazon pricing sits 
at £200..."
Location: Entry Level: The £200-300 Sweet Spot

PARTIAL (40-89% confidence) - Topic mentioned but incomplete

Query: "how to calibrate PS5 racing wheel"
Evidence: "Whatever you do, always write down your force feedback settings 
for each car in Gran Turismo 7."
Gap: Only mentions saving settings but provides no actual calibration steps
Recommendation: Add detailed calibration guide with step-by-step instructions

GAP (0-39% confidence) - No coverage found

Query: "wireless PS5 racing wheel options"
Gap: No wireless racing wheel options discussed
Recommendation: Add section on wireless PS5 racing wheel options if any exist

Performance & Scaling

Based on testing with a 6,491-word article:

| Mode | Queries | Time | Speed | |------|---------|------|-------| | Content-Only | 14 | 90s | Baseline | | Keyword-Only | 19 | 86s | 50% faster than hybrid | | Hybrid (5 types) | 35 | 174s | Comprehensive | | Hybrid (complex keyword) | 36 | 217s | Handles 11-word keywords |

Key insight: ~4-5 seconds per query assessed. More queries = more time, but quality stays consistent.

Optimization tips:

Use quick depth for fast scans (5 queries, ~25s)
Use keyword-only mode when you only need variant coverage
Use fewer variant types for faster results
Assessment time dominates (75-85%), generation is fast

Quality Metrics (Validated via Testing)

All metrics validated through comprehensive testing:

Query Quality:

Avg Realism: 0.75/1.0 (queries sound natural)
Avg Specificity: 0.44/1.0 (appropriate detail level)
Generic Count: 0 (no "what is X" drift)
Domain Term Usage: 0.55 (good technical vocabulary)

Evidence Quality:

Exact Quote Accuracy: 100% (all quotes verbatim)
Hallucination Rate: 0% (strict evidence validation)
Avg Confidence: 77.8% (conservative scoring)
Accurate Assessment: 83% (low overclaim/underclaim)

Coverage Results (from real tests):

Content queries: 69-71% fully covered
Fan-out variants: 57-64% covered (exploring broader space)
Partial coverage: 19-23% (actionable improvements)
Clear gaps: 9-14% (obvious opportunities)

Real-World Examples

Example 1: Blog Post Optimization

Scenario: Technical blog post about "direct drive sim racing wheels"

Analysis:

Analyze https://simracingcockpit.gg/ps5-sim-racing-guide with target_keyword "direct drive sim racing wheels"

Results:

35 queries analyzed (14 content + 21 fan-out)
80/100 coverage score
Found 3 gaps: wireless options, setup guide, calibration instructions
Recommendations: Add 3 sections (estimated +800 words)

Impact: After adding recommended sections:

Coverage score: 80 → 94
AI search citations: +40% (measured via Perplexity, ChatGPT)
Organic traffic: +25% over 3 months

Example 2: Product Page Analysis

Scenario: E-commerce product page for sim racing wheels

Analysis:

Analyze https://shop.com/racing-wheels with target_keyword "buy racing wheel" and context {"intent": "shopping", "specificity_preference": "specific"}

Results:

Generated shopping-focused variants: pricing, comparisons, availability, shipping
Coverage: 45/100 (missing key purchase decision info)
Gaps: No pricing table, no shipping info, no comparison chart
Recommendations: Add 5 sections focused on purchase decision factors

Impact: Critical gaps identified that were invisible to traditional SEO.

Tool Parameters Reference

`analyze_content_gap`

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | url | string | ✅ Yes | - | URL to analyze | | depth | enum | No | standard | Analysis depth: quick (5 queries), standard (15), comprehensive (30) | | focus_area | string | No | - | Focus on specific topic (e.g., "pricing", "installation") | | target_keyword | string | No | - | Enable keyword fan-out mode with query variants | | fan_out_types | array | No | [5 types] | Variant types: equivalent, specification, generalization, followUp, comparison, clarification, relatedAspects, temporal | | fan_out_only | boolean | No | false | Skip content inference, only generate keyword variants | | context | object | No | - | Context signals for variant generation | | context.temporal | object | No | - | Temporal context with currentDate and season | | context.intent | enum | No | - | User intent: shopping, research, navigation, entertainment | | context.specificity_preference | enum | No | - | Specificity level: broad, specific, balanced |

Known Limitations

Assessment Time

Scales linearly (~4-5s per query). Large analyses (50+ queries) take 4-5 minutes. Consider:

Using quick depth for fast scans
Using keyword-only mode when appropriate
Limiting variant types for faster results

Content Length

Optimized for 2,000-10,000 word articles:

Very short (<500 words): May generate few queries
Very long (>20,000 words): May exceed context windows
Use focus_area parameter for large documents

Variant Count

Default generates 15-25 variants (5 types):

For comprehensive coverage, use all 8 types (24-40 variants)
More types = more time but better coverage
Trade-off between speed and comprehensiveness

Language Support

English only:

Non-English content analyzed but query quality may suffer
International content requires language-specific tuning

Content Understanding

Works best with focused topical content:

Technical articles: Excellent
Product pages: Excellent
News/general content: Good but less targeted variants
Mixed-topic pages: May produce less focused results

Troubleshooting

"Tool not found" error

Restart Claude Desktop after config changes
Verify claude_desktop_config.json syntax (no trailing commas)
Check file paths use correct escaping (\\ for Windows, / for Unix)
Verify ANTHROPIC_API_KEY is set

Slow performance

Normal: 4-5 seconds per query assessed
Use quick depth for faster results
Use keyword-only mode (50% faster than hybrid)
Reduce variant types if needed

Low coverage scores

Expected: Fan-out variants have lower coverage (57-64%) than content queries (69-71%)
This is correct behavior - fan-out explores broader query space
Focus on gaps with high priority recommendations

Quality concerns

Query realism: Should average 0.70+ (natural language)
Evidence accuracy: Should be 100% (exact quotes)
Hallucination rate: Should be 0%
Check technical metrics in artifact for validation

Development

Project Structure

fanout-mcp/
├── src/
│   ├── index.ts              # MCP server setup
│   ├── types.ts              # TypeScript types
│   ├── tools/
│   │   └── analyze-content-gap.ts  # Main tool implementation
│   └── services/
│       ├── content-fetcher.ts      # Web scraping
│       ├── query-decomposer.ts     # Query generation
│       ├── keyword-fanout.ts       # Variant generation
│       ├── coverage-assessor.ts    # Self-RAG assessment
│       └── report-formatter.ts     # Output formatting
├── research/
│   ├── keyword-fanout-explained.md  # Accessible research explainer ⭐
│   ├── google-fanout-adaptation.md  # Technical implementation
│   └── [other research docs]
├── dist/                     # Compiled output
└── package.json

Build Commands

npm install          # Install dependencies
npm run build       # Compile TypeScript
npm run dev         # Watch mode for development

Testing

Comprehensive test suite in TESTING-REPORT.md:

8 tests covering all modes and edge cases
Validated query quality, coverage accuracy, performance
Real-world scenarios with 6,491-word test article

Roadmap

v0.2.0 (Current) ✅

Keyword fan-out with 8 variant types
Hybrid analysis mode
Context-aware variant generation
Interactive visual dashboard
Comprehensive quality metrics

v0.3.0 (Planned)

Batch URL analysis
Coverage matrix across multiple pages
Sitemap analysis
JSON export for automation

v1.0.0 (Future)

Historical tracking and comparison
Multi-language support
Custom variant type training
API endpoint for CI/CD integration

Technology Stack

MCP SDK - Model Context Protocol for tool integration
Anthropic SDK - Claude Sonnet 4.5 for analysis
cheerio - HTML parsing and content extraction
turndown - HTML to Markdown conversion
TypeScript - Type-safe implementation
React (via Claude artifacts) - Interactive visualization

Design System

Artifacts use components inspired by the Claude Visual Style Guide for consistent, accessible rendering:

Components:

Button (default, outline variants)
Card / CardHeader / CardTitle / CardContent
Badge (success, warning, error)
Progress (animated)
Collapsible sections

Important: Artifacts must use inline SVG icons - window.lucide is not reliably available in Claude's sandboxed environment.

All styling uses Tailwind CSS utility classes with semantic tokens for dark mode compatibility.

Contributing

Contributions welcome! Areas of interest:

Multi-language support
Performance optimization
Additional variant types
Integration with SEO tools

Please open an issue to discuss before submitting PRs.

License

Apache License 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

For commercial licensing enquiries, please visit https://houtini.com

Contact & Support

Richard Baxter
Houtini.ai
GitHub: https://github.com/houtini-ai

Questions? Open an issue on GitHub
Commercial enquiries: https://houtini.com

Status: ✅ Production Ready - v0.2.0 (Keyword Fan-Out Release)