---

📋 Table of Contents

• The Problem
• The Solution
• See It In Action
• Architecture Overview
• MCP Tools for AI Assistants
• Key Features
• Quick Start
• Use Cases
• Documentation
• Development
• Roadmap
• Contributing
• License

---

🎯 The Problem

Modern codebases are complex labyrinths—thousands of files, intricate dependencies, and evolving architectures. AI assistants like ChatGPT and Claude are brilliant... but they're flying blind. Without deep understanding of your codebase's structure, relationships, and patterns, they can only see the trees, never the forest.

💡 The Solution

Axon.MCP.Server transforms your entire codebase into an intelligent, queryable knowledge base using the Model Context Protocol (MCP). Think of it as giving your AI assistant X-ray vision into your code—understanding not just syntax, but semantics, architecture, and relationships.

Why Axon Stands Out

• 🧠 Semantic Understanding: Goes beyond grep to understand what code means, not just what it says
• 🔗 Relationship Mapping: Automatically builds call graphs, inheritance trees, and dependency networks
• 🤖 AI-Native Integration: Built specifically for ChatGPT, Claude, Cursor IDE, and other MCP-enabled tools
• 📊 Multi-Language Mastery: Deep analysis for C# (Roslyn), Python, JavaScript, TypeScript
• 🔍 Vector-Powered Search: Find code by meaning using semantic embeddings
• 🏗️ Architecture Intelligence: Auto-detects services, APIs, Entity Framework mappings, design patterns
• ⚡ Production-Ready Performance: <500ms p95 latency, handles 10,000+ files with ease
• 🔐 Enterprise Security: JWT auth, RBAC, audit logging, rate limiting—not a toy project

---

� See It In Action

---

🏗️ Architecture Overview

10-Service Microarchitecture

┌─────────────────────────────────────────────────────────────┐
│  Client Layer: AI Assistants, IDEs, React UI, REST Clients │
└─────────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            │               │               │
┌───────────▼────┐  ┌──────▼──────┐  ┌────▼──────┐
│  MCP Server    │  │  REST API   │  │  React UI │
│    :8001       │  │    :8080    │  │    :80    │
└───────┬────────┘  └──────┬──────┘  └───────────┘
        │                  │
        │         ┌────────┼────────┐
        │         │        │        │
        │    ┌────▼───┐ ┌─▼────┐ ┌─▼─────────┐
        │    │ Worker │ │ Beat │ │ Enrichment│
        │    │ (Sync) │ │ Sched│ │  Worker   │
        │    └────┬───┘ └──────┘ └─────┬─────┘
        │         │                     │
    ┌───▼─────────▼─────────────────────▼──────┐
    │  Analysis: Tree-sitter + Roslyn + EF     │
    └───────────────────┬──────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
┌───────▼──────┐  ┌────▼────┐  ┌──────▼────────┐
│ PostgreSQL   │  │  Redis  │  │ Prometheus +  │
│ + pgvector   │  │ Cache   │  │   Grafana     │
└──────────────┘  └─────────┘  └───────────────┘

Technology Stack

