Phabricator

Interaja com o Phabricator para gerenciamento de tarefas e fluxos de trabalho de revisão de código.

Documentação

Servidor MCP do Phabricator

Um servidor abrangente do Model Context Protocol (MCP) que permite que assistentes de IA interajam de forma inteligente com o Phabricator para fluxos de trabalho avançados de gerenciamento de tarefas e revisão de código.

✨ Recursos

🔑 Autenticação Pessoal

Autenticação por Usuário: Configure seu token de API pessoal do Phabricator no seu cliente MCP
Atribuição de Usuário: Comentários e revisões aparecem sob SEU nome em vez de uma conta de serviço compartilhada
Configuração Flexível: Suporta tanto tokens pessoais quanto variáveis de ambiente compartilhadas
Integração MCP Padrão: Segue as melhores práticas do ecossistema MCP para autenticação

🎯 Gerenciamento de Tarefas Principal

Operações de Tarefas: Visualizar detalhes da tarefa, ler comentários, adicionar comentários, inscrever usuários em tarefas
Formatação Rica: Saída bem estruturada com metadados da tarefa, status, prioridade e threads completas de comentários

🔍 Revisão de Código Avançada

Gerenciamento de Diferenciais: Visualizar revisões, ler comentários, aprovar/rejeitar alterações de código
Feedback Inteligente de Revisão: Analisar comentários com contexto de código circundante para insights acionáveis
Comentários Inline: Adicionar feedback direcionado a linhas específicas em revisões de código
Análise de Contexto de Código: Correlacionar comentários de revisão com alterações e locais reais de código

🚀 Arquitetura do Servidor

Transporte HTTP/SSE: Servidor baseado em FastMCP para uso confiável em produção (padrão na porta 8932)
Transporte stdio: Suporte legado para integração direta com clientes MCP
API Abrangente: 11 ferramentas especializadas para automação completa do fluxo de trabalho do Phabricator

🧠 Análise Inteligente de Revisão

Correlação Comentário-Código: Vincular inteligentemente o feedback da revisão a locais específicos do código
Exibição Contextual de Código: Mostrar linhas de código circundantes para melhor compreensão
Geração de Itens de Ação: Categorizar feedback em itens de ação acionáveis
Classificação de Prioridade: Organizar comentários por Problemas → Sugestões → Detalhes → Outros

🛠 Ferramentas Disponíveis

Gerenciamento de Tarefas (3 ferramentas)

get-task - Obter detalhes abrangentes da tarefa com comentários
add-task-comment - Adicionar comentários às tarefas
subscribe-to-task - Inscrever usuários nas notificações de tarefas

Revisão de Código (8 ferramentas)

get-differential - Obter detalhes básicos da revisão diferencial
get-differential-detailed - Obter revisão abrangente com alterações de código
get-review-feedback - : Obter análise inteligente de revisão com contexto de código
add-differential-comment - Adicionar comentários gerais às revisões
add-inline-comment - : Adicionar comentários inline direcionados a linhas específicas de código
accept-differential - Aceitar/aprovar revisões diferenciais
request-changes-differential - Solicitar alterações com feedback opcional
subscribe-to-differential - Inscrever usuários nas notificações de revisão

📋 Pré-requisitos

Python 3.8+
Instância do Phabricator com acesso à API
Token de API do Phabricator (Configurações → Tokens de API do Conduit)

⚡ Início Rápido

Configuração Automatizada (Recomendada)

# Clone and navigate
git clone https://github.com/YushengAuggie/phabricator-mcp-server.git
cd phabricator-mcp-server

# Configure credentials
echo "PHABRICATOR_TOKEN=your-32-character-api-token" > .env
echo "PHABRICATOR_URL=https://your-phabricator-instance.com/api/" >> .env

# Start server (handles all setup automatically)
python3 start.py --mode http

O servidor inicia em http://localhost:8932 com gerenciamento automático de dependências.

Configuração Manual

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install with dependencies
pip install -e .

# Start HTTP server
python src/servers/http_server.py

# Or start stdio server
python src/servers/stdio_server.py

⚙️ Configuração

Configuração de Autenticação

O servidor suporta autenticação híbrida com dois modos que funcionam perfeitamente juntos:

