{
  "markdown": "<!-- mcp-name: io.github.mnemox-ai/idea-reality-mcp -->\nEnglish | [繁體中文](docs/zh/README.zh-TW.md)\n\n# idea-reality-mcp\n\n**How to check if someone already built your app idea — automatically.**\n\nidea-reality-mcp is an MCP server that scans GitHub, npm, PyPI, Hacker News, 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.\n\n**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.\n\n> **Project status (August 2026):** Maintenance mode. The tool works, stays free & open source, and the hosted API remains up; bug reports are reviewed, but no new features are planned.\n\n> **Not just checking — building it?** After a reality check, open your idea as a public project on **[AngelRun](https://angelrun.vercel.app/new?utm_source=idea-reality&utm_medium=readme&utm_campaign=demand-cta)** — ship updates, climb the season, and get seen by angels.\n\n[![PyPI](https://img.shields.io/pypi/v/idea-reality-mcp.svg)](https://pypi.org/project/idea-reality-mcp/)\n[![Smithery](https://smithery.ai/badge/idea-reality-mcp)](https://smithery.ai/server/idea-reality-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Tests](https://img.shields.io/badge/tests-277%20passing-brightgreen.svg)]()\n[![GitHub stars](https://img.shields.io/github/stars/mnemox-ai/idea-reality-mcp)](https://github.com/mnemox-ai/idea-reality-mcp)\n[![Downloads](https://static.pepy.tech/badge/idea-reality-mcp)](https://pepy.tech/project/idea-reality-mcp)\n\n<p align=\"center\">\n  <a href=\"cursor://anysphere.cursor-deeplink/mcp/install?name=idea-reality&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22idea-reality-mcp%22%5D%7D\">\n    <img src=\"https://cursor.com/deeplink/mcp-install-dark.svg\" alt=\"Install in Cursor\" height=\"32\">\n  </a>\n</p>\n\n## How it works\n\n1. **Describe your idea** in plain English — e.g. \"a CLI tool that converts Figma designs to React components\"\n2. **idea_check scans 5 databases** in parallel (GitHub repos + stars, Hacker News discussions, npm/PyPI packages, Stack Overflow questions)\n3. **Get a 0–100 reality score** with trend direction (accelerating/stable/declining), top competitors, and AI-generated pivot suggestions\n\n## What you get\n\n```\nYou: \"AI code review tool\"\n\nidea_check →\n├── reality_signal: 92/100\n├── trend: accelerating ↗\n├── market_momentum: 73/100\n├── GitHub repos: 847 (45% created in last 6 months)\n├── Top competitor: reviewdog (9,094 ⭐)\n├── npm packages: 56\n├── HN discussions: 254 (trending up)\n└── Verdict: HIGH — market is accelerating, find a niche fast\n```\n\nOne score. Six sources. Trend detection. Your agent decides what to do next.\n\n<p align=\"center\">\n  <a href=\"https://mnemox.ai/check\"><strong>Try it in your browser — no install</strong></a>\n</p>\n\n## Quick Start\n\n```bash\n# 1. Install\nuvx idea-reality-mcp\n\n# 2. Add to your agent\nclaude mcp add idea-reality -- uvx idea-reality-mcp   # Claude Code\n```\n\n**3. Ask your agent:** *\"Before I start building, check if this already exists: a CLI tool that converts Figma designs to React components\"*\n\nThat's it. The agent calls `idea_check` and returns: reality_signal, top competitors, and pivot suggestions.\n\n<details>\n<summary>Other MCP clients</summary>\n\n**Claude Desktop / Cursor** — add to config JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"idea-reality\": {\n      \"command\": \"uvx\",\n      \"args\": [\"idea-reality-mcp\"]\n    }\n  }\n}\n```\n\nConfig location: **macOS** `~/Library/Application Support/Claude/claude_desktop_config.json` · **Windows** `%APPDATA%\\Claude\\claude_desktop_config.json` · **Cursor** `.cursor/mcp.json`\n\n**Smithery** (remote, no local install):\n\n```bash\nnpx -y @smithery/cli install idea-reality-mcp --client claude\n```\n\n</details>\n\n## Setup & Configuration\n\nFirst-time guided setup:\n\n```bash\nidea-reality setup\n```\n\nThis walks you through:\n1. **Terms acceptance** — data collection policy and disclaimer\n2. **Platform detection** — auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, Cline\n3. **Config generation** — prints the exact JSON snippet for your platform\n4. **Health check** — verifies MCP server, tools, and scoring engine\n\n### Platform Configs\n\n```bash\nidea-reality config              # interactive menu\nidea-reality config claude_code  # auto-installs via CLI\nidea-reality config cursor       # prints Cursor config\nidea-reality config raw_json     # generic MCP JSON\n```\n\nSupported: Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Smithery · Docker\n\n### Health Check\n\n```bash\nidea-reality doctor        # core checks (~2s)\nidea-reality doctor --full # + GitHub API, all 6 sources, Anthropic API\n```\n\n## Usage\n\n**MCP tool call** (any MCP-compatible agent):\n\n```json\n{\n  \"tool\": \"idea_check\",\n  \"arguments\": {\n    \"idea_text\": \"a CLI tool that converts Figma designs to React components\",\n    \"depth\": \"deep\"\n  }\n}\n```\n\n**REST API** (no MCP required):\n\n```bash\ncurl -X POST https://idea-reality-mcp.onrender.com/api/check \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"idea_text\": \"AI code review tool\", \"depth\": \"quick\"}'\n```\n\n**Python**:\n\n```python\nimport httpx\n\nresp = httpx.post(\"https://idea-reality-mcp.onrender.com/api/check\", json={\n    \"idea_text\": \"AI code review tool\",\n    \"depth\": \"deep\"\n})\nprint(resp.json()[\"reality_signal\"])  # 0-100\n```\n\nFree. No API key required.\n\n## Why not just Google it?\n\n**Your AI agent never Googles anything before it starts building.** `idea_check` runs *inside* your agent — it triggers automatically whether you remember or not.\n\n| | Google | ChatGPT | idea-reality-mcp |\n|---|---|---|---|\n| **Who runs it** | You, manually | You, manually | Your agent, automatically |\n| **Output** | 10 blue links | \"Sounds promising!\" | Score 0-100 + evidence |\n| **Sources** | Web pages | None (LLM) | GitHub + HN + npm + PyPI + PH + SO |\n| **Price** | Free | Paywall | Free & open-source (MIT) |\n\n## Modes\n\n| Mode | Sources | Use case |\n|------|---------|----------|\n| **quick** (default) | GitHub + HN | Fast sanity check, < 3 seconds |\n| **deep** | GitHub + HN + npm + PyPI + Stack Overflow | Full competitive scan |\n\n<details>\n<summary>Scoring weights</summary>\n\n| Source | Quick | Deep |\n|--------|-------|------|\n| GitHub repos | 60% | 22% |\n| GitHub stars | 20% | 9% |\n| Hacker News | 20% | 14% |\n| npm | — | 18% |\n| PyPI | — | 13% |\n| Stack Overflow | — | 10% |\n\nIf a source is unavailable, its weight is redistributed automatically — so the deep-mode\nweights above are renormalised over the sources that actually answered.\n\n> **Product Hunt was removed on 2026-07-17.** It had carried 14% of the deep-mode weight\n> since launch and had never returned a single result: the adapter asked for\n> `posts(search: $query)`, and Product Hunt's API has no text search on posts at all\n> (`Field 'posts' doesn't accept argument 'search'`). Its weight is now redistributed to\n> sources that answer. If you need it back, it needs a real search surface — not a token.\n\n</details>\n\n## Tool schema\n\n### `idea_check`\n\n| Parameter   | Type                      | Required | Description                          |\n|-------------|---------------------------|----------|--------------------------------------|\n| `idea_text` | string                    | yes      | Natural-language description of idea |\n| `depth`     | `\"quick\"` \\| `\"deep\"`     | no       | `\"quick\"` = GitHub + HN (default). `\"deep\"` = all 6 sources |\n\n<details>\n<summary>Full output example</summary>\n\n```json\n{\n  \"reality_signal\": 72,\n  \"duplicate_likelihood\": \"high\",\n  \"trend\": \"accelerating\",\n  \"sub_scores\": { \"market_momentum\": 73 },\n  \"evidence\": [\n    {\"source\": \"github\", \"type\": \"repo_count\", \"query\": \"...\", \"count\": 342},\n    {\"source\": \"github\", \"type\": \"max_stars\", \"query\": \"...\", \"count\": 15000},\n    {\"source\": \"hackernews\", \"type\": \"mention_count\", \"query\": \"...\", \"count\": 18},\n    {\"source\": \"npm\", \"type\": \"package_count\", \"query\": \"...\", \"count\": 56},\n    {\"source\": \"pypi\", \"type\": \"package_count\", \"query\": \"...\", \"count\": 23},\n    {\"source\": \"stackoverflow\", \"type\": \"question_count\", \"query\": \"...\", \"count\": 120}\n  ],\n  \"top_similars\": [\n    {\"name\": \"user/repo\", \"url\": \"https://github.com/...\", \"stars\": 15000, \"description\": \"...\"}\n  ],\n  \"pivot_hints\": [\n    \"High competition. Consider a niche differentiator...\",\n    \"The leading project may have gaps in...\"\n  ]\n}\n```\n\n</details>\n\n## CI: Auto-check on Pull Requests\n\nUse [idea-check-action](https://github.com/mnemox-ai/idea-check-action) to validate feature proposals:\n\n```yaml\nname: Idea Reality Check\non:\n  issues:\n    types: [opened]\n\njobs:\n  check:\n    if: contains(github.event.issue.labels.*.name, 'proposal')\n    runs-on: ubuntu-latest\n    steps:\n      - uses: mnemox-ai/idea-check-action@v1\n        with:\n          idea: ${{ github.event.issue.title }}\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n## Optional config\n\n```bash\nexport GITHUB_TOKEN=ghp_...        # Higher GitHub API rate limits\n```\n\n`PRODUCTHUNT_TOKEN` no longer does anything — the source is disabled and ignores it.\nSetting it used to be worse than useless: it un-skipped a source whose query the API\nrejects, so it reported \"0 competitors on Product Hunt\" into 14% of the deep score.\n\n**Auto-trigger:** Add one line to your `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md`:\n\n```\nWhen starting a new project, use the idea_check MCP tool to check if similar projects already exist.\n```\n\n## Roadmap\n\n- [x] **v0.1** — GitHub + HN search, basic scoring\n- [x] **v0.2** — Deep mode (npm, PyPI, Product Hunt), keyword extraction\n- [x] **v0.3** — 3-stage keyword pipeline, Chinese term mappings, LLM-powered search\n- [x] **v0.4** — Score History, Agent Templates, GitHub Action\n- [x] **v0.5** — Temporal signals, trend detection, market momentum\n- [x] **v0.6** — Onboarding CLI (`idea-reality setup`, `config`, `doctor`)\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=mnemox-ai/idea-reality-mcp&type=Date)](https://star-history.com/#mnemox-ai/idea-reality-mcp&Date)\n\n## Found a blind spot?\n\nIf the tool missed obvious competitors or returned irrelevant results:\n\n1. [Open an issue](https://github.com/mnemox-ai/idea-reality-mcp/issues/new?template=inaccurate-result.yml) with your idea text and the output\n2. We'll improve the keyword extraction for your domain\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) ([繁體中文](docs/zh/CONTRIBUTING.zh-TW.md)).\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\nBuilt by [Mnemox AI](https://mnemox.ai) · [dev@mnemox.ai](mailto:dev@mnemox.ai)\n",
  "bytes": 10798,
  "sha": "e8474c44aa4ae31fb1642506aa6c8bcfe3a7f2cfdcfe5ec042e67ae8d78a8474",
  "repo_slug": "mnemox-ai/idea-reality-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mnemox_ai_idea_reality_mcp_9c5471ed/readme"
}