mnemox-ai/idea-reality-mcp: Auto Reality Checks for AI Coding Agents

mnemox-ai/idea-reality-mcp: Auto Reality Checks for AI Coding Agents

Every developer has been there: you dream up what feels like a novel tool, spend weeks building it, then stumble across a well-established open-source project that does the same thing—with 10,000 stars and a thriving community. The problem isn't lack of talent; it's lack of visibility into what's already out there. Your AI coding agent won't Google before it generates files. It won't check npm or PyPI. It just builds.

mnemox-ai/idea-reality-mcp closes that gap. It's an MCP (Model Context Protocol) server that automatically scans six major databases—GitHub, Hacker News, npm, PyPI, Product Hunt, and Stack Overflow—to check if your startup idea already exists. It returns a 0–100 reality score with evidence, trend detection, and pivot suggestions. Your agent decides: build, pivot, or kill the idea before a single line of code is written.

What is mnemox-ai/idea-reality-mcp?

mnemox-ai/idea-reality-mcp is an open-source MCP server built by Mnemox AI and released under the MIT License. With 758 GitHub stars, 84 forks, and active development (last commit July 8, 2026), it has gained meaningful traction among developers who want their AI agents to make informed decisions about what to build.

The tool sits in the emerging category of MCP infrastructure for AI agents—servers that extend what Claude, Cursor, and other AI coding tools can do by giving them structured access to external data. Rather than treating your agent as a blind code generator, mnemox-ai/idea-reality-mcp equips it with competitive intelligence.

The server is written in Python^{↗ Bright Coding Blog} and distributed via PyPI and uvx for zero-config installation. It also offers a hosted REST API on Render for usage without MCP setup. The project includes 277 passing tests, interactive CLI onboarding (idea-reality setup, idea-reality config, idea-reality doctor), and a companion GitHub Action for CI-based idea validation.

What makes it relevant now: the explosion of AI coding agents (Claude Code, Cursor, Windsurf, Cline) has created a new problem—agents that build enthusiastically but research poorly. mnemox-ai/idea-reality-mcp is purpose-built for this exact workflow gap.

Key Features

Six-source parallel scanning. The idea_check tool queries GitHub repositories and stars, Hacker News discussions, npm packages, PyPI packages, Product Hunt launches, and Stack Overflow questions simultaneously. Results aggregate into a single structured response.

0–100 reality signal with sub-scores. The primary output is a reality_signal score (0 = likely novel, 100 = saturated market). Sub-scores include market_momentum (0–100) and duplicate_likelihood (low/medium/high). This gives your agent quantitative grounds for decisions.

Trend detection. The tool classifies market direction as accelerating, stable, or declining based on temporal signals—like what percentage of GitHub repos were created in the last six months. An "accelerating" trend with high competition might mean "move fast on a niche," while "declining" might mean "opportunity for disruption."

AI-generated pivot hints. When competition is high, the tool suggests specific differentiation strategies based on gaps it detects in top competitors.

Two depth modes. quick (default, <3 seconds, GitHub + HN only) for fast sanity checks. deep (all six sources) for full competitive scans before major investments.

Multi-platform MCP integration. Native support for Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Smithery (remote, no local install), and Docker^{↗ Bright Coding Blog}. Auto-detection during setup prints the exact config JSON for your platform.

REST API fallback. The hosted endpoint at idea-reality-mcp.onrender.com requires no MCP client—useful for scripts, dashboards, or non-MCP workflows.

CI integration via GitHub Action. The companion idea-check-action validates feature proposals from labeled issues automatically.

Use Cases

Pre-build validation for solo developers. You're about to spend evenings and weekends on a "GitHub README generator with AI." Before you start, your agent runs idea_check in quick mode, discovers 200+ existing repos with the top competitor at 15K stars, and suggests pivoting to "README generators specifically for ML model cards." You save weeks.

Startup idea screening for technical founders. Your team debates building "an AI code review tool." A deep scan reveals 847 GitHub repos (45% created in last 6 months), 56 npm packages, 254 HN discussions trending up, and reviewdog as the 9,094-star incumbent. The reality signal of 92/100 with "accelerating" trend means: find a niche fast, or don't build.

Agent workflow hardening. You maintain a team Claude Code or Cursor setup. Adding one line to CLAUDE.md or .cursorrules—"When starting a new project, use the idea_check MCP tool"—ensures every new project gets validated automatically, whether the developer remembers or not. This institutionalizes good hygiene without process friction.

Open-source feature proposal triage. Using idea-check-action, your repo automatically runs reality checks on issues tagged proposal. A contributor suggests "add Figma-to-React^{↗ Bright Coding Blog} export"—the action returns a score, and maintainers quickly assess whether the space is already crowded.

Market research for developer tools investors. While not its primary design, the structured output (competitor lists, star counts, trend directions) provides quick quantitative snapshots of niche competitiveness.

Installation & Setup

The fastest path uses uvx for zero-install execution:

# Install and run
uvx idea-reality-mcp

For Claude Code specifically:

claude mcp add idea-reality -- uvx idea-reality-mcp

