idea-reality-mcp-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

idea-reality-mcp-validation

Skill by ara.so — MCP Skills collection.

idea-reality-mcp is an MCP server that validates project ideas before you write code. It scans GitHub, Hacker News, npm, PyPI, Product Hunt, and Stack Overflow to return a 0–100 reality score, trend detection, top competitors, and pivot suggestions.

由ara.so开发的Skill——MCP Skills合集。

idea-reality-mcp是一款MCP服务器，可在你编写代码前验证项目创意。它会扫描GitHub、Hacker News、npm、PyPI、Product Hunt和Stack Overflow，返回0–100的可行性评分、趋势检测结果、顶级竞品以及转型建议。

Installation

安装

Quick Start (uvx)

快速开始（uvx）

bash

uvx idea-reality-mcp

bash

uvx idea-reality-mcp

Add to Claude Code

添加到Claude Code

bash

claude mcp add idea-reality -- uvx idea-reality-mcp

bash

claude mcp add idea-reality -- uvx idea-reality-mcp

Add to Claude Desktop / Cursor

添加到Claude Desktop / Cursor

Edit your MCP config file:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Cursor:

.cursor/mcp.json

json

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

编辑你的MCP配置文件：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

Cursor：

.cursor/mcp.json

json

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

Smithery (Remote)

Smithery（远程）

bash

npx -y @smithery/cli install idea-reality-mcp --client claude

bash

npx -y @smithery/cli install idea-reality-mcp --client claude

Setup & Configuration

设置与配置

First-Time Setup

首次设置

bash

idea-reality setup

Interactive wizard that:

Shows terms acceptance
Detects your platform (Claude Desktop, Cursor, etc.)
Generates config snippet
Runs health check

bash

idea-reality setup

交互式向导包含以下步骤：

显示条款确认
检测你的平台（Claude Desktop、Cursor等）
生成配置代码片段
运行健康检查

Platform-Specific Config

平台专属配置

bash

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

bash

idea-reality config              # 交互式菜单
idea-reality config claude_code  # 自动安装
idea-reality config cursor       # 打印Cursor配置
idea-reality config raw_json     # 通用MCP JSON

Health Check

健康检查

bash

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

bash

idea-reality doctor        # 核心检查（约2秒）
idea-reality doctor --full # + API验证，覆盖全部6个数据源

Optional Environment Variables

可选环境变量

bash

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

bash

export GITHUB_TOKEN=ghp_...        # 提升GitHub API调用限额
export PRODUCTHUNT_TOKEN=...       # 启用Product Hunt（深度模式）

Core MCP Tool:

idea_check

核心MCP工具：

idea_check

Tool Schema

工具架构

Parameters:

```
idea_text
```
(string, required): Natural-language description of your idea
```
depth
```
(string, optional):
```
"quick"
```
(default) or
```
"deep"
```

Modes:

```
quick
```
: GitHub + Hacker News (< 3 seconds)
```
deep
```
: All 6 sources (GitHub, HN, npm, PyPI, Product Hunt, Stack Overflow)

参数：

```
idea_text
```
（字符串，必填）：创意的自然语言描述
```
depth
```
（字符串，可选）：
```
"quick"
```
（默认）或
```
"deep"
```

模式：

```
quick
```
：仅扫描GitHub + Hacker News（耗时<3秒）
```
deep
```
：扫描全部6个数据源（GitHub、HN、npm、PyPI、Product Hunt、Stack Overflow）

Using from AI Agent

在AI Agent中使用

When a user says "check if this idea already exists", use the

idea_check

tool:

json

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

当用户说*"检查这个创意是否已经存在"*时，调用

idea_check

工具：

json

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "一款将Figma设计转换为React组件的CLI工具",
    "depth": "deep"
  }
}

Response Structure

响应结构

json

{
  "reality_signal": 72,
  "duplicate_likelihood": "high",
  "trend": "accelerating",
  "sub_scores": {
    "market_momentum": 73
  },
  "evidence": [
    {
      "source": "github",
      "type": "repo_count",
      "query": "figma react converter CLI",
      "count": 342
    },
    {
      "source": "github",
      "type": "max_stars",
      "query": "figma react converter",
      "count": 15000
    },
    {
      "source": "hackernews",
      "type": "mention_count",
      "query": "figma react",
      "count": 18
    },
    {
      "source": "npm",
      "type": "package_count",
      "query": "figma-react",
      "count": 56
    },
    {
      "source": "pypi",
      "type": "package_count",
      "query": "figma-react",
      "count": 23
    },
    {
      "source": "producthunt",
      "type": "product_count",
      "query": "figma react",
      "count": 8
    },
    {
      "source": "stackoverflow",
      "type": "question_count",
      "query": "figma react converter",
      "count": 120
    }
  ],
  "top_similars": [
    {
      "name": "figma-to-react/figma-to-react",
      "url": "https://github.com/figma-to-react/figma-to-react",
      "stars": 15000,
      "description": "Convert Figma designs to React components"
    }
  ],
  "pivot_hints": [
    "High competition. Consider a niche differentiator like supporting design tokens or specific component libraries.",
    "The leading project may have gaps in TypeScript support or accessibility features."
  ]
}

