Skip to content
Back to search

idea-reality-mcp

Pre-build reality check for AI coding agents. Scans GitHub, HN, npm, PyPI, Product Hunt. MCP server. 290+ stars.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mnemox-ai--idea-reality-mcp/badge.svg)](/listings/mnemox-ai--idea-reality-mcp)

HTML

<a href="/listings/mnemox-ai--idea-reality-mcp"><img src="/api/listings/mnemox-ai--idea-reality-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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.

<details> <summary>Other MCP clients</summary>

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

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 309 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- mcp-name: io.github.mnemox-ai/idea-reality-mcp -->
  2. English | [繁體中文](docs/zh/README.zh-TW.md)
  3. # idea-reality-mcp
  4. **How to check if someone already built your app idea — automatically.**
  5. idea-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.
  6. **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.
  7. > **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.
  8. > **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.
  9. [![PyPI](https://img.shields.io/pypi/v/idea-reality-mcp.svg)](https://pypi.org/project/idea-reality-mcp/)
  10. [![Smithery](https://smithery.ai/badge/idea-reality-mcp)](https://smithery.ai/server/idea-reality-mcp)
  11. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  12. [![CI](https://github.com/mnemox-ai/idea-reality-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mnemox-ai/idea-reality-mcp/actions/workflows/ci.yml)
  13. [![GitHub stars](https://img.shields.io/github/stars/mnemox-ai/idea-reality-mcp)](https://github.com/mnemox-ai/idea-reality-mcp)
  14. [![Downloads](https://static.pepy.tech/badge/idea-reality-mcp)](https://pepy.tech/project/idea-reality-mcp)
  15. <p align="center">
  16. <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">
  17. <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor" height="32">
  18. </a>
  19. </p>
  20. ## How it works
  21. 1. **Describe your idea** in plain English — e.g. "a CLI tool that converts Figma designs to React components"
  22. 2. **idea_check scans 5 databases** in parallel (GitHub repos + stars, Hacker News discussions, npm/PyPI packages, Stack Overflow questions)
  23. 3. **Get a 0–100 reality score** with trend direction (accelerating/stable/declining), top competitors, and AI-generated pivot suggestions
  24. ## What you get
  25. ```
  26. You: "AI code review tool"
  27. idea_check →
  28. ├── reality_signal: 92/100
  29. ├── trend: accelerating ↗
  30. ├── market_momentum: 73/100
  31. ├── GitHub repos: 847 (45% created in last 6 months)
  32. ├── Top competitor: reviewdog (9,094 ⭐)
  33. ├── npm packages: 56
  34. ├── HN discussions: 254 (trending up)
  35. └── Verdict: HIGH — market is accelerating, find a niche fast
  36. ```
  37. One score. Six sources. Trend detection. Your agent decides what to do next.
  38. <p align="center">
  39. <a href="https://mnemox.ai/check"><strong>Try it in your browser — no install</strong></a>
  40. </p>
  41. ## Quick Start
  42. ```bash
  43. # 1. Install
  44. uvx idea-reality-mcp
  45. # 2. Add to your agent
  46. claude mcp add idea-reality -- uvx idea-reality-mcp # Claude Code
  47. ```
  48. **3. Ask your agent:** *"Before I start building, check if this already exists: a CLI tool that converts Figma designs to React components"*
  49. That's it. The agent calls `idea_check` and returns: reality_signal, top competitors, and pivot suggestions.
  50. <details>
  51. <summary>Other MCP clients</summary>
  52. **Claude Desktop / Cursor** — add to config JSON:
  53. ```json
  54. {
  55. "mcpServers": {
  56. "idea-reality": {
  57. "command": "uvx",
  58. "args": ["idea-reality-mcp"]
  59. }
  60. }
  61. }
  62. ```
  63. Config location: **macOS** `~/Library/Application Support/Claude/claude_desktop_config.json` · **Windows** `%APPDATA%\Claude\claude_desktop_config.json` · **Cursor** `.cursor/mcp.json`
  64. **Smithery** (remote, no local install):
  65. ```bash
  66. npx -y @smithery/cli install idea-reality-mcp --client claude
  67. ```
  68. </details>
  69. ## Setup & Configuration
  70. First-time guided setup:
  71. ```bash
  72. idea-reality setup
  73. ```
  74. This walks you through:
  75. 1. **Terms acceptance** — data collection policy and disclaimer
  76. 2. **Platform detection** — auto-detects Claude Desktop, Claude Code, Cursor, Windsurf, Cline
  77. 3. **Config generation** — prints the exact JSON snippet for your platform
  78. 4. **Health check** — verifies MCP server, tools, and scoring engine
  79. ### Platform Configs
  80. ```bash
  81. idea-reality config # interactive menu
  82. idea-reality config claude_code # auto-installs via CLI
  83. idea-reality config cursor # prints Cursor config
  84. idea-reality config raw_json # generic MCP JSON
  85. ```
  86. Supported: Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Smithery · Docker
  87. ### Health Check
  88. ```bash
  89. idea-reality doctor # core checks (~2s)
  90. idea-reality doctor --full # + GitHub API, all 6 sources, Anthropic API
  91. ```
  92. ## Usage
  93. **MCP tool call** (any MCP-compatible agent):
  94. ```json
  95. {
  96. "tool": "idea_check",
  97. "arguments": {
  98. "idea_text": "a CLI tool that converts Figma designs to React components",
  99. "depth": "deep"
  100. }
  101. }
  102. ```
  103. **REST API** (no MCP required):
  104. ```bash
  105. curl -X POST https://idea-reality-mcp.onrender.com/api/check \
  106. -H "Content-Type: application/json" \
  107. -d '{"idea_text": "AI code review tool", "depth": "quick"}'
  108. ```
  109. **Python**:
  110. ```python
  111. import httpx
  112. resp = httpx.post("https://idea-reality-mcp.onrender.com/api/check", json={
  113. "idea_text": "AI code review tool",
  114. "depth": "deep"
  115. })
  116. print(resp.json()["reality_signal"]) # 0-100
  117. ```
  118. Free. No API key required.
  119. ## Why not just Google it?
  120. **Your AI agent never Googles anything before it starts building.** `idea_check` runs *inside* your agent — it triggers automatically whether you remember or not.
  121. | | Google | ChatGPT | idea-reality-mcp |
  122. |---|---|---|---|
  123. | **Who runs it** | You, manually | You, manually | Your agent, automatically |
  124. | **Output** | 10 blue links | "Sounds promising!" | Score 0-100 + evidence |
  125. | **Sources** | Web pages | None (LLM) | GitHub + HN + npm + PyPI + PH + SO |
  126. | **Price** | Free | Paywall | Free & open-source (MIT) |
  127. ## Modes
  128. | Mode | Sources | Use case |
  129. |------|---------|----------|
  130. | **quick** (default) | GitHub + HN | Fast sanity check, < 3 seconds |
  131. | **deep** | GitHub + HN + npm + PyPI + Stack Overflow | Full competitive scan |
  132. <details>
  133. <summary>Scoring weights</summary>
  134. | Source | Quick | Deep |
  135. |--------|-------|------|
  136. | GitHub repos | 60% | 22% |
  137. | GitHub stars | 20% | 9% |
  138. | Hacker News | 20% | 14% |
  139. | npm | — | 18% |
  140. | PyPI | — | 13% |
  141. | Stack Overflow | — | 10% |
  142. If a source is unavailable, its weight is redistributed automatically — so the deep-mode
  143. weights above are renormalised over the sources that actually answered.
  144. > **Product Hunt was removed on 2026-07-17.** It had carried 14% of the deep-mode weight
  145. > since launch and had never returned a single result: the adapter asked for
  146. > `posts(search: $query)`, and Product Hunt's API has no text search on posts at all
  147. > (`Field 'posts' doesn't accept argument 'search'`). Its weight is now redistributed to
  148. > sources that answer. If you need it back, it needs a real search surface — not a token.
  149. </details>
  150. ## Tool schema
  151. ### `idea_check`
  152. | Parameter | Type | Required | Description |
  153. |-------------|---------------------------|----------|--------------------------------------|
  154. | `idea_text` | string | yes | Natural-language description of idea |
  155. | `depth` | `"quick"` \| `"deep"` | no | `"quick"` = GitHub + HN (default). `"deep"` = all 6 sources |
  156. <details>
  157. <summary>Full output example</summary>
  158. ```json
  159. {
  160. "reality_signal": 72,
  161. "duplicate_likelihood": "high",
  162. "trend": "accelerating",
  163. "sub_scores": { "market_momentum": 73 },
  164. "evidence": [
  165. {"source": "github", "type": "repo_count", "query": "...", "count": 342},
  166. {"source": "github", "type": "max_stars", "query": "...", "count": 15000},
  167. {"source": "hackernews", "type": "mention_count", "query": "...", "count": 18},
  168. {"source": "npm", "type": "package_count", "query": "...", "count": 56},
  169. {"source": "pypi", "type": "package_count", "query": "...", "count": 23},
  170. {"source": "stackoverflow", "type": "question_count", "query": "...", "count": 120}
  171. ],
  172. "top_similars": [
  173. {"name": "user/repo", "url": "https://github.com/...", "stars": 15000, "description": "..."}
  174. ],
  175. "pivot_hints": [
  176. "High competition. Consider a niche differentiator...",
  177. "The leading project may have gaps in..."
  178. ]
  179. }
  180. ```
  181. </details>
  182. ## CI: Auto-check on Pull Requests
  183. Use [idea-check-action](https://github.com/mnemox-ai/idea-check-action) to validate feature proposals:
  184. ```yaml
  185. name: Idea Reality Check
  186. on:
  187. issues:
  188. types: [opened]
  189. jobs:
  190. check:
  191. if: contains(github.event.issue.labels.*.name, 'proposal')
  192. runs-on: ubuntu-latest
  193. steps:
  194. - uses: mnemox-ai/idea-check-action@v1
  195. with:
  196. idea: ${{ github.event.issue.title }}
  197. github-token: ${{ secrets.GITHUB_TOKEN }}
  198. ```
  199. ## Optional config
  200. ```bash
  201. export GITHUB_TOKEN=ghp_... # Higher GitHub API rate limits
  202. ```
  203. `PRODUCTHUNT_TOKEN` no longer does anything — the source is disabled and ignores it.
  204. Setting it used to be worse than useless: it un-skipped a source whose query the API
  205. rejects, so it reported "0 competitors on Product Hunt" into 14% of the deep score.
  206. **Auto-trigger:** Add one line to your `CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md`:
  207. ```
  208. When starting a new project, use the idea_check MCP tool to check if similar projects already exist.
  209. ```
  210. ## Roadmap
  211. - [x] **v0.1** — GitHub + HN search, basic scoring
  212. - [x] **v0.2** — Deep mode (npm, PyPI, Product Hunt), keyword extraction
  213. - [x] **v0.3** — 3-stage keyword pipeline, Chinese term mappings, LLM-powered search
  214. - [x] **v0.4** — Score History, Agent Templates, GitHub Action
  215. - [x] **v0.5** — Temporal signals, trend detection, market momentum
  216. - [x] **v0.6** — Onboarding CLI (`idea-reality setup`, `config`, `doctor`)
  217. ## Star History
  218. [![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)
  219. ## Found a blind spot?
  220. If the tool missed obvious competitors or returned irrelevant results:
  221. 1. [Open an issue](https://github.com/mnemox-ai/idea-reality-mcp/issues/new?template=inaccurate-result.yml) with your idea text and the output
  222. 2. We'll improve the keyword extraction for your domain
  223. ## Contributing
  224. See [CONTRIBUTING.md](CONTRIBUTING.md) ([繁體中文](docs/zh/CONTRIBUTING.zh-TW.md)).
  225. ## License
  226. MIT — see [LICENSE](LICENSE)
  227. Built by [Mnemox AI](https://mnemox.ai) · [dev@mnemox.ai](mailto:dev@mnemox.ai)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.