Subconscious Ai Mcp

Subconscious AI MCP 服务

从 Claude、Cursor 或任何兼容 MCP 的客户端运行 AI 驱动的联合实验。利用因果推断和合成人群，了解人们做出决策的原因。

✨ 功能

• 🧠 因果研究 - 验证研究问题并生成统计上有效的实验
• 👥 合成人群 - 基于美国人口普查微观数据（IPUMS）的 AI 虚拟角色，用于代表性抽样
• 📊 联合分析 - 使用 AMCE（平均边际组分效应）衡量属性的重要性
• 🤖 MCP 协议 - 适用于 Claude Desktop、Cursor 和任何兼容 MCP 的 AI 助手
• 🌐 REST API - 通过 HTTP 直接访问，供集成使用（n8n、Zapier、自定义应用）
• 🔌 本地 stdio 传输 - 经过协议测试的 MCP 连接，适用于桌面客户端

🚀 快速开始

支持：通过 stdio 在本地运行

前置条件：

• Python 3.11+
• Subconscious AI 账户和访问令牌

# Clone the repository
git clone https://github.com/Subconscious-ai/ghostshell.git
cd ghostshell

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Set environment variables
export AUTH0_JWT_TOKEN="your_token_here"
export API_BASE_URL="https://api.subconscious.ai"

添加到 MCP 配置中：

{
  "mcpServers": {
    "subconscious-ai": {
      "command": "/absolute/path/to/venv/bin/python3",
      "args": ["/absolute/path/to/server/main.py"],
      "env": {
        "AUTH0_JWT_TOKEN": "your_token",
        "API_BASE_URL": "https://api.subconscious.ai"
      }
    }
  }
}

Python 可执行文件和 server/main.py 都必须使用绝对路径。 配置文件包含持有者凭证，请妥善保密。 examples/ 下经过验证的示例使用相同的受支持 stdio 协议约定。

无需调用付费工具即可验证协议连接：

python scripts/smoke_stdio_mcp.py

冒烟测试会执行真实的 MCP initialize 和 tools/list 交互，并 要求返回全部 15 个已注册工具。

实验性：托管 SSE

托管 SSE 端点目前尚未支持客户端配置。它仅接受通过 Authorization 标头传递的持有者凭证；URL 查询参数中的凭证会被拒绝。由于托管协议/身份验证流程目前还没有经过凭证验证的冒烟测试，请勿在生产客户端配置中依赖它。

📋 可用工具

工具	描述
check_causality	验证研究问题是否具有因果性
generate_attributes_levels	使用 AI 生成实验属性和水平
validate_population	验证目标人群的人口统计信息
get_population_stats	获取某个国家的人口统计信息
create_experiment	创建并运行联合实验
get_experiment_status	检查实验进度
list_experiments	列出你的所有实验
get_experiment_results	获取详细的实验结果
get_run_details	获取详细的运行信息
get_run_artifacts	获取运行产物和文件
update_run_config	更新运行配置
generate_personas	为实验生成 AI 虚拟角色
get_experiment_personas	获取实验的虚拟角色
get_amce_data	获取 AMCE 分析数据
get_causal_insights	获取 AI 生成的因果洞察

经过验证的 mcp-tools.public.json 文件是机器可读的发现协议。该文件直接从与托管 API 使用的同一工具注册表生成，包含确定性的来源、传输、身份验证和架构元数据，不包含凭证值。

清单会标明每个工具实现所属的确切提交。即使导出的工具没有变化，压缩合并也会创建新的所属提交，因此请在合并后重新生成并提交清单。绿色的拉取请求构建产物只能证明其标明的分支版本，并不能证明默认分支的状态。

🔬 示例工作流

You: "Check if this is a causal question: What factors influence people's decision to buy electric vehicles?"

AI: ✅ This is a causal question. Let me generate attributes for this study.

You: "Generate attributes for an EV preference study"

AI: Generated 5 attributes with 4 levels each:
    - Price: $25,000 / $35,000 / $45,000 / $55,000
    - Range: 200 miles / 300 miles / 400 miles / 500 miles
    ...

You: "Create an experiment about EV purchasing decisions"

AI: 🚀 Experiment created! Run ID: abc-123-xyz
    Status: Processing (surveying 500 synthetic respondents)

You: "Check the status of experiment abc-123-xyz"

AI: ✅ Experiment completed!
    - 500 respondents surveyed
    - Ready for analysis

You: "Get causal insights from this experiment"

AI: 📊 Key Findings:
    - Price has the strongest effect (-0.32 AMCE)
    - 400+ mile range increases preference by 28%
    - Brand reputation matters more than charging speed

🌐 REST API

通过 HTTP 直接调用工具以进行集成：

# List experiments
curl -X POST https://ghostshell-runi.vercel.app/api/call/list_experiments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

# Check causality
curl -X POST https://ghostshell-runi.vercel.app/api/call/check_causality \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"why_prompt": "What factors influence EV purchases?"}'

# Create experiment
curl -X POST https://ghostshell-runi.vercel.app/api/call/create_experiment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"why_prompt": "What factors influence EV purchases?", "confidence_level": "Reasonable"}'

# Get experiment results
curl -X POST https://ghostshell-runi.vercel.app/api/call/get_experiment_results \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"run_id": "your-run-id"}'

📡 API 端点

端点	方法	身份验证	描述
/	GET	否	服务信息和可用工具
/api/health	GET	否	健康检查
/api/tools	GET	否	列出所有工具及其架构
/api/sse	GET	是	实验性的 MCP SSE 连接（仅支持 Authorization 标头）
/api/call/{tool}	POST	是	直接调用工具

🏗️ 在 Vercel 上自托管

为你的组织部署自己的实例：

# Install Vercel CLI
npm i -g vercel

# Clone and deploy
git clone https://github.com/Subconscious-ai/ghostshell.git
cd ghostshell
vercel --prod

在 Vercel 控制面板中配置环境变量：

• API_BASE_URL：https://api.subconscious.ai（或你的后端 URL）

⚠️ 用户必须提供自己的令牌——服务会将请求代理到 Subconscious AI 后端。

💡 功能请求与支持

有功能请求或需要帮助？请发送邮件至 [email protected]

📚 资源

• Subconscious AI 平台 - 通过 UI 创建实验
• API 文档 — 完整的 API 参考
• MCP 协议 - Model Context Protocol 规范
• 联合分析 - 了解相关方法

📄 许可证

此软件需要有效的 Subconscious AI 订阅。详情请参阅 LICENSE 文件。

---

由 Subconscious AI 倾情打造 ❤️