Ferramentas MCP

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

O SpecForge expõe 17 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"
}

Retorno

Retorna o objeto completo da entidade. O formato depende do parâmetro type:

Ticket (type: "ticket"):

Specification (type: "specification"):

Epic (type: "epic"):

Project (type: "project"):

list

Lista entidades de um tipo dado com filtros opcionais.

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

Retorno

Retorna uma lista paginada:

Cada item em items é o objeto completo da entidade (veja retornos de get acima para detalhes dos campos).

{
  "items": [
    { "id": "tkt_abc123", "title": "Set up User model", "status": "ready", ... },
    { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "pending", ... }
  ],
  "total": 4
}

search

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

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "complexity": ["large", "xlarge"],
  "limit": 10
}

Retorno

Retorna uma lista paginada de tickets:

Ao usar o parâmetro fields, apenas os campos solicitados são incluídos em cada objeto ticket.

✅ 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 complexidade.

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

Retorno

Retorna um array de objetos ticket em status ready com todas as dependências satisfeitas, ordenados por complexidade (menor primeiro).

[
  {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "ready",
    "complexity": "medium",
    "epicId": "epic_456",
    "ticketNumber": 3,
    ...
  }
]

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.

Retorno

Retorna um array de entradas de tickets bloqueados:

[
  {
    "ticket": { "id": "tkt_ghi789", "title": "Build login endpoint", "status": "pending", ... },
    "blockedBy": [
      { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "active" }
    ],
    "daysBlocked": 2
  }
]

get_report

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

Retorno

O formato da resposta varia por tipo de relatório:

implementation — Resumo de progresso:

time — Rastreamento de tempo:

blockers — Análise de bloqueadores:

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 ou planning.

Retorno

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 25 operações distintas. Cada operação é passada como um objeto operation cujo type é o nome da operação; os campos restantes são o payload dessa operação.

Para ler um único ticket, use a ferramenta get (type: "ticket") em vez de uma operação de planejamento.

Operações de Especificação e Estrutura

Operações de Blueprint

Operações de Vínculo de Passo

Operações de Dependência

Operações de Justificativa e Eleição

Operação de Status

Exemplo — Criando um ticket:

{
  "specificationId": "spec_xyz789",
  "operation": {
    "type": "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"
  }
}

Retorno

A resposta depende da operação:

Operações de estrutura (create_epic, create_ticket, update_epic, ticket_general_actions, …): Retorna o objeto da entidade criada ou atualizada.

Operações de exclusão (delete_epic, delete_ticket, delete_blueprint): Retorna confirmação { id, message }.

Operações de vinculação (create_dependencies, link_blueprint_to_tickets, link_step_file, …): Retorna { id, message } ou a entidade vinculada.

Operação de status (get_planning_status): Retorna o status atual da sessão de planejamento e o progresso das fases.

ℹ️ A especificação permanece no único estado planning durante toda a sessão. A máquina de planejamento de 7 fases (planning_spec → epic_decomposition → epic_expansion → ticket_decomposition → ticket_expansion → cross_validation → planned) avança na sessão de planejamento, não na especificação. Você não gerencia essas fases manualmente.

complete_planning_session

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

Retorno

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.

Retorno

Retorna o contexto completo de implementação:

{
  "ticket": {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "active",
    "acceptanceCriteria": [
      { "id": "ac-0", "description": "Tokens are signed with RS256", "validated": false }
    ],
    "implementation": {
      "steps": [
        { "order": 1, "title": "Create JwtService", "action": "create", "detail": "..." }
      ]
    },
    ...
  },
  "epic": { "id": "epic_456", "title": "Token Management", ... },
  "specification": { "id": "spec_xyz789", "title": "Auth System", ... },
  "dependencies": { "blockedBy": [], "blocks": [...] },
  "relatedTickets": [...],
  "previousAttempts": [],
  "relatedDiscoveries": []
}

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

Retorno

Retorna confirmação com o estado atualizado da work session:

complete_work_session

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

Retorno

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

Mutações

Duas ferramentas para modificar e vincular dados do projeto.

reopen_specification

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

Retorno

link_pull_request

Associa um pull request a um ticket completado.

Retorno

Retorna o objeto link criado:

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.

Retorno

get_dependency_tree

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

Retorno

Retorna uma estrutura de árvore mostrando todos os tickets, suas dependências e status:

Útil para visualizar a forma geral do trabalho e identificar gargalos.

Utilitário

feedback

Submeta feedback, reporte problemas ou sugira melhorias.

Retorno

Depende da operação:

• submit: Retorna { id, message } — o ID do feedback e confirmação.
• list: Retorna um array de entradas de feedback com id, category, summary, status, createdAt.
• get: Retorna a entrada completa do feedback por ID.

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