MCP Issue - GitHub Issue Creator from Git Diff

Um servidor MCP (Model Context Protocol) que permite criar issues no GitHub automaticamente a partir de diffs do Git. Desenvolvido por Gustavo Detoni.

Sobre o Projeto

Este projeto é um servidor MCP que oferece ferramentas para:

• Gerar diffs do Git (working directory, staged changes ou range de commits)
• Criar prompts estruturados para gerar issues a partir de diffs
• Criar issues no GitHub automaticamente usando a API do GitHub

Funcionalidades

Ferramentas Disponíveis:

1. git_diff - Gera diffs do repositório Git

   • Suporte para diferentes modos: working, staged, range
   • Filtros por arquivos específicos
   • Controle de tamanho máximo do output

2. create_github_issue - Cria issues no GitHub

   • Integração com a API do GitHub via Octokit
   • Suporte a labels e assignees
   • Configuração de repositório padrão

Prompts Disponíveis:

1. draft_issue_from_diff - Converte diffs em rascunhos de issues estruturadas
   • Template padronizado com seções: Summary, Context, Observations, etc.
   • Detecção automática do tipo de mudança (bug/feat/chore/refactor)
   • Sugestão de labels apropriadas

Instalação

Pré-requisitos

• Node.js (versão 18+)
• pnpm
• Git configurado no sistema
• Token do GitHub com permissões para criar issues

Passos de Instalação

1. Clone o repositório:

git clone <url-do-repositorio>
cd mcp-issue

2. Instale as dependências:

pnpm install

3. Configure as variáveis de ambiente:

cp .env.example .env

Edite o arquivo .env com suas configurações:

GITHUB_TOKEN=seu_token_do_github
DEFAULT_OWNER=seu_usuario_ou_organizacao
DEFAULT_REPO=nome_do_repositorio_padrao

4. Compile o projeto:

pnpm run build

⚙️ Configuração no Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione a seguinte configuração no arquivo de configuração do Claude:

{
  "mcpServers": {
    "boxtime-mcp": {
      "command": "node",
      "args": [
        "C:\\Users\\gusta\\Desktop\\projects\\mcp-issue\\dist\\index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "seu_token_aqui",
        "DEFAULT_OWNER": "seu_usuario",
        "DEFAULT_REPO": "seu_repositorio"
      }
    }
  }
}

Importante: Substitua o caminho no array args pelo caminho absoluto correto para o arquivo dist/index.js no seu sistema.

Scripts Disponíveis

• pnpm run build - Compila o TypeScript
• pnpm run dev - Executa em modo desenvolvimento
• pnpm run start - Executa a versão compilada

Configuração do Token GitHub

Para obter um token do GitHub:

1. Acesse GitHub → Settings → Developer settings → Personal access tokens
2. Gere um novo token com as permissões:
   • repo (para repositórios privados)
   • public_repo (para repositórios públicos)
   • issues (para criar e gerenciar issues)

Template de Issue

O projeto usa um template estruturado para issues com as seguintes seções:

• Summary: Resumo conciso da implementação
• Context: Contexto da mudança ou problema resolvido
• Observations: Pontos importantes da implementação
• Acceptance Criteria: Critérios de aceitação baseados no diff
• Action Plan: Ações/tarefas implementadas
• Dependencies/Risks: Dependências e riscos identificados
• Technical Notes: Detalhes técnicos relevantes

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.