Token de API Pessoal (Recomendado): Passe seu token pessoal pela configuração do cliente MCP para atribuição de usuário
Fallback de Variável de Ambiente: Use um token de conta de serviço compartilhada via variáveis de ambiente

🔑 Obtendo Seu Token de API:

Vá para sua instância do Phabricator → Configurações → Tokens de API
Crie um novo token com as permissões apropriadas
Copie o token de 32 caracteres para uso na configuração

🌐 Encontrando Sua URL do Phabricator: Sua URL de API do Phabricator deve terminar com /api/ e normalmente se parece com:

https://phabricator.example.com/api/
https://phab.yourcompany.com/api/
https://your-domain.phabricator.com/api/

Se não tiver certeza, verifique a página principal da sua instância do Phabricator - a URL geralmente é [your-base-url]/api/

🚀 Configuração do Cliente MCP

Transporte HTTP/SSE (Recomendado)

O servidor detecta automaticamente a configuração do seu ambiente:

Claude Code CLI (Mais Fácil):

claude mcp add --transport sse phabricator http://localhost:8932/sse \
  --env "PHABRICATOR_TOKEN=api-xxxxxxx" \
  --env "PHABRICATOR_URL=https://example.com/api/"

Substitua api-xxxxxxx pelo seu token de API real e https://example.com/api/ pela URL da sua instância do Phabricator

Configuração Manual:

{
  "mcpServers": {
    "phabricator": {
      "url": "http://localhost:8932/sse",
      "env": {
        "PHABRICATOR_TOKEN": "api-xxxxxxx",
        "PHABRICATOR_URL": "https://example.com/api/"
      }
    }
  }
}

Transporte stdio

Para Claude Desktop e integração MCP direta:

{
  "mcpServers": {
    "phabricator": {
      "command": "python",
      "args": ["path/to/phabricator-mcp-server/start.py"],
      "cwd": "path/to/phabricator-mcp-server",
      "env": {
        "PHABRICATOR_TOKEN": "api-xxxxxxx",
        "PHABRICATOR_URL": "https://example.com/api/"
      }
    }
  }
}

Múltiplas Opções de Autenticação

O servidor suporta várias formas de autenticação:

Token Pessoal nas Ferramentas: Algumas ferramentas aceitam um parâmetro api_token
Variáveis de Ambiente: Defina PHABRICATOR_TOKEN na configuração do cliente MCP
Token de Fallback: Crie o arquivo .env no diretório do servidor

Ordem de Prioridade: Token pessoal → Ambiente MCP → Arquivo .env do servidor

Variáveis de Ambiente do Servidor (Fallback)

Crie o arquivo .env na raiz do projeto para autenticação de fallback:

# Fallback: Shared service account token  
PHABRICATOR_TOKEN=your-shared-token-here

# Optional: Custom Phabricator URL (auto-detected from token by default)
# PHABRICATOR_URL=https://your-phabricator-instance.com/api/

# Optional: Custom server port (default: 8932)
# MCP_SERVER_PORT=8932

🔧 Configuração Avançada

Atribuição de Usuário

Tokens pessoais: Comentários aparecem sob SEU nome
Tokens compartilhados: Comentários aparecem sob o nome da conta de serviço
Uso misto: Ferramentas diferentes podem usar tokens diferentes

Segurança de Tokens

Tokens são passados com segurança pelo protocolo MCP
Nenhum token é armazenado em disco (exceto o fallback opcional .env)
Cada cliente pode usar seu próprio token pessoal

Solução de Problemas de Autenticação

Se você encontrar erros de autenticação:

Verifique a validade do token: Teste seu token diretamente com a API do Phabricator
Verifique a configuração: Garanta que PHABRICATOR_TOKEN esteja definido corretamente
Verifique o ambiente: Execute o servidor com depuração para ver as variáveis de ambiente
Use token pessoal: Passe o parâmetro api_token diretamente às ferramentas

Comandos de Depuração:

# Check if server can start with your token
PHABRICATOR_TOKEN=your-token python start.py --mode http

# Test token manually
curl -d "api.token=your-token" https://your-phabricator-instance.com/api/user.whoami

💻 Uso

Com o Claude Desktop

Adicione à configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "phabricator": {
      "command": "python",
      "args": ["path/to/phabricator-mcp-server/start.py", "--mode", "stdio"],
      "cwd": "path/to/phabricator-mcp-server"
    }
  }
}

