stakeholder-mcp

Permita que seu agente de IA tenha conversas com diferentes personas sobre funcionalidades e detalhes de implementação.

Documentação

Stakeholder MCP Server

Um servidor MCP (Model Context Protocol) que expõe personas de stakeholders como ferramentas para feedback iterativo de produto. Cada stakeholder representa um papel distinto com personalidade, experiência e preocupações únicas.

Preocupado com custos? O servidor usa um limite de tokens padrão alto para que os modelos possam raciocinar sobre requisitos e implementação. Para controlar custos, defina STAKEHOLDER_MCP_MAX_TOKENS (veja Configuração).

Aviso — Este projeto foi totalmente gerado por IA com Cursor. Não há garantia ou responsabilidade; use por sua conta e risco.

Recursos

7 Stakeholders Pré-configurados: Tech Lead, Product Manager, UX Designer, Security Engineer, DevOps Engineer e duas personas de Usuário Final
Gerenciamento de Personas em Tempo de Execução: Crie, atualize e exclua stakeholders em tempo de execução
Suporte a LLM Multi-Provedor: Usa OpenRouter para acesso a mais de 100 modelos (GPT-4, Claude, Gemini, Llama, etc.)
Consulta Flexível: Consulte stakeholders individualmente ou em grupos (modo paralelo ou sequencial)
Múltiplos Transportes: Suporte a stdio (padrão) e HTTP/SSE

Início Rápido

1. Instalar Dependências

bun install

2. Configurar Ambiente

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

Obtenha uma chave de API OpenRouter em: https://openrouter.ai/keys

3. Executar o Servidor

bun start

O servidor usa transporte stdio, que é o padrão para clientes MCP como Claude Desktop.

Ferramentas MCP

Ferramenta	Descrição
`list_stakeholders`	Lista todas as personas disponíveis com filtragem opcional
`get_stakeholder`	Obtém informações detalhadas sobre um stakeholder específico
`consult_stakeholder`	Consulta um stakeholder para obter feedback
`consult_group`	Consulta vários stakeholders (paralelo ou sequencial)
`create_stakeholder`	Cria um novo stakeholder em tempo de execução
`update_stakeholder`	Atualiza um stakeholder existente
`delete_stakeholder`	Exclui um stakeholder em tempo de execução

Exemplos de Uso

Exemplos de Prompts para Modelos de IA

Ao usar o MCP com Claude, Cursor ou outro assistente de IA, você pode instruir o modelo a usar as ferramentas de stakeholder. O modelo então chamará o MCP (por exemplo, list_stakeholders, consult_stakeholder, consult_group) em seu nome.

Exemplo completo: aplicativo de aprendizado de idiomas

O diretório examples/full-example-language-app/ contém uma execução completa do MCP em ação: um agente de IA (no Cursor) atua como gerente de produto, consulta vários stakeholders (usuários finais, tech lead, UX designer) para refinar recursos de vocabulário gamificado para um aplicativo de idiomas, registra as conversas e produz PDRs (Prompt Requirements Documents). Útil para ver o fluxo de trabalho de ponta a ponta e o tipo de saídas que você pode obter com um único prompt.

Planejando um novo recurso

"Estou planejando adicionar um botão de modo escuro ao nosso aplicativo. Consulte os stakeholders relevantes (UX, produto, talvez tech) e resuma o feedback deles antes de fecharmos o design."
"Estamos considerando mudar nossa autenticação de e-mail/senha para apenas OAuth. Obtenha feedback do security engineer, do product manager e de uma persona de usuário final, e depois me dê uma recomendação."

Revisando um design ou especificação

"Elaborei uma especificação para o novo fluxo de checkout (veja abaixo). Passe para o product manager, o UX designer e a persona de usuário final sênior. Use o modo sequencial para que cada um veja o feedback anterior."
"Revise este design de API com o tech lead e o DevOps engineer. Pergunte sobre preocupações de escalabilidade e implantação."

Antes de implementar

