idea-reality-mcp-validation

# idea-reality-mcp-validation > Skill by [ara.so](https://ara.so) — MCP Skills collection. idea-reality-mcp is an MCP server that validates project ideas before you write code. It scans GitHub, Hacker News, npm, PyPI, Product Hunt, and Stack Overflow to return a 0–100 reality score, trend detection, top competitors, and pivot suggestions. ## Installation ### Quick Start (uvx) ```bash uvx idea-reality-mcp ``` ### Add to Claude Code ```bash claude mcp add idea-reality -- uvx idea-reality-mcp ``` ### Add to Claude Desktop / Cursor Edit your MCP config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Cursor**: `.cursor/mcp.json` ```json { "mcpServers": { "idea-reality": { "command": "uvx", "args": ["idea-reality-mcp"] } } } ``` ### Smithery (Remote) ```bash npx -y @smithery/cli install idea-reality-mcp --client claude ``` ## Setup & Configuration ### First-Time Setup ```bash idea-reality setup ``` Interactive wizard that: 1. Shows terms acceptance 2. Detects your platform (Claude Desktop, Cursor, etc.) 3. Generates config snippet 4. Runs health check ### Platform-Specific Config ```bash idea-reality config # interactive menu idea-reality config claude_code # auto-installs idea-reality config cursor # prints Cursor config idea-reality config raw_json # generic MCP JSON ``` ### Health Check ```bash idea-reality doctor # core checks (~2s) idea-reality doctor --full # + API validation, all 6 sources ``` ### Optional Environment Variables ```bash export GITHUB_TOKEN=ghp_... # Higher GitHub API rate limits export PRODUCTHUNT_TOKEN=... # Enable Product Hunt (deep mode) ``` ## Core MCP Tool: `idea_check` ### Tool Schema **Parameters:** - `idea_text` (string, required): Natural-language description of your idea - `depth` (string, optional): `"quick"` (default) or `"deep"` **Modes:** - `quick`: GitHub + Hacker News (< 3 seconds) - `deep`: All 6 sources (GitHub, HN, npm, PyPI, Product Hunt, Stack Overflow) ### Using from AI Agent When a user says *"check if this idea already exists"*, use the `idea_check` tool: ```json { "tool": "idea_check", "arguments": { "idea_text": "a CLI tool that converts Figma designs to React components", "depth": "deep" } } ``` ### Response Structure ```json { "reality_signal": 72, "duplicate_likelihood": "high", "trend": "accelerating", "sub_scores": { "market_momentum": 73 }, "evidence": [ { "source": "github", "type": "repo_count", "query": "figma react converter CLI", "count": 342 }, { "source": "github", "type": "max_stars", "query": "figma react converter", "count": 15000 }, { "source": "hackernews", "type": "mention_count", "query": "figma react", "count": 18 }, { "source": "npm", "type": "package_count", "query": "figma-react", "count": 56 }, { "source": "pypi", "type": "package_count", "query": "figma-react", "count": 23 }, { "source": "producthunt", "type": "product_count", "query": "figma react", "count": 8 }, { "source": "stackoverflow", "type": "question_count", "query": "figma react converter", "count": 120 } ], "top_similars": [ { "name": "figma-to-react/figma-to-react", "url": "https://github.com/figma-to-react/figma-to-react", "stars": 15000, "description": "Convert Figma designs to React components" } ], "pivot_hints": [ "High competition. Consider a niche differentiator like supporting design tokens or specific component libraries.", "The leading project may have gaps in TypeScript support or accessibility features." ] } ``` ## REST API (No MCP Required) ### Python Client ```python import httpx response = httpx.post( "https://idea-reality-mcp.onrender.com/api/check", json={ "idea_text": "AI code review tool", "depth": "deep" }, timeout=30.0 ) result = response.json() print(f"Reality Score: {result['reality_signal']}/100") print(f"Trend: {result['trend']}") print(f"Top Competitor: {result['top_similars'][0]['name']} ({result['top_similars'][0]['stars']} ⭐)") ``` ### cURL ```bash curl -X POST https://idea-reality-mcp.onrender.com/api/check \ -H "Content-Type: application/json" \ -d '{ "idea_text": "a markdown-based static site generator with live reload", "depth": "quick" }' ``` ## Common Patterns ### Pre-Build Validation Before starting a new project: ```python # User says: "I want to build a CLI tool for GitHub issue management" # Agent calls: { "tool": "idea_check", "arguments": { "idea_text": "CLI tool for GitHub issue management with labels and milestones", "depth": "deep" } } # If reality_signal > 80: # → Suggest niche differentiation or pivot # If reality_signal 40-80: # → Validate unique features, check top_similars # If reality_signal < 40: # → Green light, low competition ``` ### Feature Validation Check if a feature is already widely implemented: ```json { "tool": "idea_check", "arguments": { "idea_text": "add real-time collaborative editing to my markdown editor", "depth": "quick" } } ``` ### Market Trend Analysis Understand if a space is growing or declining: ```json { "tool": "idea_check", "arguments": { "idea_text": "browser automation library using Chrome DevTools Protocol", "depth": "deep" } } ``` Check the `trend` field: - `"accelerating"` → Growing market, act fast - `"stable"` → Mature market, differentiation critical - `"declining"` → Consider pivoting ### Auto-Trigger in Agent Instructions Add to `.cursorrules`, `CLAUDE.md`, or `.github/copilot-instructions.md`: ```markdown When starting a new project, use the idea_check MCP tool to check if similar projects already exist. ``` ## CI/CD Integration ### GitHub Action for Pull Requests Create `.github/workflows/idea-check.yml`: ```yaml name: Idea Reality Check on: issues: types: [opened] jobs: check: if: contains(github.event.issue.labels.*.name, 'proposal') runs-on: ubuntu-latest steps: - uses: mnemox-ai/idea-check-action@v1 with: idea: ${{ github.event.issue.title }} github-token: ${{ secrets.GITHUB_TOKEN }} ``` This auto-validates feature proposals labeled `proposal`. ## Interpreting Results ### Reality Signal (0–100) - **0–30**: Low competition, potentially novel idea - **31–60**: Moderate competition, validate unique angle - **61–85**: High competition, niche differentiation required - **86–100**: Saturated market, strong pivot recommended ### Duplicate Likelihood - `low`: Few similar projects found - `medium`: Several similar projects exist - `high`: Many similar projects, established category - `very_high`: Extremely crowded space ### Market Momentum (sub_scores) Measures recent growth in the space: - **< 40**: Declining interest - **40–60**: Stable - **> 60**: Growing/accelerating ## Scoring Weights ### Quick Mode | Source | Weight | |--------|--------| | GitHub repos | 60% | | GitHub stars | 20% | | Hacker News | 20% | ### Deep Mode | Source | Weight | |--------|--------| | GitHub repos | 22% | | GitHub stars | 9% | | Hacker News | 14% | | npm | 18% | | PyPI | 13% | | Product Hunt | 14% | | Stack Overflow | 10% | If a source fails, weights redistribute automatically. ## Troubleshooting ### "MCP server not found" **Cursor/Claude Desktop:** 1. Restart the application completely 2. Check config file location and syntax 3. Run `idea-reality doctor` **Claude Code:** ```bash claude mcp list # verify installation claude mcp remove idea-reality claude mcp add idea-reality -- uvx idea-reality-mcp ``` ### "GitHub API rate limit exceeded" Set a GitHub token: ```bash export GITHUB_TOKEN=ghp_your_token_here idea-reality doctor --full # verify ``` Generate token at: https://github.com/settings/tokens (no scopes needed for public data) ### "Product Hunt data missing (deep mode)" Product Hunt requires authentication: ```bash export PRODUCTHUNT_TOKEN=your_token_here ``` Or use `depth: "quick"` which skips Product Hunt. ### "Irrelevant results" The tool uses 3-stage keyword extraction. If results are off: 1. Be more specific in `idea_text`: - ❌ "productivity app" - ✅ "CLI time-tracking tool for developers with Git integration" 2. Report the issue: https://github.com/mnemox-ai/idea-reality-mcp/issues/new?template=inaccurate-result.yml ### "Tool call timeout" Deep mode can take 10–15 seconds. Increase timeout: ```python # Python httpx client httpx.post(..., timeout=30.0) ``` Or use `depth: "quick"` (< 3 seconds). ## Example Workflows ### 1. Pre-Project Kickoff ```markdown User: "I want to build a Rust-based SQL formatter with auto-fix" Agent: 1. Call idea_check with depth="deep" 2. If reality_signal > 70: - Show top competitors (e.g. sqlformat, prettier-plugin-sql) - Suggest niches from pivot_hints (e.g. Rust performance angle) 3. If reality_signal < 50: - Proceed with project scaffolding ``` ### 2. Feature Gap Analysis ```markdown User: "Should I add Vim keybindings to my editor?" Agent: 1. Call idea_check: "text editor with vim keybindings" 2. Check evidence[].count for npm/PyPI packages 3. High count → already solved, suggest integration 4. Low count → potential differentiator ``` ### 3. Market Validation ```markdown User: "Is AI code review still worth building?" Agent: 1. Call idea_check with depth="deep" 2. Check trend field 3. If "accelerating" → market growing, move fast 4. If "declining" → suggest pivot to specific niche ``` ## Advanced Usage ### Batch Validation ```python import httpx ideas = [ "AI-powered commit message generator", "Real-time Markdown collaboration", "GitHub issue templates manager" ] async with httpx.AsyncClient() as client: tasks = [ client.post( "https://idea-reality-mcp.onrender.com/api/check", json={"idea_text": idea, "depth": "quick"}