stakeholder-mcp

Permite que tu agente de IA mantenga conversaciones con diferentes personas sobre características y detalles de implementación.

GitHub

Documentación

Servidor MCP de Stakeholders

Un servidor MCP (Model Context Protocol) que expone personas de stakeholders como herramientas para retroalimentación iterativa de productos. Cada stakeholder representa un rol distinto con una personalidad, experiencia y preocupaciones únicas.

¿Sensible al costo? El servidor usa un límite de tokens predeterminado alto para que los modelos puedan razonar sobre requisitos e implementación. Para controlar costos, establece STAKEHOLDER_MCP_MAX_TOKENS (ver Configuración).

Aviso — Este proyecto fue completamente generado por IA con Cursor. No hay garantía ni responsabilidad; úsalo bajo tu propio riesgo.

Características

7 Stakeholders Preconfigurados: Líder Técnico, Gerente de Producto, Diseñador UX, Ingeniero de Seguridad, Ingeniero DevOps y dos personas de Usuario Final
Gestión de Personas en Tiempo de Ejecución: Crea, actualiza y elimina stakeholders en tiempo de ejecución
Soporte Multi-Proveedor de LLM: Usa OpenRouter para acceder a más de 100 modelos (GPT-4, Claude, Gemini, Llama, etc.)
Consulta Flexible: Consulta stakeholders individualmente o en grupos (modo paralelo o secuencial)
Múltiples Transportes: Soporte para stdio (predeterminado) y HTTP/SSE

Inicio Rápido

1. Instalar Dependencias

bun install

2. Configurar el Entorno

cp .env.example .env
# Edit .env and add your OpenRouter API key

Obtén una clave API de OpenRouter en: https://openrouter.ai/keys

3. Ejecutar el Servidor

bun start

El servidor usa transporte stdio, que es el estándar para clientes MCP como Claude Desktop.

Herramientas MCP

Herramienta	Descripción
`list_stakeholders`	Lista todas las personas disponibles con filtrado opcional
`get_stakeholder`	Obtén información detallada sobre un stakeholder específico
`consult_stakeholder`	Consulta a un stakeholder para obtener retroalimentación
`consult_group`	Consulta a múltiples stakeholders (paralelo o secuencial)
`create_stakeholder`	Crea un nuevo stakeholder en tiempo de ejecución
`update_stakeholder`	Actualiza un stakeholder existente
`delete_stakeholder`	Elimina un stakeholder en tiempo de ejecución

Ejemplos de Uso

Ejemplos de Prompts para Modelos de IA

Cuando uses el MCP con Claude, Cursor u otro asistente de IA, puedes indicar al modelo que use las herramientas de stakeholders. El modelo llamará al MCP (p. ej. list_stakeholders, consult_stakeholder, consult_group) en tu nombre.

Ejemplo completo: aplicación de aprendizaje de idiomas

El directorio examples/full-example-language-app/ contiene una ejecución completa del MCP en acción: un agente de IA (en Cursor) actúa como gerente de producto, consulta a múltiples stakeholders (usuarios finales, líder técnico, diseñador UX) para refinar funciones de vocabulario gamificado para una aplicación de idiomas, registra las conversaciones y produce PDRs (Documentos de Requisitos de Prompts). Útil para ver el flujo de trabajo de principio a fin y el tipo de resultados que puedes obtener de un solo prompt.

Planificando una nueva función

"Estoy planeando agregar un modo oscuro a nuestra aplicación. Consulta a los stakeholders relevantes (UX, producto, quizás técnico) y resume su retroalimentación antes de fijar el diseño."
"Estamos considerando cambiar nuestra autenticación de correo/contraseña a solo OAuth. Obtén retroalimentación del ingeniero de seguridad, el gerente de producto y una persona de usuario final, luego dame una recomendación."

Revisando un diseño o especificación

"He redactado una especificación para el nuevo flujo de pago (ver abajo). Pásala por el gerente de producto, el diseñador UX y la persona de usuario final senior. Usa modo secuencial para que cada uno pueda ver la retroalimentación anterior."
"Revisa este diseño de API con el líder técnico y el ingeniero DevOps. Pregúntales sobre preocupaciones de escalabilidad y despliegue."

Antes de implementar

"Antes de implementar esta función, lista los stakeholders cuya experiencia es relevante para [seguridad / UX / infraestructura], luego consúltalos sobre [pregunta específica]."
"Quiero lanzar una beta de nuestra aplicación móvil. Consulta al gerente de producto y a ambas personas de usuario final sobre qué deberíamos incluir en el primer lanzamiento."

Stakeholders personalizados

"Necesitamos aportes de accesibilidad. Crea un stakeholder que sea consultor de accesibilidad, luego pídele que revise nuestro diseño de botones y formularios."

Listar Stakeholders (llamada a herramienta)

{
  "tool": "list_stakeholders",
  "arguments": {
    "filter": {
      "expertise": "security"
    }
  }
}

Consultar a un Stakeholder (llamada a herramienta)