"Antes de implementar este recurso, liste os stakeholders cuja experiência é relevante para [segurança / UX / infraestrutura] e depois consulte-os sobre [pergunta específica]."
"Quero lançar um beta do nosso aplicativo móvel. Consulte o product manager e as duas personas de usuário final sobre o que devemos incluir no primeiro lançamento."

Stakeholders personalizados

"Precisamos de contribuições sobre acessibilidade. Crie um stakeholder que seja consultor de acessibilidade e peça para ele revisar nosso design de botões e formulários."

Listar Stakeholders (chamada de ferramenta)

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

Consultar um Stakeholder (chamada de ferramenta)

{
  "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"
    }
  }
}

Stakeholders lembram da discussão (memória de sessão)
Se seu agente fizer uma pergunta e depois uma pergunta de acompanhamento, o stakeholder não verá a primeira mensagem, a menos que você passe um ID de sessão. Defina context.sessionId para um valor estável para a conversa (por exemplo, um ID de tarefa ou ID de thread). O servidor carregará consultas anteriores para essa sessão do banco de dados e as injetará no prompt, para que o stakeholder veja o Q&A anterior e possa responder às perguntas de acompanhamento no contexto. Use o mesmo sessionId para a pergunta inicial e todas as perguntas de acompanhamento com esse stakeholder.

Consultar Vários Stakeholders (chamada de ferramenta)

{
  "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..."
      }]
    }
  }
}

Criar um Stakeholder Personalizado (chamada de ferramenta)

{
  "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 Padrão

ID	Nome	Papel
`tech-lead`	Alex Chen	Tech Lead
`product-manager`	Sarah Miller	Product Manager
`ux-designer`	Marcus Rivera	UX Designer
`security-engineer`	Priya Sharma	Security Engineer
`devops-engineer`	Kenji Tanaka	DevOps Engineer
`end-user-millennial`	Jordan	Usuário Final (28, profissional urbano)
`end-user-senior`	Margaret	Usuária Final (67, professora aposentada)

Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
`OPENROUTER_API_KEY`	Sua chave de API OpenRouter	(obrigatória para chamadas LLM)
`DEFAULT_MODEL`	Modelo LLM padrão	`anthropic/claude-3-haiku`
`STAKEHOLDER_MCP_MAX_TOKENS`	Máximo de tokens por resposta de consulta; reduza para diminuir custos	`8192`
`DB_PATH`	Caminho SQLite para logs de consulta	`data/consultations.db`
`STAKEHOLDER_MCP_CONFIG_PATH`	Caminho para o YAML de stakeholders (config específica do projeto)	(veja Configuração específica do projeto)
`STAKEHOLDER_MCP_DB_PATH`	Sobrescrever caminho do banco de dados (ex.: logs de consulta por projeto)	igual ao padrão de `DB_PATH`
`STAKEHOLDER_MCP_RUNTIME_STORE_PATH`	Caminho para o JSON de stakeholders em tempo de execução (por projeto)	derivado do caminho do banco de dados
`STAKEHOLDER_MCP_API_KEY`	Chave de API para autenticação HTTP	(opcional)
`LOG_LEVEL`	Nível de log	`info`

Controlando o uso de tokens (máximo de tokens)

As consultas chamam o LLM com um máximo padrão de 8192 tokens por resposta, para que os stakeholders possam dar feedback detalhado e cuidadoso. Você pode sobrescrever isso de duas maneiras:

Variável de ambiente — Defina STAKEHOLDER_MCP_MAX_TOKENS para o limite desejado (ex.: 2048 ou 1024). O valor é limitado a 128.000. Exemplo em .env:
```
STAKEHOLDER_MCP_MAX_TOKENS=2048
```
Por solicitação — As ferramentas consult_stakeholder e consult_group aceitam um argumento opcional maxTokens; quando fornecido, ele sobrescreve o padrão apenas para essa chamada.

Stakeholders em tempo de execução (criados via create_stakeholder ou sobrescritas de update_stakeholder) são persistidos em um arquivo JSON para sobreviverem a reinicializações do servidor. Por padrão, o arquivo é data/runtime-stakeholders.json (mesmo diretório de DB_PATH). Você pode sobrescrever o caminho ao criar o servidor via runtimeStakeholdersPath em ServerConfig.

Personalizando Stakeholders

Edite config/stakeholders.yaml para personalizar ou adicionar 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"

Configuração específica do projeto

Você pode usar personas de stakeholders diferentes por projeto apontando o MCP para um arquivo de configuração local do projeto. Assim, cada repositório terá seu próprio conjunto de stakeholders (ex.: especialistas de domínio, papéis de produto) quando você usar o MCP a partir do Cursor ou de outra ferramenta.

Opção 1: Convenção (sem variáveis de ambiente)
Se o servidor MCP for iniciado com o projeto como diretório de trabalho atual (típico ao usar o MCP de nível de projeto do Cursor), ele procurará um arquivo de configuração nesta ordem:

./.cursor/stakeholders.yaml (raiz do projeto)
./config/stakeholders.yaml
./stakeholders.yaml

Então você pode adicionar .cursor/stakeholders.yaml no seu projeto com personas específicas do projeto; esse arquivo será usado automaticamente quando o MCP rodar nesse projeto.

Opção 2: Caminho explícito via env
Defina STAKEHOLDER_MCP_CONFIG_PATH no env do MCP para o caminho do arquivo de configuração do seu projeto. Caminhos relativos são resolvidos a partir do diretório de trabalho do processo (geralmente a raiz do projeto ao usar o MCP de nível de projeto do Cursor).

Exemplo: MCP de nível de projeto no Cursor

No seu projeto, crie .cursor/stakeholders.yaml com as personas para esse projeto (ou coloque stakeholders.yaml na raiz do projeto).
No mesmo projeto, crie .cursor/mcp.json para que este projeto use o MCP de stakeholders com essa configuração:

{
  "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"
      }
    }
  }
}

