mcp-context

Servidor local del Protocolo de Contexto de Modelo (MCP) con búsqueda semántica (RAG) sobre repositorios de código. Expone el contexto de múltiples proyectos a clientes de IA externos — Claude.ai, Gemini, Claude Code — eliminando la necesidad de volver a pasar el contexto manualmente en cada sesión.

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

Requisitos previos

Asegúrese de que los siguientes elementos estén instalados antes de continuar:

Se requiere una cuenta de Cloudflare con un dominio activo para la conectividad remota (Fase 3).

Related MCP server: mcplens

Instalación

# 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

Nota sobre GITHUB_TOKEN: El archivo .env incluye una variable GITHUB_TOKEN para acceso de lectura a los repositorios. Para obtener este token, vaya a Settings > Developer settings > Personal access tokens en GitHub. Genere un nuevo token y péguelo en su archivo .env.

Configuración

1. Variables de entorno

Edite el archivo .env creado en el paso anterior:

# 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. Configurar Cloudflare Tunnel

# 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

Cree cloudflared/config.yml en la raíz del proyecto (este archivo está ignorado por git). Reemplace <id> con el UUID impreso por el comando tunnel create anterior:

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. Crear el frontend

Este paso solo es necesario una vez. Crea el proyecto Next.js y elimina el .git/ interno automáticamente:

make frontend-setup

4. Indexar el primer proyecto

Abra el frontend, añada una ruta de proyecto y active la indexación:

make frontend
# Access http://localhost:17801

O ejecute el indexador directamente desde la terminal:

make index

Ejecución local (desarrollo)

Para iniciar el servidor MCP con recarga automática (recomendado durante el desarrollo):

make dev

Esto inicia Qdrant, el túnel de Cloudflare y el servidor MCP con la recarga en caliente habilitada. El servidor se reinicia automáticamente con cada cambio de archivo en server/.

Para iniciar todos los servicios en segundo plano (servidor MCP, frontend, túnel, Qdrant):

make server-dev

Servicios disponibles:

Los registros en tiempo real están disponibles en 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

Para detener todo:

make stop

Despliegue local (todos los servicios en contenedores)

Para ejecutar el proyecto completamente en contenedores — útil para simular el entorno de producción o hacer que todo se inicie junto con Docker:

# 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

Advertencia: asegúrese de que PROJECTS_ROOT en .env apunte al directorio correcto antes de ejecutar prod-up. El contenedor del servidor MCP monta esa ruta para acceder a los archivos locales.

Comandos make

Estructura del repositorio

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

Limitaciones conocidas

• El servidor depende de que la máquina local esté encendida para funcionar de forma remota a través del túnel de Cloudflare

• El índice de Qdrant refleja el estado del código en el momento de la última indexación — configure un hook post-commit para mantener el índice actualizado automáticamente después de cada confirmación (commit)

• Los archivos binarios, imágenes y activos no se indexan

• El modelo de incrustación (jina-embeddings-v2-base-code, ~160 MB) se descarga automáticamente en la primera ejecución a través de sentence-transformers

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers