This MCP server framework lets you host multiple self-contained documentation servers that combine hybrid vector search with keyword-based full-text search. Each server processes a documentation source (Markdown/MDX) into semantically meaningful chunks, generates embeddings, and builds an index that supports fast vector similarity (via HNSW) and keyword search (BM25). The results are fused using Reciprocal Rank Fusion to deliver relevant snippets from the documentation. You can run and manage multiple servers from a single configuration, enabling scalable deployment of distinct doc sources such as Mojo manuals, DuckDB docs, or MCP documentation itself. Use the provided tooling to start, stop, and scale servers, and rely on the embedded DuckLake and DuckDB components for versioned data and fast search. If the MAX embedding server is unavailable, the system gracefully falls back to keyword-only search to ensure continued access to results.

Prerequisites:

• Git installed
• Python 3.12+ installed (for Python-based MCP servers)
• Node.js (optional, for certain tooling) or Pixi installed (as the package/automation layer)
• Access to a shell/terminal with network access

Installation steps:

1. Clone the repository: git clone https://github.com/jpotter80/mcp.git cd mcp

2. Install Python dependencies for the Mojo manual MCP server (as an example path from the repo): cd servers/mojo-manual-mcp python -m venv venv source venv/bin/activate # on Windows use venv\Scripts\activate pip install -r requirements.txt

3. Install Pixi (optional but recommended for building/running servers):

   If you don’t have Pixi installed

   npm i -g pixi # or follow official Pixi installation instructions

4. Install dependencies for all servers (example using Pixi workflow): cd ../../.. pixi install

5. Configure environment variables as needed (example for Mojo): export MOJO_DB_PATH=/path/to/db export MAX_SERVER_URL=http://localhost:8000 export EMBED_MODEL_NAME=sentence-transformers/all-MiniLM-L6-v2 export AUTO_START_MAX=1

6. Start a server (example for mojo-manual-mcp): cd servers/mojo-manual-mcp pixi run serve # or use the runtime/python server command as per project guidance

7. Validate running servers by accessing their APIs or using the VS Code MCP integration as described in the README.

Note: The project provides pre-built databases in the repository so an initial build step may be optional for basic runs. Refer to the specific server’s README for exact run commands and paths.

Tips and common issues:

• If MAX embedding server is offline, the search may degrade to keyword-only results; ensure MAX is reachable or configure a fallback.
• Use the YAML-based configuration to avoid hard-coded paths; keep environment variable references for flexibility across environments.
• For multi-server setups, keep each server self-contained under servers/{name} to preserve distributability.
• When upgrading dependencies, prefer recreating virtual environments to avoid stale citations in embeddings and indexes.
• If you encounter port conflicts, adjust the MAX or DuckDB service ports via environment variables or server configuration files.
• Ensure consistent Python versions across development and deployment to avoid runtime mismatches, especially for DuckDB and embedding runtimes.
• When deploying to VS Code, ensure the cwd in your mcp.json points to the exact server directory to allow proper process management.