Substitua /path/to/stakeholder-mcp pelo caminho real para o repositório stakeholder-mcp. Se você usar a convenção acima, pode omitir STAKEHOLDER_MCP_CONFIG_PATH e definir os caminhos apenas se quiser que os logs de consulta e os stakeholders em tempo de execução sejam armazenados em .cursor/data/ para este projeto.

Gerando uma configuração de projeto
Copie o formato de config/stakeholders.yaml neste repositório, ou comece com um arquivo 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"

Depois adicione ou edite entradas para corresponder aos papéis e à experiência que importam para o projeto.

Configurando com ferramentas compatíveis com MCP

Claude Desktop

Adicione à sua configuração MCP do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

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

Cursor

Adicione o servidor à sua configuração MCP. Nível de usuário: Cursor Settings → MCP → Edit config (ou ~/.cursor/mcp.json). Nível de projeto: .cursor/mcp.json na raiz do repositório.

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

Substitua /path/to/stakeholder-mcp pelo caminho real para este projeto.

Codex CLI

O Codex CLI (e a extensão Codex VSCode) usam uma configuração TOML compartilhada em ~/.codex/config.toml. Os servidores MCP rodam como subprocessos locais via STDIO.

Crie o diretório de configuração (se não existir):
```
mkdir -p ~/.codex
```
Adicione o 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" }
```
Substitua /path/to/stakeholder-mcp pelo caminho real para este repositório (ex.: /Users/you/repos/stakeholder-mcp). Use um caminho absoluto para que funcione a partir de qualquer diretório de trabalho.
Reinicie o Codex (sessão CLI ou extensão VSCode) para que ele recarregue a configuração.

Depois, no Codex, você pode perguntar coisas como: "Liste os stakeholders e consulte o tech lead sobre usar microserviços para um blog simples."

Desenvolvimento

# Run with watch mode
bun dev

# Run tests
bun test

# Type check
bun typecheck

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

Licença

MIT