mcp-context

Lokaler Model Context Protocol (MCP) Server mit semantischer Suche (RAG) über Code-Repositories. Stellt den Kontext mehrerer Projekte für externe KI-Clients bereit — Claude.ai, Gemini, Claude Code — und macht es überflüssig, den Kontext bei jeder Sitzung manuell erneut einzugeben.

Stack: Python · FastMCP · Qdrant · sentence-transformers · Next.js · Docker · Cloudflare Tunnel

Voraussetzungen

Stellen Sie sicher, dass die folgenden Elemente installiert sind, bevor Sie fortfahren:

Ein Cloudflare-Konto mit einer aktiven Domain ist für die Remote-Konnektivität erforderlich (Phase 3).

Related MCP server: mcplens

Installation

# 1. Clone the repository
git clone https://github.com/ericlimabr/mcp-context.git
cd mcp-context

# 2. Copy the environment variables file
cp .env.example .env

# 3. Run setup — installs Python dependencies via uv and starts Qdrant
make setup

Hinweis zu GITHUB_TOKEN: Die .env-Datei enthält eine GITHUB_TOKEN-Variable für den Lesezugriff auf Repositories. Um diesen Token zu erhalten, gehen Sie in GitHub zu Settings > Developer settings > Personal access tokens. Generieren Sie einen neuen Token und fügen Sie ihn in Ihre .env-Datei ein.

Konfiguration

1. Umgebungsvariablen

Bearbeiten Sie die im vorherigen Schritt erstellte .env-Datei:

# Root path where your projects are stored on the machine
PROJECTS_ROOT=/home/your-user/projects

# Access password for the administrative panel
ADMIN_PASSWORD=choose-a-strong-password

2. Cloudflare Tunnel konfigurieren

# Authenticate cloudflared with your Cloudflare account
cloudflared tunnel login

# Create the permanent tunnel
cloudflared tunnel create mcp-context

# Associate with your subdomain (replace yourdomain.com)
cloudflared tunnel route dns mcp-context mcp.yourdomain.com

Erstellen Sie cloudflared/config.yml im Projektstammverzeichnis (diese Datei wird von git ignoriert). Ersetzen Sie <id> durch die UUID, die vom oben genannten tunnel create-Befehl ausgegeben wurde:

tunnel: mcp-context
credentials-file: /home/your-user/.cloudflared/<id>.json

ingress:
 - hostname: mcp.yourdomain.com
 service: http://localhost:17800
 - service: http_status:404

3. Frontend erstellen

Dieser Schritt ist nur einmal erforderlich. Er erstellt das Next.js-Projekt und entfernt automatisch das interne .git/:

make frontend-setup

4. Das erste Projekt indizieren

Öffnen Sie das Frontend, fügen Sie einen Projektpfad hinzu und starten Sie die Indizierung:

make frontend
# Access http://localhost:17801

Oder führen Sie den Indexer direkt über das Terminal aus:

make index

Lokal ausführen (Entwicklung)

Um den MCP-Server mit automatischem Neuladen zu starten (empfohlen während der Entwicklung):

make dev

Dies startet Qdrant, den Cloudflare Tunnel und den MCP-Server mit aktiviertem Hot-Reload. Der Server startet bei jeder Dateiänderung in server/ automatisch neu.

Um alle Dienste im Hintergrund zu starten (MCP-Server, Frontend, Tunnel, Qdrant):

make server-dev

Verfügbare Dienste:

Echtzeit-Logs sind verfügbar unter logs/:

tail -f logs/server.log # MCP server
tail -f logs/frontend.log # frontend
tail -f logs/tunnel.log # Cloudflare Tunnel
make qdrant-logs # Qdrant

Um alles zu stoppen:

make stop

Lokale Bereitstellung (alle Dienste in Containern)

Um das Projekt vollständig containerisiert auszuführen — nützlich, um die Produktionsumgebung zu simulieren oder alles zusammen mit Docker zu starten:

# First time: build the images
make prod-build

# Start all containers
make prod-up

# Stop everything
make prod-down

# Real-time logs
make prod-logs

Warnung: Stellen Sie sicher, dass PROJECTS_ROOT in .env auf das korrekte Verzeichnis zeigt, bevor Sie prod-up ausführen. Der MCP-Server-Container bindet diesen Pfad ein, um auf lokale Dateien zuzugreifen.

Make-Befehle

Repository-Struktur

mcp-context/
├── server/ # MCP Server (FastMCP/SSE, port 17800)
│ ├── main.py # Entrypoint and MCP configuration
│ ├── tools/ # MCP tool definitions (planned)
│ ├── resources/ # MCP resource definitions (planned)
│ └── embeddings.py # Local embedding model loading (planned)
├── indexer/ # Project indexing worker (planned)
│ ├── worker.py # Orchestrates indexing
│ ├── chunker.py # Function-scope chunking
│ └── qdrant_client.py # Qdrant client abstraction
├── apps/
│ └── frontend/ # Next.js app — admin panel + dashboard (port 17801)
│ # Generated by make frontend-setup
├── cloudflared/ # Cloudflare Tunnel config (gitignored)
│ └── config.yml
├── docs/
│ ├── ARCHITECTURE.md # Detailed system architecture
│ ├── DECISIONS.md # Architecture decisions
│ ├── ENDPOINTS.md # Endpoints documentation
│ └── ROADMAP.md # Implementation phases
├── logs/ # Service logs in dev (gitignored)
├── .pids/ # Process PIDs in dev (gitignored)
├── qdrant_data/ # Persisted Qdrant data (gitignored)
├── config.json # Project configuration (gitignored)
├── .env # Environment variables (gitignored)
├── .env.example # Environment variables template
├── docker-compose.yml # Qdrant for development
├── docker-compose.prod.yml # All services for local deploy
├── Makefile # Command shortcuts
├── pyproject.toml # Python project and dependencies (uv)
├── CONTEXT.md # Project context for LLMs
└── README.md # This file

Bekannte Einschränkungen

• Der Server ist darauf angewiesen, dass der lokale Rechner eingeschaltet ist, um via Cloudflare Tunnel remote zu funktionieren

• Der Qdrant-Index spiegelt den Zustand des Codes zum Zeitpunkt der letzten Indizierung wider — konfigurieren Sie einen post-commit-Hook, um den Index nach jedem Commit automatisch aktuell zu halten

• Binärdateien, Bilder und Assets werden nicht indiziert

• Das Embedding-Modell (jina-embeddings-v2-base-code, ~160 MB) wird beim ersten Start automatisch via sentence-transformers heruntergeladen

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers