Subconscious AI MCP

Ejecuta experimentos conjuntos e investigación causal mediante simulaciones conductuales impulsadas por IA.

Documentación

Servidor MCP de Subconscious AI

Ejecuta experimentos conjuntos impulsados por IA desde Claude, Cursor o cualquier cliente compatible con MCP. Comprende por qué las personas toman decisiones utilizando inferencia causal y poblaciones sintéticas.

✨ Características

🧠 Investigación Causal - Valida preguntas de investigación y genera experimentos estadísticamente válidos
👥 Poblaciones Sintéticas - Personas de IA basadas en microdatos del Censo de EE. UU. (IPUMS) para muestreo representativo
📊 Análisis Conjunto - AMCE (Efectos Marginales Promedio de Componentes) para medir la importancia de los atributos
🤖 Protocolo MCP - Funciona con Claude Desktop, Cursor y cualquier asistente de IA compatible con MCP
🌐 API REST - Acceso HTTP directo para integraciones (n8n, Zapier, aplicaciones personalizadas)
🔌 Transporte stdio local - Conexión MCP probada por protocolo para clientes de escritorio

🚀 Inicio Rápido

Compatible: Ejecutar localmente sobre stdio

Requisitos previos:

Python 3.11+
Una cuenta de Subconscious AI y token de acceso

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

Agrega a tu configuración de 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"
      }
    }
  }
}

Usa una ruta absoluta tanto para el ejecutable de Python como para server/main.py. Mantén privado el archivo de configuración porque contiene una credencial de portador. Los ejemplos verificados bajo examples/ usan el mismo contrato stdio compatible.

Puedes verificar la conexión del protocolo sin llamar a una herramienta de pago:

python scripts/smoke_stdio_mcp.py

La prueba de humo realiza un intercambio real de MCP initialize y tools/list y espera las 15 herramientas registradas.

Experimental: SSE alojado

El endpoint SSE alojado aún no es una configuración de cliente compatible. Acepta credenciales de portador solo a través del encabezado Authorization; las credenciales en la URL de consulta son rechazadas. Debido a que el flujo de protocolo/autenticación alojado aún no tiene una prueba de humo con credenciales, no confíes en él para la configuración de clientes en producción.

📋 Herramientas Disponibles

Herramienta	Descripción
`check_causality`	Valida que una pregunta de investigación sea causal
`generate_attributes_levels`	Genera atributos y niveles de experimento usando IA
`validate_population`	Valida la demografía de la población objetivo
`get_population_stats`	Obtiene estadísticas de población para un país
`create_experiment`	Crea y ejecuta un experimento conjunto
`get_experiment_status`	Verifica el progreso del experimento
`list_experiments`	Lista todos tus experimentos
`get_experiment_results`	Obtiene resultados detallados del experimento
`get_run_details`	Obtiene información detallada de la ejecución
`get_run_artifacts`	Obtiene artefactos y archivos de la ejecución
`update_run_config`	Actualiza la configuración de la ejecución
`generate_personas`	Genera personas de IA para un experimento
`get_experiment_personas`	Obtiene personas para un experimento
`get_amce_data`	Obtiene datos analíticos de AMCE
`get_causal_insights`	Obtiene información causal generada por IA

El archivo mcp-tools.public.json verificado es el contrato de descubrimiento legible por máquina. Se genera directamente desde el mismo registro de 15 herramientas utilizado por la API alojada e incluye metadatos deterministas de fuente, transporte, autenticación y esquema sin valores de credenciales.

El manifiesto nombra la confirmación exacta que posee cada implementación de herramienta. Una fusión de squash crea una nueva confirmación propietaria incluso cuando las herramientas exportadas no cambian, así que regenera y confirma el manifiesto después de la fusión. Un artefacto verde de solicitud de extracción prueba su revisión de rama nombrada, no la rama predeterminada.

🔬 Flujo de Trabajo de Ejemplo

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

Llama a las herramientas directamente vía HTTP para integraciones:

# 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 de API

Endpoint	Método	Autenticación	Descripción
`/`	GET	No	Información del servidor y herramientas disponibles
`/api/health`	GET	No	Verificación de estado
`/api/tools`	GET	No	Lista todas las herramientas con esquemas
`/api/sse`	GET	Sí	Conexión SSE MCP experimental (solo encabezado de Autorización)
`/api/call/{tool}`	POST	Sí	Llama a una herramienta directamente

🏗️ Autoalojamiento en Vercel

Implementa tu propia instancia para tu organización:

# Install Vercel CLI
npm i -g vercel

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

Configura las variables de entorno en el panel de Vercel:

API_BASE_URL: https://api.subconscious.ai (o tu URL de backend)

⚠️ Los usuarios deben proporcionar sus propios tokens: el servidor envía solicitudes al backend de Subconscious AI.

💡 Solicitudes de Funciones y Soporte

¿Tienes una solicitud de función o necesitas ayuda? Envíanos un correo a nihar@subconscious.ai

📚 Recursos

Plataforma Subconscious AI - Crea experimentos mediante la interfaz de usuario
Documentación de API — Referencia completa de la API
Protocolo MCP - Especificación del Model Context Protocol
Análisis Conjunto - Aprende sobre la metodología

📄 Licencia

Este software requiere una suscripción activa de Subconscious AI. Consulta el archivo LICENSE para más detalles.

Hecho con ❤️ por Subconscious AI