Subconscious AI MCP

Execute experimentos conjuntos e pesquisas causais por meio de simulações comportamentais alimentadas por IA.

Documentação

Servidor MCP Subconscious AI

Execute experimentos conjoint com IA a partir do Claude, Cursor ou qualquer cliente compatível com MCP. Entenda por que as pessoas tomam decisões usando inferência causal e populações sintéticas.

✨ Recursos

🧠 Pesquisa Causal — Valide perguntas de pesquisa e gere experimentos estatisticamente válidos
👥 Populações Sintéticas — Personas de IA baseadas em microdados do Censo dos EUA (IPUMS) para amostragem representativa
📊 Análise Conjoint — AMCE (Efeitos Médios Marginais de Componentes) para medir a importância de atributos
🤖 Protocolo MCP — Funciona com Claude Desktop, Cursor e qualquer assistente de IA compatível com MCP
🌐 API REST — Acesso HTTP direto para integrações (n8n, Zapier, aplicativos personalizados)
🔌 Transporte stdio local — Conexão MCP testada por protocolo para clientes desktop

🚀 Início Rápido

Compatível: Execute localmente via stdio

Pré-requisitos:

Python 3.11+
Uma conta Subconscious AI e token de acesso

# 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"

Adicione à sua configuração 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"
      }
    }
  }
}

Use um caminho absoluto tanto para o executável Python quanto para server/main.py. Mantenha o arquivo de configuração privado, pois ele contém uma credencial bearer. Os exemplos verificados em examples/ usam o mesmo contrato stdio compatível.

Você pode verificar a conexão do protocolo sem chamar uma ferramenta paga:

python scripts/smoke_stdio_mcp.py

O teste de fumaça realiza uma troca real de initialize e tools/list do MCP e espera todas as 15 ferramentas registradas.

Experimental: SSE hospedado

O endpoint SSE hospedado ainda não é uma configuração de cliente compatível. Ele aceita credenciais bearer apenas por meio do cabeçalho Authorization; credenciais na query da URL são rejeitadas. Como o fluxo de protocolo/autenticação hospedado ainda não possui um teste de fumaça com credenciais, não confie nele para configuração de cliente em produção.

📋 Ferramentas Disponíveis

Ferramenta	Descrição
`check_causality`	Valide se uma pergunta de pesquisa é causal
`generate_attributes_levels`	Gere atributos e níveis de experimento usando IA
`validate_population`	Valide dados demográficos da população-alvo
`get_population_stats`	Obtenha estatísticas populacionais de um país
`create_experiment`	Crie e execute um experimento conjoint
`get_experiment_status`	Verifique o progresso do experimento
`list_experiments`	Liste todos os seus experimentos
`get_experiment_results`	Obtenha resultados detalhados do experimento
`get_run_details`	Obtenha informações detalhadas da execução
`get_run_artifacts`	Obtenha artefatos e arquivos da execução
`update_run_config`	Atualize a configuração da execução
`generate_personas`	Gere personas de IA para um experimento
`get_experiment_personas`	Obtenha personas para um experimento
`get_amce_data`	Obtenha dados analíticos de AMCE
`get_causal_insights`	Obtenha insights causais gerados por IA

O arquivo mcp-tools.public.json verificado é o contrato de descoberta legível por máquina. Ele é gerado diretamente do mesmo registro de 15 ferramentas usado pela API hospedada e inclui metadados determinísticos de origem, transporte, autenticação e esquema, sem valores de credenciais.

O manifesto nomeia o commit exato que é dono de cada implementação de ferramenta. Um squash merge cria um novo commit proprietário mesmo quando as ferramentas exportadas não mudam, então regenere e faça commit do manifesto após o merge. Um artefato verde de pull request comprova a revisão do branch nomeado, não o branch padrão.

🔬 Exemplo de Fluxo de Trabalho

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

🌐 API REST

Chame ferramentas diretamente via HTTP para integrações:

# 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"}'

📡 Endpoints da API

Endpoint	Método	Autenticação	Descrição
`/`	GET	Não	Informações do servidor e ferramentas disponíveis
`/api/health`	GET	Não	Verificação de saúde
`/api/tools`	GET	Não	Liste todas as ferramentas com esquemas
`/api/sse`	GET	Sim	Conexão SSE MCP experimental (somente cabeçalho Authorization)
`/api/call/{tool}`	POST	Sim	Chame uma ferramenta diretamente

🏗️ Autohospedagem na Vercel

Implante sua própria instância para sua organização:

# Install Vercel CLI
npm i -g vercel

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

Configure variáveis de ambiente no painel da Vercel:

API_BASE_URL: https://api.subconscious.ai (ou sua URL de backend)

⚠️ Os usuários devem fornecer seus próprios tokens — o servidor faz proxy das requisições para o backend da Subconscious AI.

💡 Solicitações de Recursos e Suporte

Tem uma solicitação de recurso ou precisa de ajuda? Envie um e-mail para nihar@subconscious.ai

📚 Recursos

Plataforma Subconscious AI — Crie experimentos pela interface
Documentação da API — Referência completa da API
Protocolo MCP — Especificação do Model Context Protocol
Análise Conjoint — Aprenda sobre a metodologia

📄 Licença

Este software requer uma assinatura ativa da Subconscious AI. Consulte o arquivo LICENSE para obter detalhes.

Feito com ❤️ por Subconscious AI