Content
<div align="center">
<!-- Banner Placeholder - Replace with actual logo/banner image -->
<img src="assets/axon-mcp-banner.png" alt="Axon MCP Server Banner" width="800"/>
# 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*
---
[](https://www.python.org/downloads/)
[](LICENSE)
[](#-license--commercial-use)
[](https://github.com/ali-kamali/Axon.MCP.Server/actions/workflows/ci.yml)
[](https://github.com/ali-kamali/Axon.MCP.Server/pkgs/container/axon-mcp-server)
[]()
[](https://modelcontextprotocol.io)
[](https://ali-kamali.github.io/Axon.MCP.Server/)
[]()
</div>
---
## 📋 Table of Contents
- [The Problem](#-the-problem)
- [The Solution](#-the-solution)
- [See It In Action](#-see-it-in-action)
- [Architecture Overview](#️-architecture-overview)
- [MCP Tools for AI Assistants](#-mcp-tools-for-ai-assistants)
- [Key Features](#-key-features)
- [Quick Start](#-quick-start)
- [Use Cases](#-use-cases)
- [Documentation](#-documentation)
- [Development](#-development)
- [Roadmap](#️-roadmap)
- [Contributing](#-contributing)
- [License](#-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
<div align="center">
### 🤖 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
*Axon MCP providing deep code context to Google AntiGravity for intelligent code assistance*
#### Cursor IDE - AI-First Code Editor
*Real-time code intelligence powered by Axon's semantic understanding in Cursor*
---
### 🏛️ Management Dashboard
*Real-time monitoring of code analysis and synchronization*
### 🛠️ Architecture Visualization
*Auto-generated service dependency diagrams*
</div>
---
## 🏗️ 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
```bash
# 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:**
```bash
# 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
```bash
# 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](http://localhost:80) | Login with `ADMIN_PASSWORD` |
| **REST API Docs** | [http://localhost:8080/api/docs](http://localhost:8080/api/docs) | `X-API-Key: ADMIN_API_KEY` |
| **MCP Server** | `http://localhost:8001` | For AI assistants (see [MCP Tools](docs/api/mcp_tools.md)) |
| **Grafana** | [http://localhost:3000](http://localhost:3000) | `admin / admin` |
| **Prometheus** | [http://localhost:9090](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](docs/guides/development.md) 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](https://ali-kamali.github.io/Axon.MCP.Server/architecture/overview/) - System architecture and core components
- [Data Models](https://ali-kamali.github.io/Axon.MCP.Server/architecture/data_models/) - Database schema and relationships
- [Infrastructure](https://ali-kamali.github.io/Axon.MCP.Server/architecture/infrastructure/) - Deployment and scaling
### 📖 Guides
- [Setup Guide](https://ali-kamali.github.io/Axon.MCP.Server/guides/setup/) - Prerequisites and installation
- [Development Guide](https://ali-kamali.github.io/Axon.MCP.Server/guides/development/) - Dev environment setup and testing
- [Deployment Guide](https://ali-kamali.github.io/Axon.MCP.Server/guides/deployment/) - Docker and Kubernetes deployment
- [Security Guide](https://ali-kamali.github.io/Axon.MCP.Server/guides/security/) - Security features and best practices
### 🔌 API & Tools
- [REST API Reference](https://ali-kamali.github.io/Axon.MCP.Server/api/rest_api/) - API endpoints and usage
- [MCP Tools Reference](https://ali-kamali.github.io/Axon.MCP.Server/api/mcp_tools/) - MCP tools for AI assistants
### ⚙️ Reference
- [Configuration](docs/reference/configuration.md) - Environment variables
- [Troubleshooting](docs/reference/troubleshooting.md) - Common issues and solutions
---
## 🔧 Development
```bash
# 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)
- [x] **API Authentication**: JWT tokens + API keys for hybrid auth scenarios
- [x] **Hybrid Authentication**: UI login with cookies + programmatic API key access
- [x] **Memory Optimization**: Keyset pagination for efficient large dataset handling
- [x] **Vector Search**: Semantic code search powered by pgvector embeddings
- [x] **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](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](mailto:your-email@example.com)** 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](docs/guides/development.md) - 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](https://github.com/ali-kamali/Axon.MCP.Server/issues)
- 📖 **Documentation**: Browse the [`docs/`](docs/) directory
- 💬 **Community**: Join us on `#axon-mcp-server` (internal Slack)
- ❓ **Questions**: Open a discussion or issue on GitHub
---
<div align="center">
**Built with ❤️ by the Axon DevOps Team**
*Empowering developers with AI-driven code intelligence*
[](https://github.com/ali-kamali/Axon.MCP.Server)
</div>