json

{
  "reality_signal": 72,
  "duplicate_likelihood": "high",
  "trend": "accelerating",
  "sub_scores": {
    "market_momentum": 73
  },
  "evidence": [
    {
      "source": "github",
      "type": "repo_count",
      "query": "figma react converter CLI",
      "count": 342
    },
    {
      "source": "github",
      "type": "max_stars",
      "query": "figma react converter",
      "count": 15000
    },
    {
      "source": "hackernews",
      "type": "mention_count",
      "query": "figma react",
      "count": 18
    },
    {
      "source": "npm",
      "type": "package_count",
      "query": "figma-react",
      "count": 56
    },
    {
      "source": "pypi",
      "type": "package_count",
      "query": "figma-react",
      "count": 23
    },
    {
      "source": "producthunt",
      "type": "product_count",
      "query": "figma react",
      "count": 8
    },
    {
      "source": "stackoverflow",
      "type": "question_count",
      "query": "figma react converter",
      "count": 120
    }
  ],
  "top_similars": [
    {
      "name": "figma-to-react/figma-to-react",
      "url": "https://github.com/figma-to-react/figma-to-react",
      "stars": 15000,
      "description": "Convert Figma designs to React components"
    }
  ],
  "pivot_hints": [
    "竞争激烈。考虑聚焦细分领域，比如支持设计令牌或特定组件库。",
    "头部项目可能在TypeScript支持或无障碍特性方面存在短板。"
  ]
}

REST API (No MCP Required)

REST API（无需MCP）

Python Client

Python客户端

python

import httpx

response = httpx.post(
    "https://idea-reality-mcp.onrender.com/api/check",
    json={
        "idea_text": "AI code review tool",
        "depth": "deep"
    },
    timeout=30.0
)

result = response.json()
print(f"Reality Score: {result['reality_signal']}/100")
print(f"Trend: {result['trend']}")
print(f"Top Competitor: {result['top_similars'][0]['name']} ({result['top_similars'][0]['stars']} ⭐)")

python

import httpx

response = httpx.post(
    "https://idea-reality-mcp.onrender.com/api/check",
    json={
        "idea_text": "AI代码审查工具",
        "depth": "deep"
    },
    timeout=30.0
)

result = response.json()
print(f"可行性评分: {result['reality_signal']}/100")
print(f"趋势: {result['trend']}")
print(f"顶级竞品: {result['top_similars'][0]['name']} ({result['top_similars'][0]['stars']} ⭐)")

cURL

bash

curl -X POST https://idea-reality-mcp.onrender.com/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "idea_text": "a markdown-based static site generator with live reload",
    "depth": "quick"
  }'

bash

curl -X POST https://idea-reality-mcp.onrender.com/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "idea_text": "带实时重载的基于Markdown的静态站点生成器",
    "depth": "quick"
  }'

Common Patterns

常见使用场景

Pre-Build Validation

预构建验证

Before starting a new project:

python

undefined

启动新项目前：

python

undefined

User says: "I want to build a CLI tool for GitHub issue management"

用户说: "我想开发一款用于GitHub issue管理的CLI工具"

Agent calls:

Agent调用:

{ "tool": "idea_check", "arguments": { "idea_text": "CLI tool for GitHub issue management with labels and milestones", "depth": "deep" } }

{ "tool": "idea_check", "arguments": { "idea_text": "支持标签和里程碑的GitHub issue管理CLI工具", "depth": "deep" } }

If reality_signal > 80:

如果reality_signal > 80:

→ Suggest niche differentiation or pivot

→ 建议细分领域差异化或转型

If reality_signal 40-80:

如果reality_signal 40-80:

→ Validate unique features, check top_similars

→ 验证独特功能，查看top_similars

If reality_signal < 40:

如果reality_signal < 40:

→ Green light, low competition

→ 绿灯，竞争度低

undefined

undefined

Feature Validation

功能验证

Check if a feature is already widely implemented:

json

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "add real-time collaborative editing to my markdown editor",
    "depth": "quick"
  }
}