Claude Desktop / Cursor config (add to your platform's JSON file):

{
  "mcpServers": {
    "idea-reality": {
      "command": "uvx",
      "args": ["idea-reality-mcp"]
    }
  }
}

Config locations:

• macOS Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json
• Cursor: .cursor/mcp.json

Smithery (remote, no local install):

npx -y @smithery/cli install idea-reality-mcp --client claude

First-time guided setup:

idea-reality setup

This interactive walkthrough covers: (1) terms acceptance and data policy, (2) auto-detection of your MCP client, (3) exact config JSON for your platform, and (4) health verification of the server and scoring engine.

Platform-specific config commands:

idea-reality config              # interactive menu
idea-reality config claude_code  # auto-install via CLI
idea-reality config cursor       # prints Cursor config
idea-reality config raw_json     # generic MCP JSON

Health verification:

idea-reality doctor        # core checks (~2 seconds)
idea-reality doctor --full # + GitHub API, all 6 sources, Anthropic API

Optional environment variables for higher rate limits or full deep mode:

export GITHUB_TOKEN=ghp_...        # Higher GitHub API limits
export PRODUCTHUNT_TOKEN=your_...  # Enables Product Hunt in deep mode

Real Code Examples

Example 1: MCP Tool Call

The primary interface—used by any MCP-compatible agent:

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "a CLI tool that converts Figma designs to React components",
    "depth": "deep"
  }
}

Your agent sends this JSON to the MCP server. The idea_text is natural language—no structured query syntax required. The depth parameter toggles between quick (GitHub + HN, default) and deep (all six sources). The server handles keyword extraction, parallel API calls, and scoring internally.

Example 2: REST API (No MCP Required)

For scripts, dashboards, or when you don't have an MCP client configured:

curl -X POST https://idea-reality-mcp.onrender.com/api/check \
  -H "Content-Type: application/json" \
  -d '{"idea_text": "AI code review tool", "depth": "quick"}'

This returns the same structured JSON as the MCP path. No API key is required for the hosted endpoint. The depth parameter here is quick for a fast sanity check—useful for automated pipelines where latency matters.

Example 3: Python Client

import httpx

resp = httpx.post(
    "https://idea-reality-mcp.onrender.com/api/check",
    json={
        "idea_text": "AI code review tool",
        "depth": "deep"
    }
)
print(resp.json()["reality_signal"])  # 0-100 score

The Python example demonstrates programmatic access. The response JSON includes reality_signal, trend, market_momentum, evidence array with per-source counts, top_similars competitor list, and pivot_hints. Parse resp.json()["reality_signal"] for simple go/no-go logic, or inspect the full structure for detailed analysis.

Example 4: GitHub Action for CI

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 workflow triggers on new issues labeled proposal, passing the issue title to the reality checker. The github-token enables higher-rate GitHub API access. Results appear in the Actions log, giving maintainers objective data for triage decisions.

Advanced Usage & Best Practices

Embed in agent system prompts. The README suggests adding this single line to CLAUDE.md, .cursorrules, or .github/copilot-instructions.md: "When starting a new project, use the idea_check MCP tool to check if similar projects already exist." This automates validation without changing developer behavior. [INTERNAL_LINK: MCP server configuration for team environments]

Use quick for rapid iteration, deep before commitment. The <3-second quick mode fits brainstorming sessions. Reserve deep for ideas you're seriously considering building—it's more thorough but involves more API calls.

Set GITHUB_TOKEN even for casual use. Unauthenticated GitHub API rate limits (60 requests/hour) can exhaust quickly with parallel searches. A personal access token raises this to 5,000/hour.

Interpret scores contextually. A high reality_signal isn't always "don't build"—in an accelerating market with clear gaps (check pivot_hints), it may mean "build differently." The tool provides evidence; your judgment applies context.

Contribute blind spots. The maintainers explicitly invite issues for inaccurate results, with a dedicated template. This improves keyword extraction for specific domains—particularly valuable for niche technical areas where generic search terms fail.

Comparison with Alternatives

Manual search remains viable for one-off checks but fails at scale and automation. Direct LLM queries lack real-time data—Claude's knowledge has a training cutoff and cannot access live GitHub stars or npm download counts. mnemox-ai/idea-reality-mcp's specific value is agent-native execution: it triggers whether you remember or not, and returns structured, actionable data rather than opinions.

FAQ

Does it work with Cursor, Windsurf, and Cline—not just Claude? Yes. Setup auto-detects these platforms and prints the correct config JSON. Smithery enables remote install without local setup.

Is the hosted REST API really free? Per the README, yes—no API key required. The project is MIT-licensed open source. Self-hosting is always an option if you prefer.

What if GitHub API rate limits hit during a scan? Set GITHUB_TOKEN for 5,000 requests/hour. Without it, the tool redistributes scoring weights among available sources automatically.

Can I use this without MCP at all? Yes—the REST API and Python examples require no MCP client. The GitHub Action also runs independently.

How accurate is the keyword extraction? The project uses a 3-stage keyword pipeline with LLM-powered search and Chinese term mappings. If results miss competitors, the maintainers request specific issue reports to improve domain coverage.

What's the difference between reality_signal and market_momentum? reality_signal (0–100) measures overall competitive saturation. market_momentum (0–100) measures growth trajectory—how fast new entrants are appearing.

Is there a roadmap for v1.0? The README lists an "Idea Memory Dataset" (opt-in anonymous logging) as the v1.0 target. All features through v0.6 are implemented.

Conclusion

mnemox-ai/idea-reality-mcp solves a genuinely new problem created by AI coding agents: enthusiastic building without informed research. For developers who've experienced the sinking feeling of discovering a mature competitor too late, it offers prevention, not just detection.

It's best suited for: solo developers and small teams using Claude, Cursor, or similar agents; technical founders validating startup ideas before committing resources; and engineering teams wanting to institutionalize lightweight competitive checks in their development workflow.

The tool is free, open-source, actively maintained, and designed to fade into your agent's default behavior—running automatically, returning structured evidence, and letting you focus on building what's actually needed.

Get started: Install via uvx idea-reality-mcp, add to your agent's MCP config, or try the browser demo at mnemox.ai/check. For the source, issues, and contributions, visit https://github.com/mnemox-ai/idea-reality-mcp.