Projetos

Código Aberto — O GitScrum MCP Server é código aberto sob a licença MIT. Disponível no npm e no GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor e qualquer cliente compatível com MCP têm acesso operacional completo à sua stack de gerenciamento de projetos.

A ferramenta project fornece 11 ações cobrindo gerenciamento do ciclo de vida do projeto e acesso a metadados. Além de criar e listar projetos, esta ferramenta é o gateway para configuração do projeto — workflows, tipos de tarefa, níveis de esforço, labels e membros da equipe. Esses endpoints de metadados são essenciais porque fornecem os IDs e nomes que outras ferramentas (especialmente task) requerem para criar e atualizar itens.

Entender as ações de metadados da ferramenta project é chave para uso eficaz do MCP. Quando você pede ao seu assistente de IA para criar uma tarefa com "alta prioridade" atribuída a "@sarah" na coluna "In Progress", o assistente primeiro consulta project action=efforts, project action=members e project action=workflows para resolver esses nomes legíveis nos IDs numéricos que a API espera. O servidor MCP lida com essa resolução automaticamente na maioria dos casos, mas conhecer as ações de metadados ajuda a entender como o sistema funciona.

Visão Geral das Ações

Criando Projetos

A ação create configura um novo projeto dentro de um workspace. O projeto fica imediatamente disponível para criação de tarefas, planejamento de sprints e colaboração da equipe.

Parâmetros Obrigatórios

Parâmetros Opcionais

Exemplos de Prompts

Você:  "Criar um novo projeto chamado 'Mobile App' no meu workspace"
IA:    Chama project action=create com name="Mobile App", company_slug

Você:  "Criar um projeto privado 'Auditoria de Segurança' vinculado à Acme Corp"
IA:    Chama project action=create com name, visibility="private", client_uuid

Você:  "Configurar um novo projeto 'API v3' com descrição 'Redesign da REST API para Q1'"
IA:    Chama project action=create com name, description

Encontrando e Listando Projetos

Listar

A ação list retorna todos os projetos dentro de um workspace. Você pode opcionalmente filtrar por status. Cada projeto na resposta inclui seu project_slug, que é necessário para todas as operações específicas do projeto.

Você:  "Listar todos os projetos no meu workspace"
IA:    Chama project action=list → retorna projetos com slugs e estatísticas

Você:  "Mostrar apenas projetos ativos"
IA:    Chama project action=list com status="in_progress"

Você:  "Quais projetos estão arquivados?"
IA:    Chama project action=list com status="archived"

Encontrar

A ação find busca um projeto por nome em todos os seus workspaces. Isso é útil quando você sabe o nome do projeto mas não o slug ou workspace. O parâmetro company_slug é opcional — se omitido, a busca cobre todos os workspaces acessíveis.

Você:  "Encontrar o projeto Backend"
IA:    Chama project action=find com name="Backend" → retorna projeto com slug e workspace

Você:  "Em qual workspace está o projeto Mobile App?"
IA:    Chama project action=find com name="Mobile App" → retorna informações do workspace

Detalhes e Estatísticas do Projeto

Obter

A ação get retorna o objeto completo do projeto — nome, descrição, configurações, datas, tamanho da equipe e links. Isso fornece o contexto completo sobre um projeto.

Você:  "Mostrar detalhes do projeto Backend"
IA:    Chama project action=get → retorna configuração completa e metadados do projeto

Estatísticas

A ação stats retorna estatísticas no nível do projeto — total de tarefas, taxas de conclusão, sprints ativos, atividade da equipe e mais. Esses números alimentam o dashboard do projeto na aplicação web GitScrum.

Você:  "Mostrar estatísticas do projeto Mobile App"
IA:    Chama project action=stats → retorna contagem de tarefas, taxas de conclusão, dados de sprint

Você:  "Qual projeto tem mais tarefas abertas?"
IA:    Lista projetos → chama stats para cada → compara contagem de tarefas abertas