检查某功能是否已被广泛实现：

json

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "为我的Markdown编辑器添加实时协作编辑功能",
    "depth": "quick"
  }
}

Market Trend Analysis

市场趋势分析

Understand if a space is growing or declining:

json

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "browser automation library using Chrome DevTools Protocol",
    "depth": "deep"
  }
}

Check the

trend

field:

```
"accelerating"
```
→ Growing market, act fast
```
"stable"
```
→ Mature market, differentiation critical
```
"declining"
```
→ Consider pivoting

了解某领域是增长还是衰退：

json

{
  "tool": "idea_check",
  "arguments": {
    "idea_text": "基于Chrome DevTools Protocol的浏览器自动化库",
    "depth": "deep"
  }
}

查看

trend

字段：

```
"accelerating"
```
→ 市场增长中，快速行动
```
"stable"
```
→ 成熟市场，差异化至关重要
```
"declining"
```
→ 考虑转型

Auto-Trigger in Agent Instructions

在Agent指令中自动触发

Add to

.cursorrules

CLAUDE.md

, or

.github/copilot-instructions.md

markdown

When starting a new project, use the idea_check MCP tool to check if similar projects already exist.

添加到

.cursorrules

、

CLAUDE.md

或

.github/copilot-instructions.md

：

markdown

启动新项目时，使用idea_check MCP工具检查是否已有类似项目存在。

CI/CD Integration

CI/CD集成

GitHub Action for Pull Requests

用于Pull Request的GitHub Action

Create

.github/workflows/idea-check.yml

yaml

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

This auto-validates feature proposals labeled

proposal

创建

.github/workflows/idea-check.yml

：

yaml

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

此配置会自动验证标记为

proposal

的功能提案。

Interpreting Results

结果解读

Reality Signal (0–100)

可行性评分（0–100）

0–30: Low competition, potentially novel idea
31–60: Moderate competition, validate unique angle
61–85: High competition, niche differentiation required
86–100: Saturated market, strong pivot recommended

0–30：竞争度低，创意可能具有新颖性
31–60：竞争度中等，需验证独特定位
61–85：竞争度高，需聚焦细分领域差异化
86–100：市场饱和，强烈建议转型

Duplicate Likelihood

重复可能性

```
low
```
: Few similar projects found
```
medium
```
: Several similar projects exist
```
high
```
: Many similar projects, established category
```
very_high
```
: Extremely crowded space

```
low
```
：几乎未发现类似项目
```
medium
```
：存在若干类似项目
```
high
```
：大量类似项目，已形成成熟品类
```
very_high
```
：领域极度拥挤

Market Momentum (sub_scores)

市场势头（sub_scores）

Measures recent growth in the space:

< 40: Declining interest
40–60: Stable
> 60: Growing/accelerating

衡量领域近期增长情况：

< 40：关注度下降
40–60：稳定
> 60：增长/加速增长

Scoring Weights

评分权重

Quick Mode

快速模式

Source	Weight
GitHub repos	60%
GitHub stars	20%
Hacker News	20%

数据源	权重
GitHub仓库	60%
GitHub星标	20%
Hacker News	20%

Deep Mode

深度模式

Source	Weight
GitHub repos	22%
GitHub stars	9%
Hacker News	14%
npm	18%
PyPI	13%
Product Hunt	14%
Stack Overflow	10%

If a source fails, weights redistribute automatically.

数据源	权重
GitHub仓库	22%
GitHub星标	9%
Hacker News	14%
npm	18%
PyPI	13%
Product Hunt	14%
Stack Overflow	10%

若某数据源不可用，权重会自动重新分配。

Troubleshooting

故障排查

"MCP server not found"

Cursor/Claude Desktop:

Restart the application completely
Check config file location and syntax
Run
```
idea-reality doctor
```

Claude Code:

bash

claude mcp list  # verify installation
claude mcp remove idea-reality
claude mcp add idea-reality -- uvx idea-reality-mcp

Cursor/Claude Desktop：

完全重启应用
检查配置文件位置和语法
运行
```
idea-reality doctor
```

Claude Code：

bash

claude mcp list  # 验证安装状态
claude mcp remove idea-reality
claude mcp add idea-reality -- uvx idea-reality-mcp

"GitHub API rate limit exceeded"

Set a GitHub token:

bash

export GITHUB_TOKEN=ghp_your_token_here
idea-reality doctor --full  # verify

Generate token at: https://github.com/settings/tokens (no scopes needed for public data)

设置GitHub令牌：

bash

export GITHUB_TOKEN=ghp_your_token_here
idea-reality doctor --full  # 验证