Backend: FastAPI, Celery, SQLAlchemy 2.0 (async), Python 3.11+
Parsing: Tree-sitter (multi-lang), Roslyn (C# semantic analysis)
Database: PostgreSQL 15 + pgvector, Redis
AI/ML: OpenAI/OpenRouter (LLM), sentence-transformers (embeddings)
Frontend: React + TypeScript, Vite
Infrastructure: Docker Compose, Prometheus, Grafana

---

🔌 MCP Tools for AI Assistants

The server exposes 12 powerful tools to AI assistants via the Model Context Protocol:

Tool	Description	Use Case
search	Semantic + full-text code search	"Find all authentication controllers"
get_call_graph	Function call relationships	"Who calls UserService.CreateUser?"
get_inheritance_hierarchy	Class inheritance tree	"Show me all BaseController implementations"
get_api_endpoints	List REST API routes	"What endpoints modify the User table?"
get_ef_entities	Entity Framework mappings	"Show database schema for Orders"
get_module_summary	AI-generated code summaries	"Explain what PaymentService does"
explore_service	Navigate service architecture	"Show me the API service structure"
find_implementations	Interface implementations	"Find all IRepository implementations"
get_system_architecture_map	Generate architecture diagrams	"Visualize system dependencies"
get_symbol_details	Detailed symbol info	"Show UserController.Login signature"
get_file_symbols	List symbols in a file	"What's in AuthService.cs?"
get_repository_structure	Project/solution organization	"Show .NET solution structure"

---

✨ Key Features

🔬 1. Hybrid Python/C# Analysis Engine

• Tree-sitter: Lightning-fast syntactic parsing for Python, JavaScript, TypeScript, and C#
• Roslyn Subprocess: Compiler-grade semantic analysis for C# (type resolution, cross-file references, metadata)
• EF Core Analyzer: Extracts Entity Framework entities, table mappings, and relationships automatically

🗂️ 2. Intelligent Code Indexing

• 🔄 Automatically discovers repositories from GitLab/Azure DevOps
• 🏷️ Extracts symbols (classes, functions, variables) with rich metadata (docstrings, parameters, return types)
• 📞 Builds call graphs, inheritance hierarchies, and import dependency maps
• 🏗️ Detects services, APIs, workers, and libraries with auto-classification
• 🧮 Generates vector embeddings for semantic search powered by pgvector

🤖 3. AI-Powered Enrichment

• 📝 LLM-generated summaries for symbols and modules (using OpenRouter/OpenAI)
• ⚡ Parallel processing with 8-worker Celery pipeline for blazing speed
• 💾 Smart caching to avoid re-generation and reduce API costs

📊 4. Production-Grade Observability

• 📈 Pre-configured Prometheus metrics (API latency, sync status, search performance, cache hit rates)
• 📉 Beautiful Grafana dashboards for real-time monitoring
• 📄 Structured JSON logging with structlog for easy parsing
• 📡 Real-time sync progress via Redis Pub/Sub for responsive UI updates

🔐 5. Enterprise Security

• 🔑 JWT authentication + API keys for flexible auth strategies
• 👥 Role-based access control (admin, readonly) for granular permissions
• 🍪 HTTP-only cookies with CSRF protection
• ⏱️ Rate limiting and comprehensive audit logging

---

📊 Data Model Highlights

The system maintains a rich relational model:

• Repositories: Source control repos (GitLab/Azure DevOps)
• Files: Source code files with content hashes
• Symbols: Functions, classes, variables with AI enrichment
• Relations: Inherits, implements, calls, references, imports
• Services: Detected APIs, workers, libraries
• EfEntities: Entity Framework → database table mappings
• Embeddings: pgvector embeddings for semantic search
• Chunks: Code chunks (function/class level) for RAG

Total Tables: 14 with optimized indexes, cascading deletes, unique constraints

---

🚀 Quick Start

Get up and running in 5 minutes with Docker Compose.

Prerequisites

• 🐳 Docker & Docker Compose installed
• 🐍 Python 3.11+ (for local development)
• 🔑 GitLab or Azure DevOps access token

Step 1: Clone & Configure

# Clone the repository
git clone https://github.com/ali-kamali/Axon.MCP.Server.git
cd axon.mcp.server

# Copy environment template
cp .env.example .env

Edit .env with your credentials:

# Source control (choose one)
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
# OR
AZUREDEVOPS_PASSWORD=your-azure-devops-pat

# Security (generate strong keys)
ADMIN_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
ADMIN_PASSWORD=your-secure-password

# Optional: AI enrichment (for LLM-generated code summaries)
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx

Step 2: Launch Services

# Start all services (PostgreSQL, Redis, API, Workers, UI, Monitoring)
make docker-up

# Run database migrations
make migrate

# Verify health
curl http://localhost:8080/api/v1/health
# ✅ Expected: {"status":"ok"}

Step 3: Access Your Platform

🎯 Service	🌐 URL	🔐 Credentials
React Dashboard	http://localhost:80	Login with ADMIN_PASSWORD
REST API Docs	http://localhost:8080/api/docs	X-API-Key: ADMIN_API_KEY
MCP Server	http://localhost:8001	For AI assistants (see MCP Tools)
Grafana	http://localhost:3000	admin / admin
Prometheus	http://localhost:9090	No auth

🎉 You're Ready!

Next Steps:

1. 📊 View the React Dashboard and add your first repository
2. 🔍 Try a semantic search: "Find all authentication controllers"
3. 🤖 Connect an AI assistant using the MCP server
4. 📈 Monitor performance in Grafana dashboards

💡 Pro Tip: Check out the Development Guide for local development setup and testing.

---

🎯 Use Cases

🚀 Primary: AI IDE Integration (Cursor, AntiGravity, VS Code)

The main purpose of Axon MCP Server is to provide deep code intelligence to AI-powered IDEs:

Cursor IDE

1. Contextual Code Completion: AI understands your entire codebase structure
2. Intelligent Chat: Ask questions about architecture, dependencies, and implementation details
3. Semantic Code Search: Find code by what it does, not just what it's called
4. Refactoring Assistance: AI knows all usages across your entire codebase

Google AntiGravity

1. Vibe Coding Intelligence: Deep understanding of code patterns and architecture
2. Cross-Repository Context: Work with multiple projects seamlessly
3. Smart Code Generation: AI suggestions based on your actual codebase patterns
4. Real-Time Documentation: Instant explanations of complex code sections

Other MCP-Enabled Tools

• Claude Desktop: Ask natural language questions about your codebase
• ChatGPT with MCP: Deep code analysis and architectural insights
• Custom MCP Clients: Build your own AI-powered dev tools

📊 For Development Teams

1. Onboarding: New developers can ask "How does authentication work?" and get comprehensive answers
2. Code Review: AI-assisted review with full context of dependencies and impacts
3. Documentation: Auto-generated explanations for complex modules
4. Impact Analysis: "What breaks if I change this API?" with complete dependency traces

🔍 For Software Architects

1. Architecture Visualization: Auto-generated service dependency diagrams
2. Design Pattern Detection: Identify patterns and anti-patterns across the codebase
3. Technical Debt Analysis: Find complex, tightly-coupled code sections
4. Migration Planning: Understand all dependencies before major refactors

---

📚 Documentation

🏗 Architecture

• Overview - System architecture and core components
• Data Models - Database schema and relationships
• Infrastructure - Deployment and scaling

📖 Guides

• Setup Guide - Prerequisites and installation
• Development Guide - Dev environment setup and testing
• Deployment Guide - Docker and Kubernetes deployment
• Security Guide - Security features and best practices

🔌 API & Tools

• REST API Reference - API endpoints and usage
• MCP Tools Reference - MCP tools for AI assistants

⚙️ Reference

• Configuration - Environment variables
• Troubleshooting - Common issues and solutions

---

🔧 Development

# Install dependencies
make dev-install

# Run tests
make test

# Start API (dev mode with hot reload)
make api-dev

# Start MCP server
make mcp-dev

# Start UI
make ui-dev

# Lint and format
make lint
make format

---

🌟 What Makes This Special?

1. Hybrid Intelligence: Syntactic (Tree-sitter) + Semantic (Roslyn) analysis
2. AI-First Design: Built specifically to feed AI assistants with code context
3. Production-Grade: Real auth, monitoring, distributed processing, caching
4. Multi-Source: Supports GitLab and Azure DevOps
5. Deep C# Support: Compiler-grade analysis via Roslyn
6. Semantic Search: Vector embeddings enable "find similar code" queries
7. Architectural Awareness: Detects services, APIs, entities—not just functions

---

🗺️ Roadmap

This project is actively maintained and continuously evolving. Here's what's on our horizon:

✅ Completed (v3.2 - Current)

• API Authentication: JWT tokens + API keys for hybrid auth scenarios
• Hybrid Authentication: UI login with cookies + programmatic API key access
• Memory Optimization: Keyset pagination for efficient large dataset handling
• Vector Search: Semantic code search powered by pgvector embeddings
• Multi-Language Support: Python, JavaScript, TypeScript, C# (via Roslyn)

🚧 In Progress (v3.2 → v3.3)

• Roslyn Process Manager Refactor: Improved stability and resource management
• Pipeline Pattern Refactor: More modular and testable processing architecture

🎯 Next Release (v3.3 - Q1 2026)

• RAG Pipeline: Ask natural language questions about your codebase ("How does auth work?")
• Architecture Visualization: Auto-generate Mermaid/PlantUML diagrams from code structure
• Impact Analysis Tool: See what breaks before you change it ("What depends on UserService?")
• Conversation Memory: Multi-turn AI conversations with context retention

🚀 Future Enhancements (v4.0+)

• AI Test Generation: Automatically generate unit tests for your code
• Code Review Assistant: AI-powered PR reviews with security and quality checks
• Complexity Heatmaps: Visual complexity analysis to identify refactoring candidates
• Dependency Audit: Track and visualize package dependencies and vulnerabilities
• Language Expansion: Java, Go, Rust, Ruby, PHP support
• IDE Plugins: Native plugins for VS Code, JetBrains IDEs
• Collaboration Features: Team annotations, shared searches, codebase bookmarks

💡 Have a feature idea? Open an issue on our GitLab repository!

---

📄 License & Commercial Use

Axon.MCP.Server is dual-licensed to ensure sustainability and rapid development.

1. Open Source (AGPLv3)

This project is free software under the GNU Affero General Public License v3.0 (AGPLv3).

• Best for: Open-source projects, hobbyists, researchers, and educational use.
• The Rule: If you modify this code or use it in a service accessible over a network, you must open-source your own project under the same AGPLv3 license.
• Details: See the LICENSE file for complete terms.

2. Commercial License (Enterprise)

Want to integrate Axon into a proprietary/closed-source product?

• Best for: Startups, Enterprises, and SaaS products who cannot open-source their code.
• Benefits:
  • Release your product under your own proprietary license
  • No requirement to share your source code
  • Priority support and direct access to the maintainer
  • Legal indemnification options
  • Custom features and integrations

📩 Contact us to acquire a commercial license.

---

Why Dual Licensing?

We believe in open source and sustainability. The AGPLv3 ensures the community benefits from improvements, while commercial licenses fund continued development, comprehensive testing, and enterprise features that benefit everyone.

---

🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, or documentation improvements, your help makes this project better.

1. The "Reality" Check: CLA

Since this project is dual-licensed, we must ensure we have the legal right to distribute contributions.

Before merging any PR, we ask contributors to reply to a comment saying:

"I hereby assign copyright of this contribution to the project maintainers and agree to the terms of the Contributor License Agreement."

2. Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

3. Guidelines

• 📘 Development Guide - Setup, coding standards, and best practices
• ✅ Code Quality: We use Black, mypy, and pylint for code quality
• 🧪 Testing: Maintain >80% test coverage for all new code
• 🔄 Pull Requests: Follow our PR template and ensure CI passes

---

📞 Support & Community

Need help or want to discuss features?

• 🐛 Bug Reports: GitHub Issues
• 📖 Documentation: Browse the docs/ directory
• 💬 Community: Join us on #axon-mcp-server (internal Slack)
• ❓ Questions: Open a discussion or issue on GitHub

---