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

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": "queue", ... },
    { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "queue", ... }
  ],
  "total": 4
}

search

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

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "priority": ["high", "critical"],
  "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 prioridade e complexidade.

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

Retorno

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

[
  {
    "id": "tkt_abc123",
    "title": "Implement JWT token generation",
    "status": "queue",
    "priority": "high",
    "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": "todo", ... },
    "blockedBy": [
      { "id": "tkt_def456", "title": "Implement bcrypt hashing", "status": "in_progress" }
    ],
    "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, planning, specifying ou validating.

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

Retorno

A resposta depende da operação:

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

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

Operações de vinculação (add_dependencies, remove_dependency, create_blueprint, etc.): Retorna { id, message } ou a entidade vinculada.

Operações de consulta (get_ticket, get_status, gps): Retorna os dados solicitados — objeto ticket, status da sessão ou resumo de planejamento.

advance_phase: Retorna { previousPhase, newPhase, message }.

ℹ️ 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.

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": "in_progress",
    "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.

start_review_session

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

Retorno

action_review_session

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

Retorno

complete_review_session

Conclui o Implementation Review.

Retorno

Mutações

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

create_specification

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

Retorno

Retorna o objeto da especificação criada com todos os campos (veja retornos de get para Specification).

{
  "id": "spec_xyz789",
  "projectId": "proj_123",
  "title": "User Authentication System",
  "status": "draft",
  "progress": 0,
  ...
}

reopen_specification

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

Retorno

reset_work_session

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

Retorno

⚠️ 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.

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