{
  "tool": "consult_stakeholder",
  "arguments": {
    "id": "tech-lead",
    "prompt": "What do you think about using microservices for a simple blog?",
    "context": {
      "projectDescription": "A personal blog with ~1000 monthly visitors"
    }
  }
}

Los stakeholders recuerdan la discusión (memoria de sesión)
Si tu agente hace una pregunta y luego una de seguimiento, el stakeholder no ve el primer mensaje a menos que pases un ID de sesión. Establece context.sessionId a un valor estable para la conversación (p. ej. un ID de tarea o ID de hilo). El servidor cargará consultas anteriores para esa sesión desde la base de datos y las inyectará en el prompt, para que el stakeholder vea las preguntas y respuestas anteriores y pueda responder seguimientos en contexto. Usa el mismo sessionId para la pregunta inicial y todos los seguimientos con ese stakeholder.

Consultar a Múltiples Stakeholders (llamada a herramienta)

{
  "tool": "consult_group",
  "arguments": {
    "ids": ["tech-lead", "product-manager", "ux-designer"],
    "prompt": "Review this feature proposal for user authentication",
    "mode": "sequential",
    "context": {
      "artifacts": [{
        "type": "spec",
        "content": "Users should be able to sign in with email/password or OAuth..."
      }]
    }
  }
}

Crear un Stakeholder Personalizado (llamada a herramienta)

{
  "tool": "create_stakeholder",
  "arguments": {
    "stakeholder": {
      "id": "accessibility-expert",
      "name": "Sam",
      "role": "Accessibility Consultant",
      "personality": {
        "traits": ["detail-oriented", "empathetic", "standards-focused"],
        "communication_style": "educational and supportive"
      },
      "expertise": ["WCAG compliance", "screen readers", "keyboard navigation"],
      "concerns": ["inclusive design", "legal compliance", "user independence"]
    }
  }
}

Stakeholders Predeterminados

ID	Nombre	Rol
`tech-lead`	Alex Chen	Líder Técnico
`product-manager`	Sarah Miller	Gerente de Producto
`ux-designer`	Marcus Rivera	Diseñador UX
`security-engineer`	Priya Sharma	Ingeniera de Seguridad
`devops-engineer`	Kenji Tanaka	Ingeniero DevOps
`end-user-millennial`	Jordan	Usuario Final (28, profesional urbano)
`end-user-senior`	Margaret	Usuario Final (67, maestra jubilada)

Configuración

Variables de Entorno

Variable	Descripción	Predeterminado
`OPENROUTER_API_KEY`	Tu clave API de OpenRouter	(requerida para llamadas LLM)
`DEFAULT_MODEL`	Modelo LLM predeterminado	`anthropic/claude-3-haiku`
`STAKEHOLDER_MCP_MAX_TOKENS`	Máximo de tokens por respuesta de consulta; reduce para bajar costos	`8192`
`DB_PATH`	Ruta SQLite para registros de consultas	`data/consultations.db`
`STAKEHOLDER_MCP_CONFIG_PATH`	Ruta al YAML de stakeholders (config específica del proyecto)	(ver Config específica del proyecto)
`STAKEHOLDER_MCP_DB_PATH`	Sobrescribir ruta de BD (p. ej. registros de consultas por proyecto)	igual que el predeterminado de `DB_PATH`
`STAKEHOLDER_MCP_RUNTIME_STORE_PATH`	Ruta para JSON de stakeholders en tiempo de ejecución (por proyecto)	derivada de la ruta de BD
`STAKEHOLDER_MCP_API_KEY`	Clave API para autenticación HTTP	(opcional)
`LOG_LEVEL`	Nivel de registro	`info`

Control del uso de tokens (máximo de tokens)

Las consultas llaman al LLM con un máximo predeterminado de 8192 tokens por respuesta para que los stakeholders puedan dar retroalimentación detallada y reflexiva. Puedes sobrescribir esto de dos maneras:

Variable de entorno — Establece STAKEHOLDER_MCP_MAX_TOKENS al límite deseado (p. ej. 2048 o 1024). El valor se limita a 128,000. Ejemplo en .env:
```
STAKEHOLDER_MCP_MAX_TOKENS=2048
```
Por solicitud — Las herramientas consult_stakeholder y consult_group aceptan un argumento opcional maxTokens; cuando se proporciona, sobrescribe el predeterminado solo para esa llamada.

Los stakeholders en tiempo de ejecución (creados mediante create_stakeholder o sobrescrituras de update_stakeholder) se persisten en un archivo JSON para que sobrevivan a los reinicios del servidor. Por predeterminado, el archivo es data/runtime-stakeholders.json (mismo directorio que DB_PATH). Puedes sobrescribir la ruta al crear el servidor mediante runtimeStakeholdersPath en ServerConfig.

Personalizando Stakeholders

Edita config/stakeholders.yaml para personalizar o agregar stakeholders:

stakeholders:
  - id: "my-stakeholder"
    name: "Custom Name"
    role: "Custom Role"
    model: "openai/gpt-4-turbo"  # Optional: per-stakeholder model
    personality:
      traits: ["trait1", "trait2"]
      communication_style: "description of how they communicate"
    expertise:
      - "area 1"
      - "area 2"
    concerns:
      - "priority 1"
      - "priority 2"

