idea-reality-mcp: a pre-build existence check for AI coding agents
Pre-build reality check for AI coding agents. Scans GitHub, HN, npm, PyPI, Product Hunt. MCP server. 290+ stars.
At a glance
- What is it?
- An MCP server that queries GitHub, Hacker News, npm, PyPI and Stack Overflow and returns a 0 to 100 reality score for a product idea. The mechanism is simple and the scoring weights are published, but the project is in maintenance mode and one of its six advertised sources was removed in July 2026.
- Who is it for?
- Adopt it if your agent already runs through MCP and you want a repeatable, evidence-backed check before scaffolding a new project; the quick mode is the cheap default and the source weights are published, so you can reason about what a score means. Skip it if you need current competitive intelligence, since the README states the project is in maintenance mode with no new features planned, and Product Hunt was removed on 2026-07-17 after never returning a result.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 35 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap idea-reality-mcp fills between an idea and a first commit
The README states the problem directly: your AI agent never searches before it starts building. A developer describes an idea, the agent scaffolds files, and nobody has checked whether 800 repositories already do the same thing. idea-reality-mcp targets that moment. It is an MCP server, so the check runs inside the agent's tool loop rather than in a browser tab the developer has to remember to open. The README's own framing is a comparison table with Google and ChatGPT, and the row that matters is who runs it: you, manually, versus your agent, automatically. The intended user is someone about to start a new project who wants to know whether similar tools exist, how crowded the space is, and whether interest is rising or falling. It is explicitly a pre-build check, not a competitive research tool for an existing product, and not a substitute for reading the actual repositories it surfaces.
Five adapters, one score, and a renormalisation rule that changes what the number means
The data flow is straightforward. The agent calls the idea_check tool with idea_text and a depth value. The server fans out to source adapters in parallel, collects counts and items, and passes them through a scoring engine that returns a 0 to 100 reality_signal plus a trend direction (accelerating, stable or declining), a market_momentum figure, top competitors, and pivot suggestions. The published weights differ sharply by mode. In quick mode, GitHub repositories carry 60 percent, GitHub stars 20 percent and Hacker News 20 percent. In deep mode the weight spreads out: GitHub repositories 22 percent, npm 18 percent, Hacker News 14 percent, PyPI 13 percent, Stack Overflow 10 percent, GitHub stars 9 percent. The detail worth reading twice is the fallback rule. The README states that if a source is unavailable, its weight is redistributed automatically, so the deep-mode table is renormalised over whichever sources actually answered. A deep score computed from four sources is not the same measurement as one computed from six, and the output does not appear to label which case you got. Treat the number as a signal about the sources that responded, not an absolute market reading.
Installing it: uvx, one CLI line, and a doctor command worth running first
The README gives two install paths. The fastest is uvx idea-reality-mcp, followed by claude mcp add idea-reality -- uvx idea-reality-mcp for Claude Code. For Claude Desktop, Cursor, Windsurf and Cline, the config block is a standard MCP server entry with command uvx and args ["idea-reality-mcp"], placed in claude_desktop_config.json on macOS at ~/Library/Application Support/Claude/, on Windows at %APPDATA%\Claude\, or in .cursor/mcp.json for Cursor. There is also a Smithery route (npx -y @smithery/cli install idea-reality-mcp --client claude) for a remote install with no local package. The setup command idea-reality setup walks through terms acceptance, platform detection, config generation and a health check. For verification, idea-reality doctor runs core checks in roughly two seconds according to the README, and idea-reality doctor --full adds the GitHub API, all six sources and the Anthropic API. That distinction matters here: the scoring depends on live third-party APIs, so the full doctor run is the only way to confirm the adapters your score will actually use are reachable. There is also a REST endpoint at https://idea-reality-mcp.onrender.com/api/check that takes the same idea_text and depth fields and requires no API key, which is the quickest way to see the output shape before wiring anything into an agent.
The Product Hunt removal is the most instructive thing in the README
The README carries a note that Product Hunt was removed on 2026-07-17. It had held 14 percent of the deep-mode weight since launch and, in the project's own words, had never returned a single result, because the adapter called posts(search: $query) and the Product Hunt API has no such query. That is a silent-failure bug that survived from launch until mid-2026 while contributing weight to every deep score. The renormalisation rule softened the damage, since a dead adapter's weight is redistributed, but the episode is a fair warning about the rest of the pipeline: these are undocumented or partly documented third-party APIs, and an adapter can fail in a way that looks like a zero rather than an error. The current version is v0.5.0, dated 2026-03-11 and labelled Temporal Signals plus Score Recalibration, which is the release that introduced the trend direction and changed the weights. Nothing in the supplied material explains how trend direction is computed, how far back the temporal window reaches, or how market_momentum is derived. Those are the load-bearing parts of the output and they are the least documented.
Maintenance mode, and the case where a search engine beats it
The README states plainly, under a project status note dated August 2026, that the tool is in maintenance mode: it works, stays free and open source, the hosted API remains up, bug reports are reviewed, but no new features are planned. For a tool whose entire value is the freshness of five external data sources, that is the central risk. Source adapters rot; the Product Hunt case shows what rot looks like from the inside. The obvious alternative is a direct GitHub search, and the difference in approach is real rather than cosmetic. A repository search returns the repositories themselves, with names, descriptions and last-commit dates you can open and read. idea-reality-mcp returns a weighted scalar derived from counts, plus a trend label and pivot suggestions. If your question is whether a specific library exists, the search answers it and the score does not. If your question is whether a category is crowded, the score compresses five sources into one number, which is the thing a search cannot do. The honest split: use the score to decide whether the space is worth entering at all, then use a plain search to see who is actually in it. The README's own example output shows the tool naming a top competitor, so the evidence is there, but the score is the headline and the evidence is the supporting detail.
Licence, upgrade surface, and what the MIT grant does not cover
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. Two things sit outside that grant. The first is the hosted API at idea-reality-mcp.onrender.com, which is a service, not the licensed code, and the README offers no uptime commitment for it. The second is the optional Anthropic API path referenced by idea-reality doctor --full, which implies a key and a separate provider relationship for the AI-generated pivot suggestions. Self-hosting the server keeps you inside the MIT grant; relying on the hosted endpoint does not. On upgrade cost, the version history is short and the breaking surface is small: v0.3.4 added MCP Registry support, v0.4.0 added an email gate and subscribe flow with simplified templates, and v0.5.0 changed the scoring. That last one is the one to watch, because a recalibration changes the meaning of a stored score. If you log reality_signal values over time, a v0.5.0-era score is not comparable with an earlier one, and the README does not offer a migration note for historical values. Pinning via uvx and re-running the full doctor after any version bump is the cheap insurance.
Where the tool is the wrong choice
Two failure modes are visible in the material. The first is treating the score as a kill signal. A high reality_signal means the space is crowded and accelerating, which the README's own example verdict reads as find a niche fast, not abandon the idea. The score measures how much has been built, not whether a specific underserved segment exists, and the pivot suggestions are AI-generated, which the README labels as such. The second is using it for a domain the adapters do not index well. The five sources are GitHub, Hacker News, npm, PyPI and Stack Overflow. A hardware product, a regulated service, or a B2B workflow tool with no open source footprint will score low for lack of indexed evidence, which reads as an open market when it may simply be an invisible one. The tool also cannot see private repositories, internal company tools, or anything that never reached a package registry or a public discussion forum. If your competitive set lives entirely in those places, the check will return a confident number built on absence. That is the case to skip it, or to read the evidence list rather than the score.
Editorial conclusion
Adopt it if your agent already runs through MCP and you want a repeatable, evidence-backed check before scaffolding a new project; the quick mode is the cheap default and the source weights are published, so you can reason about what a score means. Skip it if you need current competitive intelligence, since the README states the project is in maintenance mode with no new features planned, and Product Hunt was removed on 2026-07-17 after never returning a result. Before trusting a score, run idea-reality doctor --full to confirm which sources actually answered, and read the redistributed weights rather than the nominal deep-mode table.
Community notes