Axon.MCP.Server

System Architecture Overview

📋 Executive Summary

Axon.MCP.Server is a sophisticated AI-powered code intelligence platform built on a modern microservices architecture. It combines FastAPI (REST API), Model Context Protocol (AI integration), Celery (distributed processing), and a hybrid analysis engine (Tree-sitter + Roslyn) to transform codebases into queryable knowledge bases.

🏗️ High-Level Architecture

System Components Diagram

graph TB
    subgraph "Client Layer"
        A1[AI Assistants<br/>ChatGPT/Claude/Cursor]
        A2[React Dashboard<br/>Port 80]
        A3[REST Clients<br/>External Tools]
    end
    
    subgraph "API Layer"
        B1[MCP Server<br/>:8001]
        B2[REST API<br/>:8080]
    end
    
    subgraph "Processing Layer"
        C1[Celery Worker<br/>Repository Sync]
        C2[Enrichment Worker<br/>AI Analysis - 8 concurrency]
        C3[Beat Scheduler<br/>Periodic Tasks]
    end
    
    subgraph "Analysis Layer"
        D1[Tree-sitter Parsers<br/>Python, JS, TS, C#]
        D2[Roslyn Analyzer<br/>C# Semantic Analysis]
        D3[EF Core Analyzer<br/>Entity Detection]
        D4[Knowledge Extractor<br/>Call Graph, Patterns]
    end
    
    subgraph "Data Layer"
        E1[(PostgreSQL + pgvector<br/>:5432)]
        E2[(Redis<br/>Cache/Queue :6379)]
    end
    
    subgraph "Monitoring"
        F1[Prometheus<br/>:9090]
        F2[Grafana<br/>:3000]
    end
    
    subgraph "Source Control"
        G1[GitLab API]
        G2[Azure DevOps API]
    end
    
    A1 --> B1
    A2 --> B2
    A3 --> B2
    B1 --> E1
    B2 --> E1
    B2 --> E2
    B2 --> C1
    C1 --> D1
    C1 --> D2
    C1 --> D3
    C1 --> D4
    C2 --> E1
    C1 --> E1
    C1 --> E2
    D2 --> E1
    G1 --> C1
    G2 --> C1
    B2 --> F1
    F1 --> F2

🔧 Technology Stack

Backend Stack

Frontend Stack

Infrastructure

📦 Core Components

1. API Layer (src/api)

Purpose: REST API endpoints for UI and external integrations

Key Files:

Responsibilities:

Authentication Flow:

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database
    
    C->>A: POST /auth/login {username, password}
    A->>D: Verify credentials
    D-->>A: User data
    A->>A: Generate JWT token
    A-->>C: Set HTTP-only cookie + token
    
    C->>A: GET /api/v1/repositories (with cookie)
    A->>A: Validate JWT
    A->>D: Query repositories
    D-->>A: Repository list
    A-->>C: JSON response

2. MCP Server (src/mcp_server)

Purpose: Model Context Protocol server for AI assistant integration

Key Files:

12 Available Tools:

  1. search - Semantic + full-text code search
  2. get_symbol_details - Detailed symbol information
  3. get_call_graph - Function call relationships
  4. get_inheritance_hierarchy - Class inheritance tree
  5. get_module_summary - AI-generated code summaries
  6. get_file_symbols - List symbols in a file
  7. get_repository_structure - Project/solution organization
  8. get_api_endpoints - List REST API routes
  9. get_ef_entities - Entity Framework mappings
  10. explore_service - Navigate service architecture
  11. find_implementations - Interface implementations
  12. get_system_architecture_map - Architecture diagrams

Transport Modes:

3. Workers (src/workers)

Purpose: Distributed background processing with Celery

Key Files:

Worker Types:

Queues:

4. Analysis Layer

4.1 Tree-sitter Parsers (src/parsers)

Purpose: Fast syntactic parsing for multiple languages

Supported Languages:

Extracts:

4.2 Roslyn Analyzer (roslyn_analyzer/)

Purpose: Deep semantic analysis for C# code

Architecture: Persistent C# subprocess communicating via JSON over stdin/stdout

Capabilities:

Communication Protocol:

// Request
{"operation": "analyze", "filePath": "UserService.cs", "content": "..."}

// Response
{
  "symbols": [...],
  "relations": [
    {"from": "UserController.Login", "to": "AuthService.Authenticate", "type": "calls"}
  ]
}

4.3 Knowledge Extractor (src/extractors)

Purpose: Extract high-level patterns and relationships

Components:

Extracts:

4.4 EF Core Analyzer (src/analyzers)

Purpose: Extract Entity Framework Core mappings

Extracts:

5. Data Layer

5.1 Database (src/database)

Models (models.py):

Session Management (session.py):

5.2 Redis Cache

Uses:

6. Embeddings (src/embeddings)

Purpose: Generate vector embeddings for semantic search

Components:

Providers:

Chunking Strategy:

⚙️ Processing Pipeline

The sync_repository task orchestrates the complete analysis pipeline:

graph LR
    A[1. Clone<br/>Repository] --> B[2. Detect<br/>Solutions]
    B --> C[3. Restore<br/>.NET Deps]
    C --> D[4. Initialize<br/>Roslyn]
    D --> E[5. Discover<br/>Files]
    E --> F[6. Parse<br/>Tree-sitter]
    F --> G[7. Analyze<br/>Roslyn C#]
    G --> H[8. Extract<br/>APIs]
    H --> I[9. Resolve<br/>Imports]
    I --> J[10. Build<br/>Call Graph]
    J --> K[11. Detect<br/>Services]
    K --> L[12. Analyze<br/>EF Entities]
    L --> M[13. Generate<br/>Embeddings]
    M --> N[14. AI<br/>Enrichment]

Pipeline Steps Detail

  1. Clone Repository: GitLab/Azure DevOps API → local cache
  2. Detect Solutions/Projects: Scan .sln and .csproj files
  3. Restore .NET Dependencies: Run dotnet restore
  4. Initialize Roslyn: Start C# subprocess, load solution
  5. Discover Files: List source files, compute hashes
  6. Parse (Tree-sitter): Extract symbols, imports, complexity
  7. Analyze (Roslyn): Deep C# semantic analysis
  8. Extract APIs: Detect REST endpoints, routes
  9. Resolve Imports: Map import statements to symbols
  10. Build Call Graph: Track function calls
  11. Detect Services: Identify APIs, workers, libraries
  12. Analyze EF Entities: Extract database mappings
  13. Generate Embeddings: Create vector embeddings
  14. AI Enrichment: LLM-generated summaries (optional)

Memory Management:

🐳 Deployment Architecture

Docker Services (10 Containers)

┌─────────────────────────────────────────────────────────────┐
│                    Docker Network: axon-network             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ PostgreSQL   │  │    Redis     │  │   React UI   │     │
│  │  + pgvector  │  │   Cache/MQ   │  │   (Nginx)    │     │
│  │    :5432     │  │    :6379     │  │     :80      │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │  REST API    │  │  MCP Server  │                        │
│  │  (FastAPI)   │  │    (HTTP)    │                        │
│  │    :8080     │  │    :8001     │                        │
│  └──────────────┘  └──────────────┘                        │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Worker     │  │  Enrichment  │  │     Beat     │     │
│  │ (Sync - 1)   │  │ Worker (8)   │  │  Scheduler   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐                        │
│  │  Prometheus  │  │   Grafana    │                        │
│  │    :9090     │  │    :3000     │                        │
│  └──────────────┘  └──────────────┘                        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Resource Allocation:

🔍 Search Architecture

Hybrid Search Flow

sequenceDiagram
    participant C as Client
    participant API as Search Service
    participant PG as PostgreSQL
    participant V as pgvector
    participant R as Redis
    
    C->>API: search(query="authentication")
    API->>R: Check cache
    alt Cache Hit
        R-->>API: Cached results
        API-->>C: Return results
    else Cache Miss
        API->>API: Generate query embedding
        par Vector Search
            API->>V: Cosine similarity search
            V-->>API: Top 10 results
        and Keyword Search
            API->>PG: Full-text search
            PG-->>API: Top 10 results
        end
        API->>API: Merge + re-rank results
        API->>R: Cache results (TTL: 3600s)
        API-->>C: Return ranked results
    end

Search Strategies

  1. Semantic Search: Vector similarity using pgvector
    • Embed query using same model as code chunks
    • Cosine similarity: embedding <=> query_vector
    • Fast with HNSW index
  2. Full-Text Search: PostgreSQL tsvector
    • Indexes symbol names, docstrings, signatures
    • Supports fuzzy matching
    • Language-specific stemming
  3. Hybrid: Combine both with score fusion
    • Vector search weight: 0.6
    • Keyword search weight: 0.4
    • Re-rank by relevance

🔐 Security Architecture

Authentication Flow

graph LR
    A[Client Request] --> B{Has Cookie?}
    B -->|Yes| C[Validate JWT]
    B -->|No| D{Has X-API-Key?}
    D -->|Yes| E[Validate API Key]
    D -->|No| F[401 Unauthorized]
    C -->|Valid| G[Authorize Role]
    C -->|Invalid| F
    E -->|Valid| G
    E -->|Invalid| F
    G -->|Authorized| H[Process Request]
    G -->|Forbidden| I[403 Forbidden]

Auth Mechanisms:

Secure Defaults:

📊 Monitoring & Observability

Metrics Stack

Application Metrics → Prometheus → Grafana Dashboards
Logs (structlog) → Redis Pub/Sub → Dashboard
Celery Events → Flower (optional)

Key Metrics:

Pre-configured Dashboards:

🌐 Source Control Integration

GitLab Integration

Features:

Azure DevOps Integration

Features:

API Endpoints:

🔮 Future Architecture Enhancements

Planned Improvements

  1. RAG Pipeline: Add ask_codebase tool for conversational queries
  2. Microservices Split: Separate parsing, embeddings, and API into independent services
  3. Kubernetes: Production-grade orchestration with Helm charts
  4. Event Sourcing: Audit trail for all symbol changes
  5. GraphQL API: Supplement REST API for flexible queries
  6. Multi-tenancy: Organization-level isolation

📖 Additional Resources

This site is open source. Improve this page.