Subconscious Ai Mcp

Subconscious AI MCP Server

Claude、Cursor、またはMCP対応クライアントから、AIを活用したコンジョイント実験を実行できます。因果推論と合成人口を用いて、人々が意思決定をする理由を理解できます。

✨ 特長

• 🧠 因果研究 - 研究課題を検証し、統計的に妥当な実験を生成します
• 👥 合成人口 - 代表性のあるサンプリングのため、米国国勢調査のマイクロデータ（IPUMS）に基づくAIペルソナを使用します
• 📊 コンジョイント分析 - 属性の重要度を測定するAMCE（平均限界成分効果）
• 🤖 MCP プロトコル - Claude Desktop、Cursor、およびMCP対応のAIアシスタントで動作します
• 🌐 REST API - インテグレーション（n8n、Zapier、カスタムアプリ）向けの直接HTTPアクセス
• 🔌 ローカル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で使われているものと同じ15個のツールレジストリから直接生成され、認証情報の値を含めずに、ソース、トランスポート、認証、スキーマに関する決定的なメタデータを収録しています。

マニフェストには、各ツールの実装が属する正確なコミットが記載されています。スカッシュマージを行うと、エクスポートされたツールに変更がなくても、所有元のコミットは新しくなります。そのため、マージ後にマニフェストを再生成してコミットしてください。プルリクエストのアーティファクトが成功していても、それが証明するのは記載されたブランチのリビジョンであり、デフォルトブランチではありません。

🔬 ワークフローの例

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 Platform - UI から実験を作成
• API Documentation — API の完全なリファレンス
• MCP Protocol - Model Context Protocol の仕様
• Conjoint Analysis - この手法について学ぶ

📄 ライセンス

このソフトウェアを利用するには、有効な Subconscious AI サブスクリプション が必要です。詳細は LICENSE ファイルをご覧ください。

---

❤️ を込めて Subconscious AI が作成