AIStack MCP

🚀 AIStack-MCP

Enterprise-Grade MCP Orchestration for Modern Development

Dual-mode MCP orchestration that solves the isolation vs. coordination dilemma—local-first, production-ready, and 90% cheaper than cloud-only approaches.

[](https://github.com/mjdevaccount/AIStack-MCP) [](https://github.com/mjdevaccount/AIStack-MCP/releases) [](LICENSE) [](https://github.com/mjdevaccount/AIStack-MCP) [](https://python.org) [](https://github.com/psf/black)

---

📊 Current Status (v1.2.0)

Latest Release: v1.2.0 — MCP Registry Integration & Template System

What's New in v1.2.0

| Feature | Status | Description | |---------|--------|-------------| | 🗂️ MCP Registry | ✅ NEW | Browse and install 500+ community MCP servers | | 📋 Template System | ✅ NEW | Pre-built configs (minimal, standard, full) | | 🔧 Server Installer | ✅ NEW | One-command installation for npm/PyPI/Docker servers | | 🔍 Registry Search | ✅ NEW | Search by keywords, category, runtime | | 🧠 Code Intelligence | ✅ Stable | Semantic search, pattern analysis, code generation | | 🔄 Dual-Mode | ✅ Stable | Single-repo isolation & multi-repo orchestration | | ✅ 88 Tests Passing | ✅ Stable | Comprehensive test coverage |

Quick Stats

• Community Servers: 500+ available via registry
• Templates: 3 pre-built configurations
• Test Coverage: 88 unit tests passing
• Documentation: 15+ guides and troubleshooting docs
• Production Ready: CI/CD validated, enterprise-tested

---

💡 Why This Matters

> The Problem: MCP servers require careful isolation for security, but modern development often spans multiple repositories. You're forced to choose between safe isolation (one repo at a time) or productivity (cross-repo intelligence). > > The Solution: AIStack-MCP provides dual-mode orchestration—switch between isolated single-repo mode and coordinated multi-repo mode with a single command. Get the best of both worlds.

Key Differentiators

| What Makes This Different | Why It Matters | |---------------------------|----------------| | 🔄 One-command mode switching | Switch context in seconds, not minutes | | 🏗️ 2025 proven patterns | Git multi-repo support, MCP coordination | | 🔒 Production-ready security | Workspace isolation, explicit permissions | | 💰 90% cost reduction | Local LLM + vector search = FREE intelligence | | ✅ Enterprise validation | CI-ready scripts, health checks, monitoring |

---

📑 Table of Contents

• [✨ Features](#-features)
• [🏗️ Architecture](#️-architecture)
• [🚀 Quick Start](#-quick-start)
• [📦 Installation](#-installation)
• [🔄 Operating Modes](#-operating-modes)
• [📖 Usage Guide](#-usage-guide)
• [📁 Project Structure](#-project-structure)
• [🛠️ Tools Reference](#️-tools-reference)
• [⚡ Performance & Cost](#-performance--cost)
• [🔧 Troubleshooting](#-troubleshooting)
• [❓ FAQ](#-faq)
• [🎓 Advanced Topics](#-advanced-topics)
• [🗺️ Roadmap](#️-roadmap)
• [🤝 Contributing](#-contributing)
• [📄 License](#-license)

---

✨ Features

Core Capabilities

| Feature | Description | |---------|-------------| | 🔒 Single-Repo Isolation | Portable ${workspaceFolder} configs, maximum security, per-project permissions | | 🌐 Multi-Repo Orchestration | Cross-repo semantic search, unified context, CORE workspace coordination | | ⚡ One-Command Switching | switch_to_single_repo.ps1 / switch_to_multi_repo.ps1 with automatic validation | | 🩺 Health Monitoring | Real-time service checks, dependency validation, configuration verification | | 🧠 Local-First AI | Ollama (LLM inference) + Qdrant (vector search) = 100% local, 100% private | | 💰 90% Cost Reduction | Pre-process with local AI, send only compressed context to Claude | | 🌍 Universal Compatibility | Works with Python, TypeScript, Rust, Go, Java—any language, any framework |

Developer Experience

| Feature | Description | |---------|-------------| | 🧙 Interactive Setup Wizard | quickstart.ps1 guides new users through complete setup | | 🔍 CI-Ready Validation | validate_mcp_config.py with --strict mode for zero-warning builds | | 📊 Dev Environment Dashboard | dev_all.ps1 shows service status, models, collections at a glance | | 📚 Comprehensive Documentation | Troubleshooting guides, best practices, real-world examples | | 🏭 Production-Tested Patterns | Battle-tested configurations from enterprise deployments |

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    YOUR CODEBASE                                    │
│              (Any Language • Any Framework • Any Size)              │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                 AISTACK-MCP ORCHESTRATION LAYER                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐  │
│  │   Filesystem    │  │      Git        │  │  Code Intelligence  │  │
│  │      MCP        │  │      MCP        │  │        MCP          │  │
│  │  (Read/Write)   │  │  (History/Diff) │  │  (Search/Analyze)   │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘  │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  Mode Orchestrator: Single-Repo ←→ Multi-Repo Switching     │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    LOCAL AI STACK (FREE)                            │
│                                                                     │
│  ┌─────────────────────────┐    ┌─────────────────────────────┐    │
│  │        OLLAMA           │    │          QDRANT             │    │
│  │  • LLM Inference        │    │  • Vector Search            │    │
│  │  • Pattern Analysis     │    │  • Semantic Indexing        │    │
│  │  • Code Generation      │    │  • 90% Token Compression    │    │
│  └─────────────────────────┘    └─────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    CURSOR + CLAUDE                                  │
│           (Final Generation Only • Minimal Token Usage)             │
└─────────────────────────────────────────────────────────────────────┘

Data Flow & Cost Savings

1. You ask a question → Cursor receives your prompt
2. Local search first → Qdrant finds relevant code chunks (FREE)
3. Local compression → Ollama summarizes context (FREE)
4. Minimal transmission → Only 500-1000 tokens sent to Claude
5. Final generation → Claude generates with full understanding

Result: 90% fewer tokens, same quality, 100% privacy for local processing.

---

🚀 Quick Start

Path 1: New Users (Recommended)

# Clone and run the interactive wizard
git clone https://github.com/mjdevaccount/AIStack-MCP.git
cd AIStack-MCP
.\scripts\quickstart.ps1

The wizard automatically:

• ✅ Checks all dependencies
• ✅ Guides mode selection
• ✅ Configures services
• ✅ Validates setup

Path 2: Experienced Users

📋 Click to expand manual setup

# 1. Clone repository
git clone https://github.com/mjdevaccount/AIStack-MCP.git
cd AIStack-MCP

# 2. Install Python dependencies
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 3. Start services
ollama serve                                    # Terminal 1
docker run -d -p 6333:6333 qdrant/qdrant       # Terminal 2

# 4. Pull required models
ollama pull mxbai-embed-large
ollama pull qwen2.5:7b

# 5. Configure mode
.\scripts\switch_to_single_repo.ps1

# 6. Open in Cursor
cursor .

Path 3: CI/CD Integration

# .github/workflows/validate.yml
- name: Validate MCP Configuration
  run: |
    python scripts/validate_mcp_config.py --test-generation --strict

---

🌐 Community Tools (v1.2.0)

Browse 500+ MCP Servers

Search for tools

.\scripts\list_registry_tools.ps1 -Search "database"

Popular servers

.\scripts\list_registry_tools.ps1 -Popular

Install Community Tools

Install PostgreSQL server

.\scripts\install_community_tool.ps1 -ServerId "io.modelcontextprotocol/server-postgres"

Install Slack integration

.\scripts\install_community_tool.ps1 -ServerId "io.modelcontextprotocol/server-slack"

Apply Templates

Minimal (search only)

.\scripts\apply_template.ps1 -Template minimal

Standard (recommended)

.\scripts\apply_template.ps1 -Template standard

Full (all features)

.\scripts\apply_template.ps1 -Template full

See [Registry Documentation](docs/REGISTRY.md) for full guide.

---

📦 Installation

System Requirements

| Requirement | Minimum | Recommended | |-------------|---------|-------------| | OS | Windows 10 | Windows 11 | | Python | 3.8 | 3.11+ | | Node.js | 18.x | 20.x LTS | | RAM | 8 GB | 16 GB | | Disk | 10 GB | 20 GB (for models) | | Docker | Optional | Recommended |

Step 1: Prerequisites

# Install Node.js (for MCP community servers)
winget install OpenJS.NodeJS

# Install Python (if not present)
winget install Python.Python.3.11

# Verify installations
node --version   # Should show v18+
python --version # Should show 3.8+

Step 2: Python Dependencies

cd C:\AIStack-MCP

# Create virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

Step 3: Local AI Services

🦙 Ollama Setup

1. Download from ollama.ai
2. Install and start the service
3. Pull required models:

ollama pull mxbai-embed-large  # Required: embeddings
ollama pull qwen2.5:7b         # Recommended: analysis
ollama pull phi4:14b           # Optional: code generation

1. Verify:

ollama list

🔍 Qdrant Setup

Option A: Docker (Recommended)

docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant

Option B: Native Installation

• Download from qdrant.tech

Verify:

curl http://localhost:6333/collections

Step 4: Configuration

# Run the quickstart wizard (recommended)
.\scripts\quickstart.ps1

# Or manually configure single-repo mode
.\scripts\switch_to_single_repo.ps1

> 💡 Tip: If Cursor hangs on startup, ensure you're using the cmd /c wrapper pattern. See [Windows MCP Fix](docs/troubleshooting/WINDOWSMCPFIX.md).

---

🔄 Operating Modes

Mode Comparison

| Feature | Single-Repo Mode | Multi-Repo Mode | |---------|------------------|-----------------| | Isolation | ✅ Maximum (per-repo) | ⚠️ Shared (CORE access) | | Portability | ✅ ${workspaceFolder} | ✅ Relative paths | | Security | ✅ Explicit permissions | ⚠️ CORE has all access | | Cross-repo search | ❌ One repo only | ✅ All linked repos | | Setup complexity | ⭐ Simple | ⭐⭐ Requires linking | | Best for | Focused work, security | Multi-package, microservices |

Switching Modes

# Switch to single-repo (isolated, portable)
.\scripts\switch_to_single_repo.ps1

# Switch to multi-repo (orchestrated)
.\scripts\switch_to_multi_repo.ps1

# Check current mode
Get-Content .cursor\ACTIVE_MODE.txt

Multi-Repo Setup

# 1. Link repositories (requires Admin for symlinks)
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\backend-api"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\frontend-app"

# 2. Or clone directly (no Admin required)
.\scripts\link_repo.ps1 -TargetPath "https://github.com/org/repo" -Clone

# 3. Activate multi-repo mode
.\scripts\switch_to_multi_repo.ps1

# 4. Restart Cursor

---

📖 Usage Guide

Scenario 1: First-Time Setup

# 1. Run quickstart wizard
.\scripts\quickstart.ps1

# 2. Open project in Cursor
cursor C:\AIStack-MCP

# 3. In Cursor chat, index your workspace
Use code-intelligence to index_workspace

# 4. Verify setup
Use code-intelligence to validate_workspace_config

Expected Output:

✅ Workspace: C:\AIStack-MCP (accessible)
✅ Ollama: Connected (3 models available)
✅ Qdrant: Connected (1 collection indexed)
✅ Configuration: Valid

Scenario 2: Daily Development

# Semantic search (find code by meaning)
Use code-intelligence to semantic_search for "error handling patterns"

# Pattern analysis (extract patterns with LLM)
Use code-intelligence to analyze_patterns for "async"

# Get optimized context for a file
Use code-intelligence to get_context for src/utils.py with task "add retry logic"

# Generate code matching project style
Use code-intelligence to generate_code for src/api.py with task "add pagination"

Scenario 3: Multi-Repo Development

# Morning: Link all related repos
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\shared-libs"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\backend"
.\scripts\link_repo.ps1 -TargetPath "C:\Projects\frontend"

# Activate multi-repo mode
.\scripts\switch_to_multi_repo.ps1

# Now in Cursor: search across ALL linked repos
Use code-intelligence to semantic_search for "authentication flow"

Scenario 4: Team Onboarding

Share these commands with new team members:

# Complete setup in one command
git clone https://github.com/your-org/AIStack-MCP.git
cd AIStack-MCP
.\scripts\quickstart.ps1

Reference: [docs/BESTPRACTICES.md](docs/BESTPRACTICES.md)

---

📁 Project Structure

AIStack-MCP/
├── .cursor/
│   ├── mcp.json                  # 🎯 Active MCP configuration
│   └── ACTIVE_MODE.txt           # 📍 Current mode indicator
│
├── docs/
│   ├── WORKSPACE_PATTERN.md      # 📐 Isolation best practices
│   ├── BEST_PRACTICES.md         # 👥 Team usage guidelines
│   ├── SETUP.md                  # 📋 Detailed setup guide
│   └── troubleshooting/          # 🔧 Platform-specific fixes
│       ├── WINDOWS_MCP_FIX.md
│       └── MCP_TROUBLESHOOTING.md
│
├── scripts/
│   ├── quickstart.ps1            # 🌟 Interactive setup wizard
│   ├── switch_to_single_repo.ps1 # 🔒 Activate isolated mode
│   ├── switch_to_multi_repo.ps1  # 🌐 Activate orchestration mode
│   ├── link_repo.ps1             # 🔗 Repository linking helper
│   ├── validate_mcp_config.py    # ✅ CI-ready validation
│   ├── validate_workspace.py     # 🩺 Workspace diagnostics
│   ├── dev_all.ps1               # 📊 Dev environment status
│   └── mcp_config_builder.py     # 🏗️ Config generator
│
├── workspaces/                   # 📂 Multi-repo links (gitignored)
│   └── README.md
│
├── python_agent/                 # 🤖 Agent implementation
│   ├── agents/
│   ├── tools/
│   └── mcp_production_server.py
│
├── mcp_intelligence_server.py    # 🧠 Main MCP server
├── requirements.txt              # 📦 Python dependencies
├── docker-compose.yml            # 🐳 Service orchestration
└── README.md                     # 📖 You are here

---

🛠️ Tools Reference

Available MCP Tools

| Tool | Description | Example | Cost | |------|-------------|---------|------| | semantic_search | Find code by meaning using vector similarity | semantic_search for "retry logic" | FREE | | analyze_patterns | Extract patterns using local LLM | `ana

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mjdevaccount
• Source: mjdevaccount/AIStack-MCP
• License: MIT

Install and usage instructions live in the source repository linked above.