Expert Registry MCP Server

# Expert Registry MCP Server **Last Updated: 2025-06-30** A high-performance MCP server for expert discovery, registration, and context injection built with FastMCP v2, featuring vector and graph database integration for enhanced semantic search and relationship modeling. ## Features - 🚀 **High Performance**: Multi-layer caching with vector indices for sub-millisecond queries - 📁 **File-Based Updates**: Hot reload on registry/context file changes - 🔍 **Semantic Search**: Vector database integration for meaning-based expert discovery - 🔗 **Relationship Modeling**: Graph database for expert networks and team formation - 💉 **Context Injection**: AI-powered prompt enhancement with expert knowledge - 📊 **Analytics**: Performance tracking with collaborative filtering - 🧠 **Hybrid Discovery**: Combined vector similarity and graph connectivity scoring - 🐍 **Python-First**: Built with FastMCP v2 for clean, Pythonic code ## Installation ### Docker (Recommended for Production) The easiest way to run the Expert Registry MCP server is using Docker: ```bash # Build and deploy locally ./scripts/build.sh ./scripts/deploy.sh # Or use pre-built image from GitHub Container Registry docker pull ghcr.io/agentience/expert-registry-mcp:latest ``` **Features:** - 🐳 Single container service for multiple MCP clients - 📦 Expert contexts and registry mapped to host for easy editing - 🔄 Hot reload support when files change on host - 🌐 SSE transport for client connections - 🗄️ Includes Neo4j database setup - 🚀 Production-ready with health checks See [DOCKER.md](DOCKER.md) for complete deployment guide. ### Local Development Using uv (recommended): ```bash # Create virtual environment and install uv venv uv pip install -e . # Or install directly uv pip install expert-registry-mcp ``` Using pip: ```bash pip install expert-registry-mcp ``` ### Database Setup #### Vector Database (ChromaDB - Embedded) ```bash # ChromaDB is embedded, no separate installation needed # It will create a vector-db directory automatically ``` #### Graph Database (Neo4j) ```bash # Option 1: Docker (recommended) docker run -d --name neo4j \ -p 7474:7474 -p 7687:7687 \ -e NEO4J_AUTH=neo4j/password \ neo4j:latest # Option 2: Local installation # Download from https://neo4j.com/download/ ``` ## Quick Start 1. Set up your expert system directory structure: ``` expert-system/ ├── registry/ │ └── expert-registry.json ├── expert-contexts/ │ ├── aws-amplify-gen2.md │ ├── aws-cloudscape.md │ └── ... └── performance/ └── metrics.json ``` 2. Configure environment: ```bash export EXPERT_SYSTEM_PATH=/path/to/expert-system export NEO4J_URI=bolt://localhost:7687 export NEO4J_PASSWORD=password ``` 3. Run the server: ```bash # Using FastMCP CLI fastmcp run expert-registry-mcp # Or using Python python -m expert_registry_mcp.server ``` ## Claude Desktop Configuration Add to your Claude Desktop configuration: ```json { "mcpServers": { "expert-registry": { "command": "uv", "args": ["run", "expert-registry-mcp"], "env": { "EXPERT_SYSTEM_PATH": "/path/to/expert-system", "NEO4J_URI": "bolt://localhost:7687", "NEO4J_PASSWORD": "password" } } } } ``` ## Usage Examples ### Basic Expert Discovery ```python # Detect technologies in your project technologies = await expert_detect_technologies( scan_paths=["./src", "./package.json"] ) # Select the best expert with hybrid search result = await expert_smart_discover( context={ "description": "Refactor authentication system using AWS Amplify", "technologies": technologies.technologies, "constraints": ["maintain backward compatibility"], "preferred_strategy": "single" } ) ``` ### Context Injection ```python # Load expert context context = await expert_load_context( expert_id=result.expert.id ) # Inject into prompt enhanced_prompt = await expert_inject_context( prompt="Refactor the authentication system", expert_id=result.expert.id, injection_points=["constraints", "patterns", "quality-criteria"] ) ``` ### Performance Tracking ```python # Track usage await expert_track_usage( expert_id=result.expert.id, task_id="auth-refactor-001", outcome={ "success": True, "adherence_score": 9.5, "task_type": "refactoring" } ) # Get analytics analytics = await expert_get_analytics( expert_id=result.expert.id ) ``` ## Available Tools ### Registry Management - `expert_registry_list` - List experts with filtering - `expert_registry_get` - Get expert details - `expert_registry_search` - Search experts by query ### Expert Selection - `expert_detect_technologies` - Detect project technologies - `expert_select_optimal` - Select best expert for task - `expert_assess_capability` - Assess expert capability - `expert_smart_discover` - AI-powered hybrid search (vector + graph) ### Semantic Search - `expert_semantic_search` - Search using natural language - `expert_find_similar` - Find similar experts ### Graph Operations - `expert_explore_network` - Explore expert relationships - `expert_find_combinations` - Find complementary expert teams ### Context Operations - `expert_load_context` - Load expert knowledge - `expert_inject_context` - Enhance prompts with expertise ### Analytics - `expert_track_usage` - Record expert performance - `expert_get_analytics` - Get performance metrics ## Expert Registry Format ```json { "version": "1.0.0", "last_updated": "2025-06-30T00:00:00Z", "experts": [ { "id": "aws-amplify-gen2", "name": "AWS Amplify Gen 2 Expert", "version": "1.0.0", "description": "Expert in AWS Amplify Gen 2 development", "domains": ["backend", "cloud", "serverless"], "specializations": [ { "technology": "AWS Amplify Gen 2", "frameworks": ["AWS CDK", "TypeScript"], "expertise_level": "expert" } ], "workflow_compatibility": { "feature": 0.95, "bug-fix": 0.85, "refactoring": 0.80, "investigation": 0.70, "article": 0.60 }, "constraints": [ "Use TypeScript-first approach", "Follow AWS Well-Architected Framework" ], "patterns": [ "Infrastructure as Code", "Serverless-first architecture" ], "quality_standards": [ "100% type safety", "Comprehensive error handling" ] } ] } ``` ## Expert Context Format Expert context files are markdown documents in `expert-contexts/`: ```markdown # AWS Amplify Gen 2 Expert Context ## Constraints - Use TypeScript for all backend code - Follow AWS Well-Architected Framework principles - Implement proper error handling and logging ## Patterns - Infrastructure as Code using CDK - Serverless-first architecture - Event-driven communication ## Quality Standards - 100% TypeScript type coverage - Comprehensive error handling - Unit test coverage > 80% ``` ## Development ### Setup Development Environment ```bash # Clone repository git clone https://github.com/agentience/expert-registry-mcp cd expert-registry-mcp # Create virtual environment with uv uv venv source .venv/bin/activate # or .venv\Scripts\activate on Windows # Install in development mode uv pip install -e ".[dev]" ``` ### Run Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=expert_registry_mcp # Run specific test file pytest tests/test_registry.py ``` ### Code Quality ```bash # Format code black src tests # Lint code ruff check src tests # Type checking mypy src ``` ## Architecture ### Multi-Layer Caching - **Registry Cache**: 24-hour TTL for expert definitions - **Vector Cache**: Embeddings cached until expert updates - **Graph Cache**: Relationship queries cached for 10 minutes - **Selection Cache**: 5-minute TTL for technology detection - **Context Cache**: LRU cache for expert contexts (50 entries) ### Database Integration - **ChromaDB**: Embedded vector database for semantic search - Multiple collections for different embedding types - Automatic embedding generation with sentence-transformers - **Neo4j**: Graph database for relationship modeling - Expert-Technology-Task relationships - Team synergy calculations - Evolution tracking ### Performance Features - **Vector Indices**: Annoy indices for ultra-fast similarity search - **Precomputed Combinations**: Common expert pairs cached - **Batch Operations**: Efficient bulk processing - **Smart Invalidation**: Targeted cache updates ### File Watching - Uses `watchdog` for cross-platform file monitoring - Automatic registry reload and database sync - No server restart required for updates ## Troubleshooting ### Common Issues 1. **Expert not found** - Verify expert ID in registry - Check file paths are correct - Ensure registry JSON is valid 2. **Context file missing** - Check expert-contexts directory - Verify filename matches expert ID - Ensure .md extension 3. **Cache not updating** - File watcher may need restart - Check file permissions - Verify EXPERT_SYSTEM_PATH ### Debug Mode Enable debug logging: ```bash export FASTMCP_DEBUG=1 expert-registry-mcp ``` ## Advanced Features ### Semantic Search The system uses ChromaDB to enable natural language queries: ```python # Find experts by meaning, not just keywords results = await expert_semantic_search( query="implement secure authentication with cloud integration", search_mode="hybrid" ) ``` ### Relationship Exploration Neo4j powers sophisticated relationship queries: ```python # Explore expert networks network = await expert_explore_network( start_expert_id="aws-amplify-gen2", depth=2, relationship_types=["SPECIALIZES_IN", "COMPATIBLE_WITH"] ) ``` ### Team Formation AI-powered team composition: ```python # Find complementary expert teams teams = await expert_find_combinations( requirements=["AWS Amplify", "React", "DynamoDB"], team_size=3 ) ``` ## Contributing 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Run tests and linting 4. Commit your changes (`git commit -m 'Add amazing feature'`) 5. Push to the branch (`git push origin feature/amazing-feature`) 6. Open a Pull Request ## License MIT License - see LICENSE file for details ## Support - Documentation: https://github.com/agentience/expert-registry-mcp - Issues: https://github.com/agentience/expert-registry-mcp/issues - Discussions: https://github.com/agentience/expert-registry-mcp/discussions