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:

Personal API Token (Recommended): Pass your personal token through MCP client configuration for user attribution
Environment Variable Fallback: Use a shared service account token via environment variables

🔑 Getting Your API Token:

Go to your Phabricator instance → Settings → API Tokens
Create a new token with appropriate permissions
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:

Personal Token in Tools: Some tools accept an api_token parameter
Environment Variables: Set PHABRICATOR_TOKEN in MCP client config
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:

Check token validity: Test your token directly with Phabricator API
Verify configuration: Ensure PHABRICATOR_TOKEN is set correctly
Check environment: Run server with debugging to see environment variables
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/

Phabricator