在https://github.com/settings/tokens生成令牌（公共数据无需权限范围）

"Product Hunt data missing (deep mode)"

Product Hunt requires authentication:

bash

export PRODUCTHUNT_TOKEN=your_token_here

Or use

depth: "quick"

which skips Product Hunt.

Product Hunt需要身份验证：

bash

export PRODUCTHUNT_TOKEN=your_token_here

或使用

depth: "quick"

模式，该模式会跳过Product Hunt。

"Irrelevant results"

The tool uses 3-stage keyword extraction. If results are off:

Be more specific in
```
idea_text
```
:
- ❌ "productivity app"
- ✅ "CLI time-tracking tool for developers with Git integration"
Report the issue: https://github.com/mnemox-ai/idea-reality-mcp/issues/new?template=inaccurate-result.yml

工具采用三级关键词提取。若结果不准确：

在
```
idea_text
```
中更具体地描述：
- ❌ "生产力应用"
- ✅ "面向开发者的带Git集成的CLI时间跟踪工具"
提交问题：https://github.com/mnemox-ai/idea-reality-mcp/issues/new?template=inaccurate-result.yml

"Tool call timeout"

Deep mode can take 10–15 seconds. Increase timeout:

python

undefined

深度模式可能耗时10–15秒。增加超时时间：

python

undefined

Python httpx client

Python httpx客户端

httpx.post(..., timeout=30.0)


Or use `depth: "quick"` (< 3 seconds).

httpx.post(..., timeout=30.0)


或使用`depth: "quick"`模式（耗时<3秒）。

Example Workflows

示例工作流

1. Pre-Project Kickoff

1. 项目启动前校验

markdown

User: "I want to build a Rust-based SQL formatter with auto-fix"

Agent:
1. Call idea_check with depth="deep"
2. If reality_signal > 70:
   - Show top competitors (e.g. sqlformat, prettier-plugin-sql)
   - Suggest niches from pivot_hints (e.g. Rust performance angle)
3. If reality_signal < 50:
   - Proceed with project scaffolding

markdown

用户: "我想开发一款基于Rust的SQL格式化工具，支持自动修复"

Agent:
1. 调用idea_check，设置depth="deep"
2. 如果reality_signal > 70:
   - 展示顶级竞品（如sqlformat、prettier-plugin-sql）
   - 根据pivot_hints建议细分领域（如Rust性能优势）
3. 如果reality_signal < 50:
   - 继续项目脚手架搭建

2. Feature Gap Analysis

2. 功能缺口分析

markdown

User: "Should I add Vim keybindings to my editor?"

Agent:
1. Call idea_check: "text editor with vim keybindings"
2. Check evidence[].count for npm/PyPI packages
3. High count → already solved, suggest integration
4. Low count → potential differentiator

markdown

用户: "我应该为我的编辑器添加Vim快捷键吗？"

Agent:
1. 调用idea_check："带Vim快捷键的文本编辑器"
2. 查看evidence[].count中的npm/PyPI包数量
3. 数量多→需求已被满足，建议集成现有方案
4. 数量少→可作为差异化特性

3. Market Validation

3. 市场验证

markdown

User: "Is AI code review still worth building?"

Agent:
1. Call idea_check with depth="deep"
2. Check trend field
3. If "accelerating" → market growing, move fast
4. If "declining" → suggest pivot to specific niche

markdown

用户: "AI代码审查工具还有开发价值吗？"

Agent:
1. 调用idea_check，设置depth="deep"
2. 查看trend字段
3. 如果是"accelerating"→市场增长中，快速行动
4. 如果是"declining"→建议转向特定细分领域

Advanced Usage

高级用法

Batch Validation

批量验证

python

import httpx

ideas = [
    "AI-powered commit message generator",
    "Real-time Markdown collaboration",
    "GitHub issue templates manager"
]

async with httpx.AsyncClient() as client:
    tasks = [
        client.post(
            "https://idea-reality-mcp.onrender.com/api/check",
            json={"idea_text": idea, "depth": "quick"}
        )
        for idea in ideas
    ]
    results = await asyncio.gather(*tasks)

for idea, resp in zip(ideas, results):
    data = resp.json()
    print(f"{idea}: {data['reality_signal']}/100 ({data['trend']})")

python

import httpx
import asyncio

ideas = [
    "AI驱动的提交信息生成器",
    "实时Markdown协作",
    "GitHub issue模板管理器"
]

async with httpx.AsyncClient() as client:
    tasks = [
        client.post(
            "https://idea-reality-mcp.onrender.com/api/check",
            json={"idea_text": idea, "depth": "quick"}
        )
        for idea in ideas
    ]
    results = await asyncio.gather(*tasks)

