# GitHub MCP Server

Servidor MCP (Model Context Protocol) customizado, escrito em TypeScript, que conecta o Claude à API REST do GitHub.

## O que ele faz

Expõe 6 ferramentas (tools) que o Claude pode chamar:

| Tool | Descrição |
|---|---|
| `list_repos` | Lista repositórios do usuário autenticado |
| `get_repo` | Detalhes de um repositório específico |
| `list_issues` | Lista issues de um repositório |
| `create_issue` | Cria uma issue nova |
| `get_file_content` | Lê o conteúdo de um arquivo do repositório |
| `search_code` | Busca código no GitHub |

## 1. Gerar um GitHub Personal Access Token

1. Acesse **GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens**
2. Crie um token com permissões mínimas necessárias:
   - `Contents: Read` (para `get_file_content`)
   - `Issues: Read and write` (para `list_issues`/`create_issue`)
   - `Metadata: Read` (obrigatório sempre)
3. Copie o token gerado (começa com `github_pat_...`)

> Dica de segurança: nunca commite o token no repositório. Use variável de ambiente.

## 2. Instalar e buildar

```bash
npm install
npm run build
```

Isso gera `build/index.js`, que é o executável do servidor (comunica via stdio, protocolo padrão do MCP).

## 3. Testar localmente (opcional, sem Claude)

```bash
export GITHUB_PERSONAL_ACCESS_TOKEN="seu_token_aqui"
npm start
```

Se aparecer `GitHub MCP server rodando via stdio.` no stderr, está funcionando. Para testar as tools interativamente, use o [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

## 4. Conectar ao Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Adicione:

```json
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/caminho/absoluto/para/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "seu_token_aqui"
      }
    }
  }
}
```

Reinicie o Claude Desktop. As ferramentas do GitHub devem aparecer no ícone de ferramentas (🔨) da conversa.

## 5. Próximos passos (ideias para expandir e turbinar o portfólio)

- Adicionar tools de escrita: `create_pull_request`, `merge_pull_request`, `create_branch`
- Adicionar paginação real (cursor-based) em vez de só `per_page`
- Rate limiting e cache (o GitHub limita a 5000 req/h autenticado)
- Testes automatizados com Vitest/Jest
- CI com GitHub Actions rodando lint + testes + build a cada push
- Publicar como pacote npm (`npx github-mcp-server`)
- Dockerizar o servidor (bom gancho pra conectar com seus outros projetos DevOps)

## Estrutura do projeto

```
github-mcp-server/
├── src/
│   └── index.ts      # lógica do servidor e definição das tools
├── build/             # gerado pelo `npm run build`
├── package.json
├── tsconfig.json
└── README.md
```