Configuración específica del proyecto

Puedes usar diferentes personas de stakeholders por proyecto apuntando el MCP a un archivo de configuración local del proyecto. De esa manera, cada repositorio obtiene su propio conjunto de stakeholders (p. ej. expertos de dominio, roles de producto) cuando usas el MCP desde Cursor u otra herramienta.

Opción 1: Convención (sin variables de entorno)
Si el servidor MCP se inicia con el proyecto como directorio de trabajo actual (típico al usar el MCP a nivel de proyecto de Cursor), buscará un archivo de configuración en este orden:

./.cursor/stakeholders.yaml (raíz del proyecto)
./config/stakeholders.yaml
./stakeholders.yaml

Entonces puedes agregar .cursor/stakeholders.yaml en tu proyecto con personas específicas del proyecto; ese archivo se usará automáticamente cuando el MCP se ejecute en ese proyecto.

Opción 2: Ruta explícita mediante entorno
Establece STAKEHOLDER_MCP_CONFIG_PATH en el env del MCP a la ruta del archivo de configuración de tu proyecto. Las rutas relativas se resuelven desde el directorio de trabajo del proceso (generalmente la raíz del proyecto al usar el MCP a nivel de proyecto de Cursor).

Ejemplo: MCP de Cursor a nivel de proyecto

En tu proyecto, crea .cursor/stakeholders.yaml con las personas para ese proyecto (o coloca stakeholders.yaml en la raíz del proyecto).
En el mismo proyecto, crea .cursor/mcp.json para que este proyecto use el MCP de stakeholders con esa configuración:

{
  "mcpServers": {
    "stakeholder-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/stakeholder-mcp/src/index.ts"],
      "env": {
        "OPENROUTER_API_KEY": "your-key-here",
        "STAKEHOLDER_MCP_CONFIG_PATH": ".cursor/stakeholders.yaml",
        "STAKEHOLDER_MCP_DB_PATH": ".cursor/data/consultations.db",
        "STAKEHOLDER_MCP_RUNTIME_STORE_PATH": ".cursor/data/runtime-stakeholders.json"
      }
    }
  }
}

Reemplaza /path/to/stakeholder-mcp con la ruta real al repositorio stakeholder-mcp. Si usas la convención anterior, puedes omitir STAKEHOLDER_MCP_CONFIG_PATH y solo establecer las rutas si deseas que los registros de consultas y los stakeholders en tiempo de ejecución se almacenen bajo .cursor/data/ para este proyecto.

Generando una configuración de proyecto
Copia el formato de config/stakeholders.yaml en este repositorio, o comienza desde un archivo mínimo:

stakeholders:
  - id: "domain-expert"
    name: "Jamie"
    role: "Domain Expert"
    personality:
      traits: ["pragmatic", "user-focused"]
      communication_style: "clear and concise"
    expertise:
      - "your domain"
    concerns:
      - "accuracy"
      - "usability"

Luego agrega o edita entradas para que coincidan con los roles y la experiencia que importan para el proyecto.

Configuración con herramientas compatibles con MCP

Claude Desktop

Agrega a tu configuración MCP de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "stakeholder-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/stakeholder-mcp/src/index.ts"],
      "env": {
        "OPENROUTER_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor

Agrega el servidor a tu configuración MCP. A nivel de usuario: Cursor Settings → MCP → Edit config (o ~/.cursor/mcp.json). A nivel de proyecto: .cursor/mcp.json en la raíz del repositorio.

{
  "mcpServers": {
    "stakeholder-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/stakeholder-mcp/src/index.ts"],
      "env": {
        "OPENROUTER_API_KEY": "your-key-here"
      }
    }
  }
}

Reemplaza /path/to/stakeholder-mcp con la ruta real a este proyecto.

Codex CLI

Codex CLI (y la extensión Codex VSCode) usan una configuración TOML compartida en ~/.codex/config.toml. Los servidores MCP se ejecutan como subprocesos locales sobre STDIO.

Crea el directorio de configuración (si no existe):
```
mkdir -p ~/.codex
```
Agrega el MCP de stakeholders a ~/.codex/config.toml:
```
[mcp_servers.stakeholder_mcp]
command = "bun"
args = ["run", "/path/to/stakeholder-mcp/src/index.ts"]
env = { "OPENROUTER_API_KEY" = "your-key-here" }
```
Reemplaza /path/to/stakeholder-mcp con la ruta real a este repositorio (p. ej. /Users/you/repos/stakeholder-mcp). Usa una ruta absoluta para que funcione desde cualquier directorio de trabajo.
Reinicia Codex (sesión CLI o extensión VSCode) para que recargue la configuración.

Luego en Codex puedes preguntar cosas como: "Lista los stakeholders y consulta al líder técnico sobre el uso de microservicios para un blog simple."

Desarrollo

# Run with watch mode
bun dev

# Run tests
bun test

# Type check
bun typecheck

# Test client (basic functionality)
bun run examples/test-client.ts

Licencia

MIT