Phabricator

Interactúa con Phabricator para la gestión de tareas y flujos de trabajo de revisión de código.

Documentación

Servidor MCP de Phabricator

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que permite a los asistentes de IA interactuar de forma inteligente con Phabricator para flujos de trabajo avanzados de gestión de tareas y revisión de código.

✨ Características

🔑 Autenticación Personal

Autenticación por Usuario: Configura tu token personal de la API de Phabricator en tu cliente MCP
Atribución de Usuario: Los comentarios y revisiones aparecen bajo TU nombre en lugar de una cuenta de servicio compartida
Configuración Flexible: Admite tanto tokens personales como variables de entorno compartidas
Integración MCP Estándar: Sigue las mejores prácticas del ecosistema MCP para la autenticación

🎯 Gestión Central de Tareas

Operaciones con Tareas: Ver detalles de tareas, leer comentarios, añadir comentarios, suscribir usuarios a tareas
Formato Enriquecido: Salida bien estructurada con metadatos de tarea, estado, prioridad e hilos de comentarios completos

🔍 Revisión de Código Avanzada

Gestión de Differential: Ver revisiones, leer comentarios, aprobar/rechazar cambios de código
Retroalimentación Inteligente de Revisión: Analizar comentarios con contexto de código circundante para obtener información práctica
Comentarios en Línea: Añadir retroalimentación específica a líneas concretas en revisiones de código
Análisis de Contexto de Código: Correlacionar comentarios de revisión con cambios de código reales y ubicaciones

🚀 Arquitectura del Servidor

Transporte HTTP/SSE: Servidor basado en FastMCP para uso de producción fiable (puerto predeterminado 8932)
Transporte stdio: Soporte heredado para integración directa con clientes MCP
API Integral: 11 herramientas especializadas para la automatización completa del flujo de trabajo de Phabricator

🧠 Análisis Inteligente de Revisiones

Correlación Comentario-Código: Vincular inteligentemente la retroalimentación de revisión con ubicaciones específicas de código
Visualización Contextual de Código: Mostrar líneas de código circundantes para una mejor comprensión
Generación de Elementos de Acción: Categorizar la retroalimentación en tareas pendientes accionables
Clasificación de Prioridad: Organizar comentarios por Problemas → Sugerencias → Detalles → Otros

🛠 Herramientas Disponibles

Gestión de Tareas (3 herramientas)

get-task - Obtener detalles completos de tareas con comentarios
add-task-comment - Añadir comentarios a tareas
subscribe-to-task - Suscribir usuarios a notificaciones de tareas

Revisión de Código (8 herramientas)

get-differential - Obtener detalles básicos de revisión diferencial
get-differential-detailed - Obtener revisión integral con cambios de código
get-review-feedback - : Obtener análisis inteligente de revisión con contexto de código
add-differential-comment - Añadir comentarios generales a revisiones
add-inline-comment - : Añadir comentarios en línea específicos a líneas de código concretas
accept-differential - Aceptar/aprobar revisiones diferenciales
request-changes-differential - Solicitar cambios con retroalimentación opcional
subscribe-to-differential - Suscribir usuarios a notificaciones de revisión

📋 Requisitos Previos

Python 3.8+
Instancia de Phabricator con acceso a la API
Token de API de Phabricator (Configuración → Tokens de API de Conduit)

⚡ Inicio Rápido

Configuración 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

El servidor se inicia en http://localhost:8932 con gestión automática de dependencias.

Configuración 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

⚙️ Configuración

Configuración de Autenticación

El servidor admite autenticación híbrida con dos modos que funcionan perfectamente juntos:

Token de API Personal (Recomendado): Pasa tu token personal a través de la configuración del cliente MCP para la atribución de usuario
Respaldo de Variable de Entorno: Usa un token de cuenta de servicio compartida mediante variables de entorno

🔑 Obtención de tu Token de API:

Ve a tu instancia de Phabricator → Configuración → Tokens de API
Crea un nuevo token con los permisos adecuados
Copia el token de 32 caracteres para usarlo en la configuración

