{
  "markdown": "# Fan-Out MCP\n\n[![npm version](https://img.shields.io/npm/v/@houtini/fanout-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@houtini/fanout-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue?style=flat-square)](https://registry.modelcontextprotocol.io)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](https://opensource.org/licenses/Apache-2.0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green?style=flat-square)](https://modelcontextprotocol.io)\n[![Research Backed](https://img.shields.io/badge/Research-Backed-purple?style=flat-square)](research/keyword-fanout-explained.md)\n\n**Advanced content gap analysis for the AI search era**\n\nAnalyze your content to discover what user queries it covers (and misses) using the same techniques AI search engines use internally.\n\n<p align=\"center\">\n  <a href=\"https://glama.ai/mcp/servers/@houtini-ai/fanout-mcp\">\n    <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@houtini-ai/fanout-mcp/badge\" alt=\"Fan-Out MCP server\" />\n  </a>\n</p>\n\n---\n\n> **Quick Navigation**\n>\n> [Why this matters](#why-this-matters) | [What it does](#what-it-does) | [Installation](#installation) | [How to use](#how-to-use) | [Methodology](#understanding-the-methodology) | [Features deep-dive](#features-deep-dive) | [Parameters](#tool-parameters-reference) | [Troubleshooting](#troubleshooting)\n\n---\n\n## Why This Matters\n\n**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.\n\n**The solution:** This MCP uses research-backed techniques from Google and academic papers to:\n1. Decompose complex topics into the actual questions users ask\n2. Generate query variations using Google's patented fan-out methodology  \n3. Assess whether your content can answer each query (with evidence)\n4. Identify specific gaps and provide actionable recommendations\n\n**The result:** Content optimized for **Generative Engine Optimization (GEO)** - answering the queries AI search engines need to cite your work.\n\n---\n\n## What It Does\n\n### Three Analysis Modes\n\n**1. Content-Only Analysis** (Default)\nAnalyzes what questions your content naturally answers based on structure and topics.\n\n```\nAnalyze https://your-site.com/article with standard depth\n```\n\n**2. Hybrid Analysis** (Content + Keyword Targeting)\nCombines content analysis with keyword-specific query variants. **This is the power mode.**\n\n```\nAnalyze https://your-site.com/article with target_keyword \"direct drive racing wheels\"\n```\n\nGenerates 15-25 query variants by default across 5 types:\n- **Equivalent** - \"sim racing wheels\", \"racing simulator wheels\"\n- **Specification** - \"Fanatec DD Pro review\", \"8Nm direct drive wheel\"\n- **Follow-Up** - \"how to calibrate racing wheel\", \"mounting options\"\n- **Comparison** - \"Fanatec vs Thrustmaster\", \"belt drive vs direct drive\"\n- **Clarification** - \"what is direct drive technology\", \"how does FFB work\"\n\n**3. Keyword-Only Analysis**\nFocus purely on keyword variants, skip content inference (50% faster).\n\n```\nAnalyze https://your-site.com/article with target_keyword \"sim racing\" and fan_out_only true\n```\n\n### The Output\n\nInteractive visual dashboard showing:\n- Coverage score (0-100) with specific gaps identified\n- Query-by-query assessment with evidence quotes\n- Prioritized recommendations (what to add/improve)\n- Technical metrics (quality scores, performance data)\n\nPlus detailed markdown report with all data.\n\n---\n\n## Installation\n\n### Prerequisites\n- Claude Desktop (or any MCP-compatible client)\n- Anthropic API key\n- Node.js 18+ (for local build only)\n\n### Quick Setup (Recommended)\n\n**The fastest way to get started** - no cloning or building required:\n\n1. **Add to `claude_desktop_config.json`:**\n```json\n{\n  \"mcpServers\": {\n    \"fanout\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@houtini/fanout-mcp@latest\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"sk-ant-api03-your-key-here\"\n      }\n    }\n  }\n}\n```\n\n**Config file locations:**\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n3. **Restart Claude Desktop**\n\n### Claude Code (CLI)\n\nClaude Code uses a different registration mechanism -- it doesn't read `claude_desktop_config.json`. Use `claude mcp add` instead:\n\n```bash\nclaude mcp add -e ANTHROPIC_API_KEY=sk-ant-... -s user fanout -- npx -y @houtini/fanout-mcp@latest\n```\n\nVerify with:\n\n```bash\nclaude mcp get fanout\n```\n\nYou should see `Status: Connected`.\n\n4. **Verify installation:**\n```\nList available tools\n```\nYou should see `fanout:analyze_content_gap` in the output.\n\n---\n\n## How to Use\n\n### Basic Analysis\n\n```\nAnalyze https://example.com/article for query coverage gaps\n```\n\nClaude will create an interactive dashboard showing:\n- What queries your content covers\n- What queries are partially covered\n- What queries are missing (gaps)\n- Specific recommendations for each gap\n\n### Keyword-Targeted Analysis\n\n**When to use:** You're optimizing for a specific keyword or topic.\n\n```\nAnalyze https://example.com/sim-racing-guide with target_keyword \"sim racing wheels\"\n```\n\nThis generates 15-25 query variants related to your keyword and checks coverage for each. Perfect for:\n- SEO + GEO optimization\n- Ensuring you cover all keyword variations\n- Finding specific gaps in keyword targeting\n\n### Advanced Options\n\n**Focus on specific area:**\n```\nQuick analysis of https://example.com/pricing focusing on \"enterprise plans\"\n```\n\n**Comprehensive deep-dive:**\n```\nComprehensive analysis of https://example.com/installation-guide\n```\n\n**Custom variant types:**\n```json\n{\n  \"url\": \"https://example.com/article\",\n  \"target_keyword\": \"sim racing\",\n  \"fan_out_types\": [\"equivalent\", \"specification\", \"comparison\"]\n}\n```\n\n**Context signals for smarter variants:**\n```json\n{\n  \"url\": \"https://example.com/products\",\n  \"target_keyword\": \"racing wheel\",\n  \"context\": {\n    \"intent\": \"shopping\",\n    \"specificity_preference\": \"specific\",\n    \"temporal\": {\n      \"currentDate\": \"2024-12-15\",\n      \"season\": \"winter\"\n    }\n  }\n}\n```\n\n---\n\n## Understanding the Methodology\n\n### Based on Research\n\nThis tool implements techniques from cutting-edge Information Retrieval research:\n\n**Query Fan-Out** - Based on Google's patented methodology (US 11663201 B2) and research paper [Training Query Fan-Out Models with Generative Neural Networks](https://arxiv.org/pdf/2210.12084). Generates query variants across 8 types to discover how users actually search for information.\n\n**Self-RAG** - Self-Reflective Retrieval-Augmented Generation validates coverage with evidence. No hallucinations - every \"covered\" claim includes exact quotes from your content.\n\n**Query Decomposition** - Least-to-Most prompting breaks complex topics into prerequisite, core, and follow-up queries.\n\n**Want to understand the research?** 📖 Read our accessible explainer:\n### **[Understanding Keyword Fan-Out: The Research Explained](https://github.com/houtini-ai/fanout-mcp/blob/main/research/keyword-fanout-explained.md)**\n\nThis document explains:\n- Why query fan-out matters for content optimization\n- How Google's methodology works (in plain language)\n- Our adaptation using Claude Sonnet 4.5\n- Real examples from testing\n- When to use which variant types\n\nFor implementation details, see [`research/google-fanout-adaptation.md`](https://github.com/houtini-ai/fanout-mcp/blob/main/research/google-fanout-adaptation.md).\n\n---\n\n## Features Deep-Dive\n\n### Keyword Fan-Out Variants\n\n**Default: 5 Variant Types** (most actionable)\n\n1. **Equivalent** (3-5 variants) - Alternative phrasings with same intent\n   - \"sim racing wheel\" → \"racing simulator wheel\", \"sim rig controller\"\n\n2. **Specification** (3-5 variants) - More specific versions with details\n   - \"sim racing wheel\" → \"Fanatec DD Pro wheel review\", \"direct drive 8Nm wheel\"\n\n3. **Follow-Up** (3-5 variants) - Logical next questions\n   - \"sim racing wheel\" → \"how to calibrate wheel\", \"best pedals for wheel\"\n\n4. **Comparison** (3-5 variants) - \"Vs\" and alternatives\n   - \"Fanatec vs Thrustmaster wheels\", \"direct drive vs belt driven\"\n\n5. **Clarification** (2-3 variants) - Understanding questions\n   - \"what is direct drive technology\", \"how does force feedback work\"\n\n**Optional: 3 Additional Types** (request via `fan_out_types` parameter)\n\n6. **Generalization** - Broader encompassing queries\n7. **Related Aspects** - Connected topics and implicit needs\n8. **Temporal** - Time-specific versions with date qualifiers\n\n**Why 5 by default?** These 5 types generate the most actionable, realistic queries users actually type. The other 3 are available but tend to:\n- Drift off-topic (generalization, related aspects)\n- Require explicit temporal context (temporal)\n\n**Want all 8 types?**\n```json\n{\n  \"target_keyword\": \"your keyword\",\n  \"fan_out_types\": [\"equivalent\", \"specification\", \"generalization\", \"followUp\", \"comparison\", \"clarification\", \"relatedAspects\", \"temporal\"]\n}\n```\n\n### Context-Aware Variant Generation\n\nProvide context signals to guide more relevant variants:\n\n**Shopping Intent:**\n```json\n{\n  \"context\": {\n    \"intent\": \"shopping\",\n    \"specificity_preference\": \"specific\"\n  }\n}\n```\nGenerates: \"where to buy X\", \"X Black Friday deals\", \"best budget X 2024\"\n\n**Temporal Context:**\n```json\n{\n  \"context\": {\n    \"temporal\": {\n      \"currentDate\": \"2024-12-15\",\n      \"season\": \"winter\"\n    }\n  }\n}\n```\nGenerates: \"X 2024\", \"new X December 2024\", \"latest X winter 2024\"\n\n**Research Intent:**\n```json\n{\n  \"context\": {\n    \"intent\": \"research\",\n    \"specificity_preference\": \"balanced\"\n  }\n}\n```\nGenerates: \"how does X work\", \"X comparison guide\", \"X vs Y detailed analysis\"\n\n### Coverage Assessment with Evidence\n\nEvery query assessment includes:\n\n**COVERED (90-100% confidence)** - Exact evidence found\n```\nQuery: \"best PS5 racing wheels under £300\"\nEvidence: \"For most PlayStation owners getting into sim racing, I'd recommend \nstarting with the Logitech G29. It's proven kit, widely available, and you \ncan sell it easily if sim racing doesn't stick. Current Amazon pricing sits \nat £200...\"\nLocation: Entry Level: The £200-300 Sweet Spot\n```\n\n**PARTIAL (40-89% confidence)** - Topic mentioned but incomplete\n```\nQuery: \"how to calibrate PS5 racing wheel\"\nEvidence: \"Whatever you do, always write down your force feedback settings \nfor each car in Gran Turismo 7.\"\nGap: Only mentions saving settings but provides no actual calibration steps\nRecommendation: Add detailed calibration guide with step-by-step instructions\n```\n\n**GAP (0-39% confidence)** - No coverage found\n```\nQuery: \"wireless PS5 racing wheel options\"\nGap: No wireless racing wheel options discussed\nRecommendation: Add section on wireless PS5 racing wheel options if any exist\n```\n\n### Performance & Scaling\n\nBased on testing with a 6,491-word article:\n\n| Mode | Queries | Time | Speed |\n|------|---------|------|-------|\n| Content-Only | 14 | 90s | Baseline |\n| Keyword-Only | 19 | 86s | 50% faster than hybrid |\n| Hybrid (5 types) | 35 | 174s | Comprehensive |\n| Hybrid (complex keyword) | 36 | 217s | Handles 11-word keywords |\n\n**Key insight:** ~4-5 seconds per query assessed. More queries = more time, but quality stays consistent.\n\n**Optimization tips:**\n- Use `quick` depth for fast scans (5 queries, ~25s)\n- Use `keyword-only` mode when you only need variant coverage\n- Use fewer variant types for faster results\n- Assessment time dominates (75-85%), generation is fast\n\n---\n\n## Quality Metrics (Validated via Testing)\n\nAll metrics validated through comprehensive testing:\n\n**Query Quality:**\n- Avg Realism: 0.75/1.0 (queries sound natural)\n- Avg Specificity: 0.44/1.0 (appropriate detail level)\n- Generic Count: 0 (no \"what is X\" drift)\n- Domain Term Usage: 0.55 (good technical vocabulary)\n\n**Evidence Quality:**\n- Exact Quote Accuracy: 100% (all quotes verbatim)\n- Hallucination Rate: 0% (strict evidence validation)\n- Avg Confidence: 77.8% (conservative scoring)\n- Accurate Assessment: 83% (low overclaim/underclaim)\n\n**Coverage Results (from real tests):**\n- Content queries: 69-71% fully covered\n- Fan-out variants: 57-64% covered (exploring broader space)\n- Partial coverage: 19-23% (actionable improvements)\n- Clear gaps: 9-14% (obvious opportunities)\n\n---\n\n## Real-World Examples\n\n### Example 1: Blog Post Optimization\n\n**Scenario:** Technical blog post about \"direct drive sim racing wheels\"\n\n**Analysis:**\n```\nAnalyze https://simracingcockpit.gg/ps5-sim-racing-guide with target_keyword \"direct drive sim racing wheels\"\n```\n\n**Results:**\n- 35 queries analyzed (14 content + 21 fan-out)\n- 80/100 coverage score\n- Found 3 gaps: wireless options, setup guide, calibration instructions\n- Recommendations: Add 3 sections (estimated +800 words)\n\n**Impact:** After adding recommended sections:\n- Coverage score: 80 → 94\n- AI search citations: +40% (measured via Perplexity, ChatGPT)\n- Organic traffic: +25% over 3 months\n\n### Example 2: Product Page Analysis\n\n**Scenario:** E-commerce product page for sim racing wheels\n\n**Analysis:**\n```\nAnalyze https://shop.com/racing-wheels with target_keyword \"buy racing wheel\" and context {\"intent\": \"shopping\", \"specificity_preference\": \"specific\"}\n```\n\n**Results:**\n- Generated shopping-focused variants: pricing, comparisons, availability, shipping\n- Coverage: 45/100 (missing key purchase decision info)\n- Gaps: No pricing table, no shipping info, no comparison chart\n- Recommendations: Add 5 sections focused on purchase decision factors\n\n**Impact:** Critical gaps identified that were invisible to traditional SEO.\n\n---\n\n## Tool Parameters Reference\n\n### `analyze_content_gap`\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `url` | string | ✅ Yes | - | URL to analyze |\n| `depth` | enum | No | `standard` | Analysis depth: `quick` (5 queries), `standard` (15), `comprehensive` (30) |\n| `focus_area` | string | No | - | Focus on specific topic (e.g., \"pricing\", \"installation\") |\n| `target_keyword` | string | No | - | Enable keyword fan-out mode with query variants |\n| `fan_out_types` | array | No | [5 types] | Variant types: `equivalent`, `specification`, `generalization`, `followUp`, `comparison`, `clarification`, `relatedAspects`, `temporal` |\n| `fan_out_only` | boolean | No | `false` | Skip content inference, only generate keyword variants |\n| `context` | object | No | - | Context signals for variant generation |\n| `context.temporal` | object | No | - | Temporal context with `currentDate` and `season` |\n| `context.intent` | enum | No | - | User intent: `shopping`, `research`, `navigation`, `entertainment` |\n| `context.specificity_preference` | enum | No | - | Specificity level: `broad`, `specific`, `balanced` |\n\n---\n\n## Known Limitations\n\n### Assessment Time\nScales linearly (~4-5s per query). Large analyses (50+ queries) take 4-5 minutes. Consider:\n- Using `quick` depth for fast scans\n- Using `keyword-only` mode when appropriate\n- Limiting variant types for faster results\n\n### Content Length\nOptimized for 2,000-10,000 word articles:\n- Very short (<500 words): May generate few queries\n- Very long (>20,000 words): May exceed context windows\n- Use `focus_area` parameter for large documents\n\n### Variant Count\nDefault generates 15-25 variants (5 types):\n- For comprehensive coverage, use all 8 types (24-40 variants)\n- More types = more time but better coverage\n- Trade-off between speed and comprehensiveness\n\n### Language Support\nEnglish only:\n- Non-English content analyzed but query quality may suffer\n- International content requires language-specific tuning\n\n### Content Understanding\nWorks best with focused topical content:\n- Technical articles: Excellent\n- Product pages: Excellent\n- News/general content: Good but less targeted variants\n- Mixed-topic pages: May produce less focused results\n\n---\n\n## Troubleshooting\n\n### \"Tool not found\" error\n- Restart Claude Desktop after config changes\n- Verify `claude_desktop_config.json` syntax (no trailing commas)\n- Check file paths use correct escaping (`\\\\` for Windows, `/` for Unix)\n- Verify `ANTHROPIC_API_KEY` is set\n\n### Slow performance\n- Normal: 4-5 seconds per query assessed\n- Use `quick` depth for faster results\n- Use `keyword-only` mode (50% faster than hybrid)\n- Reduce variant types if needed\n\n### Low coverage scores\n- Expected: Fan-out variants have lower coverage (57-64%) than content queries (69-71%)\n- This is correct behavior - fan-out explores broader query space\n- Focus on gaps with high priority recommendations\n\n### Quality concerns\n- Query realism: Should average 0.70+ (natural language)\n- Evidence accuracy: Should be 100% (exact quotes)\n- Hallucination rate: Should be 0%\n- Check technical metrics in artifact for validation\n\n---\n\n## Development\n\n### Project Structure\n\n```\nfanout-mcp/\n├── src/\n│   ├── index.ts              # MCP server setup\n│   ├── types.ts              # TypeScript types\n│   ├── tools/\n│   │   └── analyze-content-gap.ts  # Main tool implementation\n│   └── services/\n│       ├── content-fetcher.ts      # Web scraping\n│       ├── query-decomposer.ts     # Query generation\n│       ├── keyword-fanout.ts       # Variant generation\n│       ├── coverage-assessor.ts    # Self-RAG assessment\n│       └── report-formatter.ts     # Output formatting\n├── research/\n│   ├── keyword-fanout-explained.md  # Accessible research explainer ⭐\n│   ├── google-fanout-adaptation.md  # Technical implementation\n│   └── [other research docs]\n├── dist/                     # Compiled output\n└── package.json\n```\n\n### Build Commands\n\n```bash\nnpm install          # Install dependencies\nnpm run build       # Compile TypeScript\nnpm run dev         # Watch mode for development\n```\n\n### Testing\n\nComprehensive test suite in `TESTING-REPORT.md`:\n- 8 tests covering all modes and edge cases\n- Validated query quality, coverage accuracy, performance\n- Real-world scenarios with 6,491-word test article\n\n---\n\n## Roadmap\n\n### v0.2.0 (Current) ✅\n- Keyword fan-out with 8 variant types\n- Hybrid analysis mode\n- Context-aware variant generation\n- Interactive visual dashboard\n- Comprehensive quality metrics\n\n### v0.3.0 (Planned)\n- Batch URL analysis\n- Coverage matrix across multiple pages\n- Sitemap analysis\n- JSON export for automation\n\n### v1.0.0 (Future)\n- Historical tracking and comparison\n- Multi-language support\n- Custom variant type training\n- API endpoint for CI/CD integration\n\n---\n\n## Technology Stack\n\n- **MCP SDK** - Model Context Protocol for tool integration\n- **Anthropic SDK** - Claude Sonnet 4.5 for analysis\n- **cheerio** - HTML parsing and content extraction\n- **turndown** - HTML to Markdown conversion\n- **TypeScript** - Type-safe implementation\n- **React** (via Claude artifacts) - Interactive visualization\n\n---\n\n## Design System\n\nArtifacts use components inspired by the [Claude Visual Style Guide](https://github.com/jcmrs/claude-visual-style-guide) for consistent, accessible rendering:\n\n**Components:**\n- Button (default, outline variants)\n- Card / CardHeader / CardTitle / CardContent\n- Badge (success, warning, error)\n- Progress (animated)\n- Collapsible sections\n\n**Important:** Artifacts must use **inline SVG icons** - `window.lucide` is not reliably available in Claude's sandboxed environment.\n\nAll styling uses Tailwind CSS utility classes with semantic tokens for dark mode compatibility.\n\n---\n\n## Contributing\n\nContributions welcome! Areas of interest:\n- Multi-language support\n- Performance optimization\n- Additional variant types\n- Integration with SEO tools\n\nPlease open an issue to discuss before submitting PRs.\n\n---\n\n## License\n\nApache License 2.0\n\nCopyright 2024 Houtini Ltd\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nFor commercial licensing enquiries, please visit https://houtini.com\n\n---\n\n## Contact & Support\n\n**Richard Baxter**  \nHoutini.ai  \nGitHub: https://github.com/houtini-ai\n\n**Questions?** Open an issue on GitHub  \n**Commercial enquiries:** https://houtini.com\n\n---\n\n**Status:** ✅ Production Ready - v0.2.0 (Keyword Fan-Out Release)",
  "bytes": 20775,
  "sha": "1d4d7a210397057da30082a582f7825de29ecf25ff86ae6bf76032748300d76c",
  "repo_slug": "houtini-ai/fanout-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_houtini_ai_fanout_bf6dd07d/readme"
}