Tarefas

A ação tasks retorna todas as tarefas dentro de um projeto. Enquanto a ação filter da ferramenta task fornece filtragem mais granular, a ação tasks do projeto é uma forma rápida de obter uma visão geral de todos os itens de trabalho.

Você:  "Mostrar todas as tarefas no projeto Backend"
IA:    Chama project action=tasks → retorna lista completa de tarefas

Metadados do Projeto

As ações de metadados são a ponte entre nomes legíveis e os IDs numéricos que a API do GitScrum requer. Quando seu assistente de IA cria ou atualiza tarefas, ele depende desses endpoints para traduzir sua linguagem natural em chamadas de API precisas.

Workflows (Colunas Kanban)

A ação workflows retorna as colunas do quadro Kanban do projeto com seus IDs e títulos. Cada entrada de workflow representa uma coluna no quadro — "To Do", "In Progress", "Code Review", "Done", etc.

Por que importa: Quando você diz "mover esta tarefa para In Progress", o assistente de IA precisa do workflow_id da coluna "In Progress". O servidor MCP lida com essa resolução automaticamente quando você usa o parâmetro column na ferramenta task, mas entender workflows ajuda a configurar quadros e resolver problemas de colunas.

Você:  "Quais são as colunas disponíveis no projeto Backend?"
IA:    Chama project action=workflows → retorna lista de colunas:
      [{ id: 1, title: "Backlog" }, { id: 2, title: "In Progress" }, { id: 3, title: "Done" }]

Você:  "Quais estágios de workflow o projeto Mobile App usa?"
IA:    Chama project action=workflows → retorna a configuração Kanban do projeto

Tipos (Tipos de Tarefa)

A ação types retorna os tipos de tarefa disponíveis — Feature, Bug, Improvement, Chore, etc. Cada tipo tem um id e title.

Por que importa: Quando você diz "criar um bug", o assistente de IA precisa do typeid para o tipo "Bug". O servidor MCP usa isso para definir o campo typeid na tarefa.

Você:  "Quais tipos de tarefa estão disponíveis neste projeto?"
IA:    Chama project action=types → retorna lista de tipos:
      [{ id: 1, title: "Feature" }, { id: 2, title: "Bug" }, { id: 3, title: "Improvement" }]

Esforços (Níveis de Prioridade)

A ação efforts retorna os níveis de esforço ou prioridade disponíveis — Low, Medium, High, Critical, etc. Cada esforço tem um id e title.

Por que importa: Quando você diz "criar uma tarefa de alta prioridade", o assistente de IA precisa do effortid para o nível "High". O servidor MCP usa isso para definir o campo effortid na tarefa.

Você:  "Quais níveis de prioridade estão disponíveis?"
IA:    Chama project action=efforts → retorna lista de esforços:
      [{ id: 1, title: "Low" }, { id: 2, title: "Medium" }, { id: 3, title: "High" }]

Labels

A ação labels retorna todos os labels configurados para o projeto, cada um com um id e title. Labels são usados para categorização e filtragem de tarefas.

Por que importa: Quando você diz "rotular esta tarefa como 'frontend' e 'urgent'", o assistente de IA precisa dos label_ids para esses labels. A ação filter da ferramenta task também resolve nomes de labels automaticamente, mas conhecer os labels disponíveis ajuda a organizar o trabalho efetivamente.

Você:  "Quais labels estão disponíveis neste projeto?"
IA:    Chama project action=labels → retorna lista de labels:
      [{ id: 1, title: "frontend" }, { id: 2, title: "backend" }, { id: 3, title: "urgent" }]

Membros

A ação members retorna todos os membros da equipe atribuídos ao projeto, incluindo nome de exibição, nome de usuário, URL do avatar e papel. Nomes de usuário são usados para atribuição de tarefas.

