English | 繁體中文

idea-reality-mcp

How to check if someone already built your app idea — automatically.

idea-reality-mcp is an MCP server that scans GitHub, npm, PyPI, Hacker News, 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 — so your AI agent can decide whether to build, pivot, or kill the idea before writing any code.

When to use this: You're about to start a new project and want to know if similar tools already exist, how competitive the space is, and whether the market is growing or declining.

How it works

1. Describe your idea in plain English — e.g. "a CLI tool that converts Figma designs to React components"
2. idea_check scans 6 databases in parallel (GitHub repos + stars, Hacker News discussions, npm/PyPI packages, Product Hunt launches, Stack Overflow questions)
3. Get a 0–100 reality score with trend direction (accelerating/stable/declining), top competitors, and AI-generated pivot suggestions

What you get

You: "AI code review tool"

idea_check →
├── reality_signal: 92/100
├── trend: accelerating ↗
├── market_momentum: 73/100
├── GitHub repos: 847 (45% created in last 6 months)
├── Top competitor: reviewdog (9,094 ⭐)
├── npm packages: 56
├── HN discussions: 254 (trending up)
└── Verdict: HIGH — market is accelerating, find a niche fast

One score. Six sources. Trend detection. Your agent decides what to do next.

Try it in your browser — no install

Quick Start

# 1. Install
uvx idea-reality-mcp

# 2. Add to your agent
claude mcp add idea-reality -- uvx idea-reality-mcp   # Claude Code

3. Ask your agent: "Before I start building, check if this already exists: a CLI tool that converts Figma designs to React components"

That's it. The agent calls idea_check and returns: reality_signal, top competitors, and pivot suggestions.

Other MCP clients

Claude Desktop / Cursor — add to config JSON:

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

Config location: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %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

Setup & Configuration

First-time guided setup:

idea-reality setup

This walks you through:

1. Terms acceptance — data collection policy and disclaimer
2. Platform detection — auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, Cline
3. Config generation — prints the exact JSON snippet for your platform
4. Health check — verifies MCP server, tools, and scoring engine

Platform Configs

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

Supported: Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Smithery · Docker

Health Check

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

Usage

MCP tool call (any MCP-compatible agent):

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

REST API (no MCP required):

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"}'

Python:

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

Free. No API key required.

Why not just Google it?

Your AI agent never Googles anything before it starts building. idea_check runs inside your agent — it triggers automatically whether you remember or not.

	Google	ChatGPT	idea-reality-mcp
Who runs it	You, manually	You, manually	Your agent, automatically
Output	10 blue links	"Sounds promising!"	Score 0-100 + evidence
Sources	Web pages	None (LLM)	GitHub + HN + npm + PyPI + PH + SO
Price	Free	Paywall	Free & open-source (MIT)

Modes

Mode	Sources	Use case
quick (default)	GitHub + HN	Fast sanity check, < 3 seconds
deep	GitHub + HN + npm + PyPI + Product Hunt + Stack Overflow	Full competitive scan

Scoring weights

Source	Quick	Deep
GitHub repos	60%	22%
GitHub stars	20%	9%
Hacker News	20%	14%
npm	—	18%
PyPI	—	13%
Product Hunt	—	14%
Stack Overflow	—	10%

If a source is unavailable, its weight is redistributed automatically.

Tool schema

idea_check

Parameter	Type	Required	Description
idea_text	string	yes	Natural-language description of idea
depth	"quick" | "deep"	no	"quick" = GitHub + HN (default). "deep" = all 6 sources

Full output example

{
  "reality_signal": 72,
  "duplicate_likelihood": "high",
  "trend": "accelerating",
  "sub_scores": { "market_momentum": 73 },
  "evidence": [
    {"source": "github", "type": "repo_count", "query": "...", "count": 342},
    {"source": "github", "type": "max_stars", "query": "...", "count": 15000},
    {"source": "hackernews", "type": "mention_count", "query": "...", "count": 18},
    {"source": "npm", "type": "package_count", "query": "...", "count": 56},
    {"source": "pypi", "type": "package_count", "query": "...", "count": 23},
    {"source": "producthunt", "type": "product_count", "query": "...", "count": 8},
    {"source": "stackoverflow", "type": "question_count", "query": "...", "count": 120}
  ],
  "top_similars": [
    {"name": "user/repo", "url": "https://github.com/...", "stars": 15000, "description": "..."}
  ],
  "pivot_hints": [
    "High competition. Consider a niche differentiator...",
    "The leading project may have gaps in..."
  ]
}

CI: Auto-check on Pull Requests

Use idea-check-action to validate feature proposals:

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 }}

Optional config

export GITHUB_TOKEN=ghp_...        # Higher GitHub API rate limits
export PRODUCTHUNT_TOKEN=your_...  # Enable Product Hunt (deep mode)

Auto-trigger: Add one line to your 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.

Roadmap

• v0.1 — GitHub + HN search, basic scoring
• v0.2 — Deep mode (npm, PyPI, Product Hunt), keyword extraction
• v0.3 — 3-stage keyword pipeline, Chinese term mappings, LLM-powered search
• v0.4 — Score History, Agent Templates, GitHub Action
• v0.5 — Temporal signals, trend detection, market momentum
• v0.6 — Onboarding CLI (idea-reality setup, config, doctor)
• v1.0 — Idea Memory Dataset (opt-in anonymous logging)

Star History

Found a blind spot?

If the tool missed obvious competitors or returned irrelevant results:

1. Open an issue with your idea text and the output
2. We'll improve the keyword extraction for your domain

Contributing

See CONTRIBUTING.md (繁體中文).

License

MIT — see LICENSE

Built by Mnemox AI · [email protected]