for idea, resp in zip(ideas, results):
    data = resp.json()
    print(f"{idea}: {data['reality_signal']}/100 ({data['trend']})")

Custom Analysis

自定义分析

python

def should_build(result: dict) -> str:
    score = result['reality_signal']
    trend = result['trend']
    
    if score < 40:
        return "BUILD: Low competition, novel idea"
    elif score < 70 and trend == "accelerating":
        return "BUILD WITH NICHE: Growing market, differentiate"
    elif score > 85:
        return "PIVOT: Saturated market"
    else:
        return "RESEARCH: Validate unique angle"

response = httpx.post(...)
verdict = should_build(response.json())

python

def should_build(result: dict) -> str:
    score = result['reality_signal']
    trend = result['trend']
    
    if score < 40:
        return "BUILD: 竞争度低，创意新颖"
    elif score < 70 and trend == "accelerating":
        return "BUILD WITH NICHE: 市场增长中，需差异化"
    elif score > 85:
        return "PIVOT: 市场饱和"
    else:
        return "RESEARCH: 验证独特定位"

response = httpx.post(...)
verdict = should_build(response.json())

Best Practices

最佳实践

Always use
idea_check
before scaffolding — prevents wasted effort
Start with
depth="quick"
— faster iteration, upgrade to deep if uncertain
Read
pivot_hints
— often contains actionable niche suggestions
Check
top_similars
— study competitors before building
Monitor
trend
— timing matters as much as uniqueness
Set
GITHUB_TOKEN
— avoids rate limits on larger scans

搭建项目前务必使用
idea_check
——避免无效投入
先使用
depth="quick"
模式——迭代更快，不确定时再升级到深度模式
阅读
pivot_hints
——通常包含可落地的细分领域建议
查看
top_similars
——开发前研究竞品
关注
trend
——时机和创意独特性同样重要
设置
GITHUB_TOKEN
——避免大规模扫描时触发限额

Resources

资源

GitHub: https://github.com/mnemox-ai/idea-reality-mcp
PyPI: https://pypi.org/project/idea-reality-mcp/
Web Demo: https://mnemox.ai/check/
CI Action: https://github.com/mnemox-ai/idea-check-action

GitHub: https://github.com/mnemox-ai/idea-reality-mcp
PyPI: https://pypi.org/project/idea-reality-mcp/
Web演示: https://mnemox.ai/check/
CI Action: https://github.com/mnemox-ai/idea-check-action

idea-reality-mcp-validation

Original

Translation

idea-reality-mcp-validation

idea-reality-mcp-validation

Installation

安装

Quick Start (uvx)

快速开始（uvx）

Add to Claude Code

添加到Claude Code

Add to Claude Desktop / Cursor

添加到Claude Desktop / Cursor

Smithery (Remote)

Smithery（远程）

Setup & Configuration

设置与配置

First-Time Setup

首次设置

Platform-Specific Config

平台专属配置

Health Check

健康检查

Optional Environment Variables

可选环境变量

Core MCP Tool: idea_check

核心MCP工具：idea_check

Tool Schema

工具架构

Using from AI Agent

在AI Agent中使用

Response Structure

响应结构

REST API (No MCP Required)

REST API（无需MCP）

Python Client

Python客户端

cURL

cURL

Common Patterns

常见使用场景

Pre-Build Validation

预构建验证

User says: "I want to build a CLI tool for GitHub issue management"

用户说: "我想开发一款用于GitHub issue管理的CLI工具"

Agent calls:

Agent调用:

If reality_signal > 80:

如果reality_signal > 80:

→ Suggest niche differentiation or pivot

→ 建议细分领域差异化或转型

If reality_signal 40-80:

如果reality_signal 40-80:

→ Validate unique features, check top_similars

→ 验证独特功能，查看top_similars

If reality_signal < 40:

如果reality_signal < 40:

→ Green light, low competition

→ 绿灯，竞争度低

Feature Validation

功能验证

Market Trend Analysis

市场趋势分析

Auto-Trigger in Agent Instructions

在Agent指令中自动触发

CI/CD Integration

CI/CD集成

GitHub Action for Pull Requests

用于Pull Request的GitHub Action

Interpreting Results

结果解读

Reality Signal (0–100)

可行性评分（0–100）

Duplicate Likelihood

重复可能性

Market Momentum (sub_scores)

市场势头（sub_scores）

Scoring Weights

评分权重

Quick Mode

Core MCP Tool:
`idea_check`

核心MCP工具：
`idea_check`