Axon.MCP.Server

# Axon.MCP.Server **Model Context Protocol (MCP) Server for AI IDEs - Cursor, AntiGravity & Claude** *Transform your codebase into an intelligent knowledge base for AI-powered development with Cursor IDE, Google AntiGravity, and MCP-enabled assistants* --- [![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial License](https://img.shields.io/badge/License-Commercial_Available-purple.svg)](#-license--commercial-use) [![Build Status](https://github.com/ali-kamali/Axon.MCP.Server/actions/workflows/ci.yml/badge.svg?branch=public-release)](https://github.com/ali-kamali/Axon.MCP.Server/actions/workflows/ci.yml) [![Docker Image](https://img.shields.io/badge/docker-GHCR-blue.svg)](https://github.com/ali-kamali/Axon.MCP.Server/pkgs/container/axon-mcp-server) [![Coverage](https://img.shields.io/badge/coverage-85%25-yellowgreen.svg)]() [![MCP Protocol](https://img.shields.io/badge/MCP-v1.0-purple.svg)](https://modelcontextprotocol.io) [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](docs/) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)]()

🎯 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

### 🤖 AI IDE Integration - The Main Use Case **Axon MCP Server seamlessly integrates with leading AI-powered IDEs to supercharge your development workflow** #### Google AntiGravity - Best AI IDE for Vibe Coders ![AntiGravity Integration](assets/screenshots/AntiGravity.png) *Axon MCP providing deep code context to Google AntiGravity for intelligent code assistance* #### Cursor IDE - AI-First Code Editor ![Cursor Integration](assets/screenshots/Cursor.png) *Real-time code intelligence powered by Axon's semantic understanding in Cursor* --- ### 🏛️ Management Dashboard ![Axon Dashboard](assets/screenshots/dashboard.png) *Real-time monitoring of code analysis and synchronization* ### 🛠️ Architecture Visualization ![Architecture Map](assets/architecture-diagram.jpg) *Auto-generated service dependency diagrams*

🏗️ 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:

📊 View the React Dashboard and add your first repository
🔍 Try a semantic search: “Find all authentication controllers”
🤖 Connect an AI assistant using the MCP server
📈 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

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

Google AntiGravity

Vibe Coding Intelligence: Deep understanding of code patterns and architecture
Cross-Repository Context: Work with multiple projects seamlessly
Smart Code Generation: AI suggestions based on your actual codebase patterns
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

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

🔍 For Software Architects

Architecture Visualization: Auto-generated service dependency diagrams
Design Pattern Detection: Identify patterns and anti-patterns across the codebase
Technical Debt Analysis: Find complex, tightly-coupled code sections
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?

Hybrid Intelligence: Syntactic (Tree-sitter) + Semantic (Roslyn) analysis
AI-First Design: Built specifically to feed AI assistants with code context
Production-Grade: Real auth, monitoring, distributed processing, caching
Multi-Source: Supports GitLab and Azure DevOps
Deep C# Support: Compiler-grade analysis via Roslyn
Semantic Search: Vector embeddings enable “find similar code” queries
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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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 documentation
💬 Community: Join us on #axon-mcp-server (internal Slack)
❓ Questions: Open a discussion or issue on GitHub

**Built with ❤️ by the Axon DevOps Team** *Empowering developers with AI-driven code intelligence* [![Star on GitHub](https://img.shields.io/badge/⭐-Star%20Us%20on%20GitHub-orange)](https://github.com/ali-kamali/Axon.MCP.Server)

This site is open source. Improve this page.