Com Transporte HTTP/SSE

{
  "mcpServers": {
    "phabricator": {
      "url": "http://localhost:8932/sse"
    }
  }
}

Uso Programático

from src.core.client import PhabricatorClient

# Initialize client
client = PhabricatorClient(
    token="your-32-char-api-token",
    host="https://your-instance.com/api/"
)

# Get enhanced review feedback with code context
feedback = await client.get_review_feedback_with_code_context("12345", context_lines=7)

# Add inline comment to specific line
await client.add_inline_comment("12345", "src/file.py", 42, "Consider using a more descriptive variable name")

# Get task with full context
task = await client.get_task("6789")
comments = await client.get_task_comments("6789")

Exemplo: Revisão de Código com IA

# Get intelligent review feedback
feedback_data = await client.get_review_feedback_with_code_context("D123", context_lines=5)

# The feedback includes:
# - Comments correlated with specific code locations
# - Surrounding code context for each comment
# - Action items categorized by priority
# - File-by-file breakdown of changes

🧪 Desenvolvimento e Testes

Instalar Dependências de Desenvolvimento

# Install with dev dependencies
pip install -e ".[dev]"

# Or with uv (faster)
uv pip install -e ".[dev]"

Executar Testes

# Run all tests with our test runner
python run_tests.py

# Run specific test suites
python -m pytest src/tests/test_tool_completeness.py -v
python -m pytest src/tests/test_tool_integration.py -v

# Run with coverage
python -m pytest --cov=src --cov-report=html

Qualidade de Código

# Format code
black src/
ruff check src/ --fix

# Type checking
mypy src/

# Run all quality checks
black src/ && ruff check src/ && mypy src/ && python run_tests.py

Recursos de Teste

Completude das Ferramentas: Valida que todas as 11 ferramentas estão configuradas corretamente
Testes de Integração: Testa todas as ferramentas com dados simulados realistas
Tratamento de Erros: Valida modos de falha graciosos
Validação de Argumentos: Garante parâmetros obrigatórios/opcionais corretos
Phabricator Simulado: Nenhuma chamada de API necessária para testes

🎯 Recursos Avançados

Análise Inteligente de Feedback de Revisão

A ferramenta get-review-feedback fornece análise avançada:

# Returns structured feedback with:
{
    "revision": {...},              # Revision metadata
    "review_feedback": [            # Enhanced comment analysis
        {
            "comment": "Fix this issue",
            "author": "reviewer-phid",
            "type": "inline",
            "code_context": {
                "file": "src/example.py",
                "target_line": 42,
                "hunk_info": "@@ -40,7 +40,7 @@",
                "lines": [           # Surrounding code context
                    {"line_number": 40, "content": "def example():", "is_target": False},
                    {"line_number": 41, "content": "    # TODO: fix this", "is_target": False},
                    {"line_number": 42, "content": "    return broken_code", "is_target": True},
                    {"line_number": 43, "content": "    # end function", "is_target": False},
                ]
            },
            "primary_file": "src/example.py",
            "primary_line": 42
        }
    ],
    "summary": "Analysis summary with actionable insights",
    "total_comments": 5,
    "comments_with_context": 3
}

Correlação Inteligente Comentário-Código

Extração de Palavras-chave: Identifica nomes de variáveis e funções nos comentários
Mapeamento de Localização de Código: Vincula comentários a arquivos e números de linha específicos
Enriquecimento de Contexto: Mostra código circundante para melhor compreensão
Classificação de Prioridade: Organiza o feedback por importância

🤝 Contribuindo

Aceitamos contribuições! Veja como começar:

# Fork and clone the repository
git clone https://github.com/your-username/phabricator-mcp-server.git
cd phabricator-mcp-server

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
python run_tests.py

# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open a Pull Request

Diretrizes de Desenvolvimento

Siga o estilo de código existente (black + ruff)
Adicione testes para novos recursos
Atualize a documentação conforme necessário
Garanta que todas as verificações de qualidade passem

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🔗 Links

Repositório: https://github.com/YushengAuggie/phabricator-mcp-server
Model Context Protocol: https://modelcontextprotocol.io/
FastMCP: https://github.com/jlowin/fastmcp
API do Phabricator: https://secure.phabricator.com/book/phabricator/article/conduit/