Por que importa: Quando você diz "atribuir isto a @sarah", o assistente de IA precisa verificar que "sarah" é um nome de usuário válido na lista de membros do projeto. O parâmetro usernames na ferramenta task aceita esses valores diretamente.

Você:  "Quem são os membros da equipe neste projeto?"
IA:    Chama project action=members → retorna lista de membros:
      [{ name: "Sarah Chen", username: "sarah", role: "developer" }, ...]

Você:  "A quem posso atribuir tarefas no projeto Backend?"
IA:    Chama project action=members → lista membros da equipe atribuíveis

Fluxo de Resolução de Metadados

Veja como o assistente de IA usa metadados para criar uma tarefa totalmente configurada:

Você:  "Criar um bug de alta prioridade 'Timeout no login' atribuído a @sarah
       na coluna In Progress do projeto Backend"

IA internamente:
  1. project action=efforts   → encontra "High" → effort_id=3
  2. project action=workflows → encontra "In Progress" → workflow_id=2
  3. project action=members   → valida que "sarah" existe
  4. task action=create       → passa title, effort_id=3, column="In Progress",
                                 usernames=["sarah"], is_bug=true

Na prática, o servidor MCP lida com grande parte dessa resolução automaticamente. Quando você passa column: "In Progress" para a ferramenta task, ela busca workflows internamente e resolve o ID. Mas entender esse fluxo ajuda na depuração ou quando o assistente de IA faz perguntas de esclarecimento sobre opções disponíveis.

Workflow de Configuração de Projeto

Ao configurar um novo projeto pelo MCP, siga esta sequência:

1. Criar o projeto

Você:  "Criar um projeto chamado 'Mobile App' com descrição 'Cliente iOS e Android'"
IA:    Chama project action=create → retorna project_slug

2. Revisar configuração padrão

Novos projetos vêm com workflows, tipos e esforços padrão. Verifique o que está disponível.

Você:  "Mostrar workflows, tipos e níveis de esforço do Mobile App"
IA:    Chama workflows, types, efforts → exibe a configuração do projeto

3. Começar a criar tarefas

Use os metadados da etapa 2 para criar tarefas bem configuradas.

Você:  "Criar uma tarefa 'Design da tela inicial' como Feature, prioridade média, atribuir a @alex"
IA:    Usa metadados armazenados → cria tarefa com IDs corretos

4. Monitorar progresso

Acompanhe a saúde do projeto através de estatísticas.

Você:  "Como está o projeto Mobile App?"
IA:    Chama project action=stats → resume conclusão de tarefas, sprints ativos, atividade da equipe

Resolução Automática de Contexto

A ferramenta project suporta resolução automática de contexto. Se seu assistente de IA conhece o projectslug mas não o companyslug, ele tenta resolver o workspace automaticamente buscando em seus workspaces acessíveis. Isso significa que você pode frequentemente referenciar projetos por nome em vez de fornecer ambos os slugs explicitamente.

A ação find é particularmente útil aqui — ela busca por nome do projeto e retorna tanto o projectslug quanto o companyslug, estabelecendo contexto para todas as operações subsequentes na conversa.

Visibilidade e Permissões

A visibilidade do projeto determina quem pode acessar o projeto dentro de um workspace:

• Público — Todos os membros do workspace podem ver o projeto e suas tarefas. Este é o padrão.
• Privado — Apenas membros explicitamente convidados podem acessar o projeto. Projetos privados não aparecem em listagens de tarefas do workspace para não-membros.

O servidor MCP respeita essas regras de visibilidade. Se você não tem acesso a um projeto privado, ele não aparecerá nos resultados de list e chamadas diretas de get falharão com erro de permissão.

Próximos Passos

• Tarefas: Crie e gerencie tarefas dentro dos seus projetos.
• Sprints: Planeje e acompanhe sprints para entrega iterativa.
• Controle de Tempo: Acompanhe tempo em tarefas de projetos.
• Início Rápido: Configure o servidor MCP se ainda não o fez.