🌐 Cómo Encontrar tu URL de Phabricator: La URL de tu API de Phabricator debe terminar en /api/ y normalmente tiene este aspecto:

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

Si no estás seguro, consulta la página principal de tu instancia de Phabricator: la URL suele ser [your-base-url]/api/

🚀 Configuración del Cliente MCP

Transporte HTTP/SSE (Recomendado)

El servidor detecta automáticamente la configuración de tu entorno:

Claude Code CLI (Más Sencillo):

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

Reemplaza api-xxxxxxx con tu token de API real y https://example.com/api/ con la URL de tu instancia de Phabricator

Configuración 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 integración MCP directa:

{
  "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últiples Opciones de Autenticación

El servidor admite varias formas de autenticación:

Token Personal en Herramientas: Algunas herramientas aceptan un parámetro api_token
Variables de Entorno: Establece PHABRICATOR_TOKEN en la configuración del cliente MCP
Token de Respaldo: Crea un archivo .env en el directorio del servidor

Orden de Prioridad: Token personal → Entorno MCP → Archivo .env del servidor

Variables de Entorno del Servidor (Respaldo)

Crea un archivo .env en la raíz del proyecto para la autenticación de respaldo:

# 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

🔧 Configuración Avanzada

Atribución de Usuario

Tokens personales: Los comentarios aparecen bajo TU nombre
Tokens compartidos: Los comentarios aparecen bajo el nombre de la cuenta de servicio
Uso mixto: Diferentes herramientas pueden usar diferentes tokens

Seguridad de Tokens

Los tokens se pasan de forma segura a través del protocolo MCP
No se almacenan tokens en disco (excepto el respaldo opcional .env)
Cada cliente puede usar su propio token personal

Solución de Problemas de Autenticación

Si ves errores de autenticación:

Comprueba la validez del token: Prueba tu token directamente con la API de Phabricator
Verifica la configuración: Asegúrate de que PHABRICATOR_TOKEN esté configurado correctamente
Comprueba el entorno: Ejecuta el servidor con depuración para ver las variables de entorno
Usa el token personal: Pasa el parámetro api_token directamente a las herramientas

Comandos de Depuración:

# 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

Con Claude Desktop

Añade a la configuración de 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"
    }
  }
}

Con 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")

Ejemplo: Revisión de Código Impulsada por 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

🧪 Desarrollo y Pruebas

Instalar Dependencias de Desarrollo

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

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

Ejecutar Pruebas

# 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

Calidad del 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

Características de Pruebas

Integridad de Herramientas: Valida que las 11 herramientas estén configuradas correctamente
Pruebas de Integración: Prueba todas las herramientas con datos simulados realistas
Manejo de Errores: Valida modos de fallo elegantes
Validación de Argumentos: Asegura los parámetros obligatorios/opcionales correctos
Phabricator Simulado: No se necesitan llamadas a la API para las pruebas

🎯 Características Avanzadas

Análisis Inteligente de Retroalimentación de Revisiones

La herramienta get-review-feedback proporciona análisis avanzado:

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

Correlación Inteligente Comentario-Código

Extracción de Palabras Clave: Identifica nombres de variables y funciones en los comentarios
Mapeo de Ubicaciones de Código: Vincula comentarios a archivos y números de línea específicos
Enriquecimiento de Contexto: Muestra el código circundante para una mejor comprensión
Clasificación de Prioridad: Organiza la retroalimentación por importancia

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Así es como empezar:

# 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

Directrices de Desarrollo

Sigue el estilo de código existente (black + ruff)
Añade pruebas para nuevas funciones
Actualiza la documentación según sea necesario
Asegúrate de que todos los controles de calidad pasen

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

🔗 Enlaces

Repositorio: https://github.com/YushengAuggie/phabricator-mcp-server
Protocolo de Contexto de Modelos: https://modelcontextprotocol.io/
FastMCP: https://github.com/jlowin/fastmcp
API de Phabricator: https://secure.phabricator.com/book/phabricator/article/conduit/