feat: add MCP server for Neo4j graph queries

[rysweet]

Summary

• Implements MCP server for AI agents to query Blarify graphs
• Provides three powerful tools for code understanding and change planning
• Uses Neo4j for graph queries and Azure OpenAI for result formatting
• Includes comprehensive integration tests with real Neo4j database

Details

This PR implements issue #10 to create an MCP (Model Context Protocol) server that provides AI coding agents with sophisticated tools to query and analyze Blarify graph databases.

Tools Implemented

1. getContextForFiles

   • Retrieves comprehensive context for specified files
   • Traverses graph to find classes, functions, dependencies, imports
   • Includes LLM summaries and documentation links
   • Returns organized Markdown structure

2. getContextForSymbol

   • Gets detailed context for any symbol (class, function, variable)
   • Finds definitions, usages, inheritance chains, and relationships
   • Supports fuzzy matching for symbol names
   • Shows callers, callees, and references

3. buildPlanForChange

   • Analyzes codebase to create implementation plans
   • Extracts entities from change requests using LLM
   • Identifies affected files, dependencies, and tests
   • Generates step-by-step implementation guide

Architecture

mcp-blarify-server/
├── src/
│   ├── server.py              # Main MCP server
│   ├── config.py              # Configuration management
│   ├── tools/
│   │   ├── context_tools.py   # File and symbol context
│   │   ├── planning_tools.py  # Change planning
│   │   └── query_builder.py   # Cypher queries
│   └── processors/
│       ├── graph_traversal.py # Neo4j traversal
│       ├── context_builder.py # Context organization
│       └── llm_processor.py   # LLM integration
└── tests/                     # Comprehensive test suite

Testing

This PR includes comprehensive testing:

Unit Tests

• Query builder tests
• Context builder tests
• LLM processor tests
• MCP server tests

Integration Tests

• Real Neo4j database with docker-compose
• Test graph setup with realistic Blarify data
• Full end-to-end testing of all MCP tools
• Manual test script for interactive testing
• CI/CD workflow for automated testing

Test Data

The test setup creates a realistic graph with:

• Folder structure (src, tests, docs)
• Code nodes (UserService, AuthService, UserController)
• Relationships (inheritance, imports, calls, uses)
• Documentation nodes with concepts
• LLM descriptions
• Filesystem nodes

Configuration

Environment variables:

• NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD: Neo4j connection
• AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT: LLM configuration
• MAX_TRAVERSAL_DEPTH, MAX_CONTEXT_LENGTH: Performance tuning

Usage Example

# In Claude Desktop config
{
  "mcpServers": {
    "blarify": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-blarify-server"
    }
  }
}

Test plan

• Unit tests for all components
• Integration tests with real Neo4j
• Test data setup script
• Manual testing script
• Docker-compose environment
• CI/CD workflow
• Testing with Claude Desktop
• Performance testing with large graphs

How to Test

1. Run unit tests:

   cd mcp-blarify-server
   pytest tests/test_*.py -v

2. Run integration tests:

   cd mcp-blarify-server
   ./run_integration_tests.sh

3. Manual testing:

   cd mcp-blarify-server
   docker-compose up -d
   python tests/setup_test_graph.py
   python manual_test.py

🤖 Generated with Claude Code