Ferramentas MCP

Referência completa de todas as 22 ferramentas MCP do SpecForge — parâmetros, uso e exemplos.

O SpecForge expõe 22 ferramentas MCP organizadas em cinco categorias. Essas ferramentas estão disponíveis para qualquer agente de código compatível com MCP (Claude Code, Cursor, VS Code com Copilot, Gemini CLI, etc.) uma vez que o servidor MCP do SpecForge esteja configurado.

Consultas

Seis ferramentas para ler dados do projeto, buscar tickets e gerar relatórios. São somente leitura — nunca modificam sua especificação.

get

Recupera uma única entidade por tipo e ID.

{
  "type": "ticket",
  "id": "tkt_abc123",
  "specificationId": "spec_xyz789"
}

Retorna o objeto completo do ticket incluindo título, descrição, passos, critérios de aceite, dependências, status, complexidade, prioridade, tags e expectativas de arquivo.

list

Lista entidades de um tipo dado com filtros opcionais.

{
  "type": "tickets",
  "specificationId": "spec_xyz789",
  "epicId": "epic_456"
}

Retorna um array de todos os tickets pertencentes ao épico especificado.

search

Busca unificada em tickets com consultas full-text e filtros estruturados.

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "priority": ["high", "critical"],
  "limit": 10
}

✅ Combine files com tags para encontrar todos os tickets tocando uma parte específica do seu codebase. Por exemplo, files: ["src/auth/**"] com tags: ["security"].

get_next_actionable_tickets

Retorna tickets em status ready com todas as dependências satisfeitas, ordenados por prioridade e complexidade.

{
  "specificationId": "spec_xyz789",
  "limit": 5
}

Este é o ponto de entrada principal para agentes decidindo no que trabalhar a seguir. No Agent Teams, o orquestrador chama isso para atribuir tickets a workers.

get_blocked_tickets

Retorna tickets em status pending junto com os motivos pelos quais estão bloqueados.

Cada ticket bloqueado inclui suas dependências não resolvidas e quaisquer motivos de bloqueio externo.

get_report

Gera relatórios analíticos em diferentes escopos e intervalos de tempo.

Ciclo de Vida

Nove ferramentas que conduzem especificações através de planejamento, implementação e revisão. São as ferramentas centrais do fluxo de trabalho.

start_planning_session

Abre uma sessão de planejamento para uma especificação, habilitando mudanças estruturais.

A especificação deve estar em estado draft, planning, specifying ou validating.

action_planning_session

Realiza operações dentro de uma sessão de planejamento ativa. Esta é a ferramenta principal para construir especificações — ela lida com 18 operações distintas.

Parâmetros adicionais dependem da operação.

Operações de Estrutura

Operações de Vinculação

Operações de Consulta e Controle

Exemplo — Criando um ticket:

{
  "specificationId": "spec_xyz789",
  "operation": "create_ticket",
  "epicId": "epic_456",
  "title": "Implement JWT token generation",
  "description": "Create a service that generates signed JWT access tokens with configurable expiration.",
  "complexity": "medium",
  "priority": "high",
  "steps": [
    "Create JwtService class in src/auth/jwt.service.ts",
    "Implement generateAccessToken method with RS256 signing",
    "Add token expiration configuration via environment variables",
    "Write unit tests for token generation and validation"
  ],
  "acceptanceCriteria": [
    "Tokens are signed with RS256 algorithm",
    "Token expiration is configurable",
    "Invalid tokens are rejected with clear error messages"
  ]
}

ℹ️ A especificação transiciona automaticamente entre os estados planning, specifying e validating baseado nas operações que você realiza. Você não gerencia essas transições manualmente.

complete_planning_session

Encerra a sessão de planejamento e dispara o gate de Planning Review.

Se o gate de Planning Review está habilitado e a especificação passa, ela avança para ready.

start_work_session

Inicia trabalho de implementação em um ticket específico.

Transiciona o ticket de ready para active. Retorna o contexto completo do ticket: passos de implementação, critérios de aceite, expectativas de arquivo, outputs de dependência e blueprints vinculados.

action_work_session

Registra progresso, resultados e descobertas durante a implementação.

{
  "ticketId": "tkt_abc123",
  "steps": [
    { "index": 0, "completed": true },
    { "index": 1, "completed": true }
  ],
  "files": [
    { "path": "src/auth/jwt.service.ts", "action": "created" },
    { "path": "src/auth/jwt.service.test.ts", "action": "created" }
  ],
  "notes": "Used jose library instead of jsonwebtoken for Edge Runtime compatibility."
}

complete_work_session

Finaliza trabalho em um ticket com um resumo e resultados de validação.

Transiciona o ticket de active para done. Tickets dependentes são recalculados e podem se tornar ready.

start_review_session

Inicia uma sessão de Implementation Review para uma especificação.

action_review_session

Endereça achados durante uma sessão de review ativa.

complete_review_session

Conclui o Implementation Review.

Mutações

Quatro ferramentas para criar, modificar e vincular dados do projeto.

create_specification

Cria uma nova especificação dentro de um projeto.

reopen_specification

Reabre uma especificação completada ou revisada para trabalho adicional.

reset_work_session

Reseta tickets completados de volta a um estado trabalhável.

⚠️ Resetar tickets limpa dados de work session. Commits e PRs vinculados são preservados, mas conclusões de passos, notas e resultados de critérios de aceite são removidos. O reset cascateia para tickets dependentes.

link_pull_request

Associa um pull request a um ticket completado.

Orquestração

Duas ferramentas para entender e navegar o grafo de dependência.

get_critical_path

Calcula a cadeia de dependência mais longa em uma especificação — a sequência de tickets que determina o tempo mínimo para conclusão.

Retorna uma lista ordenada de tickets formando o caminho crítico, junto com o esforço total estimado.

get_dependency_tree

Renderiza a árvore de dependência completa upstream e downstream para uma especificação.

Retorna uma estrutura de árvore mostrando todos os tickets, suas dependências e status atuais. Útil para visualizar a forma geral do trabalho e identificar gargalos.

Utilitário

feedback

Submeta feedback, reporte problemas ou sugira melhorias.

Veja Também

• Comandos CLI — Equivalentes CLI para operações comuns
• Estados da Especificação — Máquina de estados disparada por ferramentas de ciclo de vida
• Estados do Ticket — Estados de ticket acionados por ferramentas de work session