Phabricator MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact intelligently with Phabricator for advanced task management and code review workflows.

✨ Features

🔑 Personal Authentication

• Per-User Authentication: Configure your personal Phabricator API token in your MCP client
• User Attribution: Comments and reviews appear under YOUR name instead of a shared service account
• Flexible Configuration: Supports both personal tokens and shared environment variables
• Standard MCP Integration: Follows MCP ecosystem best practices for authentication

🎯 Core Task Management

• Task Operations: View task details, read comments, add comments, subscribe users to tasks
• Rich Formatting: Well-structured output with task metadata, status, priority, and full comment threads

🔍 Advanced Code Review

• Differential Management: View revisions, read comments, approve/reject code changes
• Intelligent Review Feedback: Analyze comments with surrounding code context for actionable insights
• Inline Comments: Add targeted feedback to specific lines in code reviews
• Code Context Analysis: Correlate review comments with actual code changes and locations

🚀 Server Architecture

• HTTP/SSE Transport: FastMCP-based server for reliable production use (default on port 8932)
• stdio Transport: Legacy support for direct MCP client integration
• Comprehensive API: 11 specialized tools for complete Phabricator workflow automation

🧠 Smart Review Analysis

• Comment-Code Correlation: Intelligently link review feedback to specific code locations
• Contextual Code Display: Show surrounding code lines for better understanding
• Action Item Generation: Categorize feedback into actionable to-do items
• Priority Classification: Organize comments by Issues → Suggestions → Nits → Other

🛠 Available Tools

Task Management (3 tools)

• `get-task` - Get comprehensive task details with comments
• `add-task-comment` - Add comments to tasks
• `subscribe-to-task` - Subscribe users to task notifications

Code Review (8 tools)

• `get-differential` - Get basic differential revision details
• `get-differential-detailed` - Get comprehensive review with code changes
• `get-review-feedback` - : Get intelligent review analysis with code context
• `add-differential-comment` - Add general comments to reviews
• `add-inline-comment` - : Add targeted inline comments to specific code lines
• `accept-differential` - Accept/approve differential revisions
• `request-changes-differential` - Request changes with optional feedback
• `subscribe-to-differential` - Subscribe users to review notifications

📋 Prerequisites

• Python 3.8+
• Phabricator instance with API access
• API token from Phabricator (Settings → Conduit API Tokens)

⚡ Quick Start

Automated Setup (Recommended)

# 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

The server starts on `http://localhost:8932` with automatic dependency management.

Manual Setup

# 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

⚙️ Configuration

Authentication Configuration

The server supports hybrid authentication with two modes that work seamlessly together:

1. Personal API Token (Recommended): Pass your personal token through MCP client configuration for user attribution

2. Environment Variable Fallback: Use a shared service account token via environment variables

🔑 Getting Your API Token:

1. Go to your Phabricator instance → Settings → API Tokens

2. Create a new token with appropriate permissions

3. Copy the 32-character token for use in configuration

🌐 Finding Your Phabricator URL:

Your Phabricator API URL should end with `/api/` and typically looks like:

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

If unsure, check your Phabricator instance's main page - the URL is usually `[your-base-url]/api/`

🚀 MCP Client Configuration

HTTP/SSE Transport (Recommended)

The server automatically detects your environment configuration:

Claude Code CLI (Easiest):

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

> Replace `api-xxxxxxx` with your actual API token and `https://example.com/api/` with your Phabricator instance URL

Manual Configuration:

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

stdio Transport

For Claude Desktop and direct MCP integration:

{
  "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/"
      }
    }
  }
}

Multiple Authentication Options

The server supports multiple ways to authenticate:

1. Personal Token in Tools: Some tools accept an `api_token` parameter

2. Environment Variables: Set `PHABRICATOR_TOKEN` in MCP client config

3. Fallback Token: Create `.env` file in server directory

Priority Order: Personal token → MCP environment → Server `.env` file

Server Environment Variables (Fallback)

Create `.env` file in project root for fallback authentication:

# 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

🔧 Advanced Configuration

User Attribution

• Personal tokens: Comments appear under YOUR name
• Shared tokens: Comments appear under the service account name
• Mixed usage: Different tools can use different tokens

Token Security

• Tokens are passed securely through MCP protocol
• No tokens stored on disk (except optional `.env` fallback)
• Each client can use their own personal token

Troubleshooting Authentication

If you see authentication errors:

1. Check token validity: Test your token directly with Phabricator API

2. Verify configuration: Ensure `PHABRICATOR_TOKEN` is set correctly

3. Check environment: Run server with debugging to see environment variables

4. Use personal token: Pass `api_token` parameter directly to tools

Debugging Commands:

# 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

💻 Usage

With Claude Desktop

Add to Claude Desktop configuration (`claude_desktop_config.json`):

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

With HTTP/SSE Transport

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

Programmatic Usage

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

Example: AI-Powered Code Review

# 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

🧪 Development & Testing

Install Development Dependencies

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

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

Run Tests

# 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

Code Quality

# 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

Testing Features

• Tool Completeness: Validates all 11 tools are properly configured
• Integration Testing: Tests all tools with realistic mock data
• Error Handling: Validates graceful failure modes
• Argument Validation: Ensures correct required/optional parameters
• Mock Phabricator: No API calls needed for testing

🎯 Advanced Features

Intelligent Review Feedback Analysis

The `get-review-feedback` tool provides advanced analysis:

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

Smart Comment-Code Correlation

• Keyword Extraction: Identifies variable names, function names in comments
• Code Location Mapping: Links comments to specific files and line numbers
• Context Enrichment: Shows surrounding code for better understanding
• Priority Classification: Organizes feedback by importance

🤝 Contributing

We welcome contributions! Here's how to get started:

# 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

Development Guidelines

• Follow existing code style (black + ruff)
• Add tests for new features
• Update documentation as needed
• Ensure all quality checks pass

📄 License

MIT License - see LICENSE file for details.

🔗 Links

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