idea-reality

idea-reality-mcp is a Python-based MCP server that performs a reality check for a given idea by querying five real data sources in parallel: GitHub repos, Hacker News discussions, npm packages, PyPI packages, and Product Hunt. It returns a reality_signal score along with supporting evidence, top similars, and pivot hints to help your agent decide whether to build, pivot, or partner. To use it, run the MCP server via your MCP client (the recommended invocation is uvx idea-reality-mcp). You can then prompt your agent to call idea_check with a natural-language description of the idea. The tool will automatically fetch sources and provide structured outputs that your agent can interpret for decision making. You can also integrate the tool into CI or other tooling via your MCP client of choice (Claude, Cursor, Code, etc.).

Prerequisites:

• Python 3.11 or newer
• Optional: pipx for isolated install
• Optional: pip if you prefer direct install

Install methods:

1. Using pip (system-wide or virtualenv):

python -m ensurepip --upgrade
pip install --upgrade idea-reality-mcp

2. Using pipx (isolated, recommended):

python -m pip install --user pipx
python -m pipx ensurepath
pipx install idea-reality-mcp

3. Verify installation:

python -m idea_reality_mcp --version  # if the package provides a CLI entry
# or depending on package, simply run the MCP via your MCP client as documented

Usage after installation:

• Run the MCP server via your MCP client, e.g., uvx idea-reality-mcp (as shown in the README).
• Ensure your environment variables (e.g., GITHUB_TOKEN) are set if you plan to access authenticated sources.

Notes and tips:

• The server pulls from five sources in parallel to produce a reality_check result with a reality_signal (0-100) and supporting evidence.
• If you hit API rate limits, provide GITHUB_TOKEN (and any other tokens you use) to increase limits.
• This MCP is open-source and free to use; you can audit and customize the sources or scoring if needed.
• When configuring in Claude Desktop or other clients, ensure the mcpServers entry matches your client’s expected format.
• For CI or automation, consider proactive triggering by adding a line to your CLAUDE.md or equivalent to call idea_check before starting a project.