Zileo Docs

MCP (Model Context Protocol) server for indexing, semantic search, and generation of multi-format documents. Exposes 13 tools over JSON-RPC 2.0 so an LLM can search your local PDF, Excel, and Word files, and create or edit Excel and Word documents.

Developed by Assistance Micro Design

Built with Claude Code by Anthropic

Beta Warning

This project is in beta. Use at your own risk and review the trade-offs before relying on it.

Recommendation: Run behind a private network, set API_KEY, and pin the Docker image to a tagged version.

Related MCP server: MCP RAG

Description

Zileo Docs ingests heterogeneous office documents, extracts their content (native text or Mistral OCR), chunks the result while preserving Markdown structure, embeds each chunk with Mistral (1024-dim dense vectors plus BM25 sparse vectors), and stores them in Qdrant. An LLM connected over MCP can then search the indexed corpus, read full documents, and generate new Excel or Word files — all from natural-language tool calls.

Key Features

• 13 MCP tools over JSON-RPC 2.0 / HTTP (POST /mcp)

• Multi-format ingestion: PDF (native + OCR), Excel .xlsx/.xls, Word .docx

• Hybrid search (dense + BM25 RRF) with cosine relevance guard against off-domain results

• Semantic-only search with explicit score_threshold

• Excel and Word generation from structured input (data, formulas, styles, charts)

• Path traversal, formula-injection, and ZIP-bomb protections

• Per-endpoint rate limiting (slowapi) and API-key authentication

• Docker multi-stage image, non-root runtime, health-checked

Prerequisites

Build Requirements

Required only when developing outside Docker (the container ships everything else).

Installation

git clone https://github.com/assistance-micro-design/zileo-docs.git
cd zileo-docs
cp .env.example .env

# Edit .env: set MISTRAL_API_KEY and DOCUMENTS_PATH
# Generate an API key to protect the server:
echo "API_KEY=$(openssl rand -hex 32)" >> .env

docker compose up -d

About API_KEY — Protects /api/v1/*, /mcp, and /health. Outside DEBUG=true, the server refuses to start with an empty key. See docs/mcp-client-setup.md for passing it to MCP clients.

Verify the server is up:

curl -H "X-API-Key: $API_KEY" http://localhost:8000/health
# {"status": "healthy", ...}

Tech Stack

MCP Configuration

The MCP endpoint is POST /mcp (JSON-RPC 2.0 over HTTP).

Claude Desktop

Add to the Claude Desktop config:

{
  "mcpServers": {
    "zileo-docs": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "headers": {
        "X-API-Key": "your_api_key_here"
      }
    }
  }
}

Replace your_api_key_here with the API_KEY from .env. Restart Claude Desktop after editing.

Zileo Chat

In Zileo Chat, open Settings → MCP → Add server and fill in the form:

The API-key value is stored in your OS keychain — never written to the database in plain text, never exported. Only non-sensitive metadata (the header name) is persisted.

Set the endpoint URL according to where Zileo Chat runs relative to the server:

Then Save. See docs/mcp-client-setup.md for details.

Other MCP clients

Any MCP-compatible client can connect over HTTP Streamable to http://localhost:8000/mcp. The server implements:

• initialize — Handshake and capabilities

• tools/list — Lists the 13 available tools

• tools/call — Invokes a tool

Transport is HTTP POST with JSON-RPC 2.0 payloads. No SSE, no WebSocket.

MCP Tools

Indexing and search

Generation and editing

Utilities

Configuration

Main environment variables (see docs/configuration.md for the full list):

Local Development

uv sync --extra dev
docker compose up -d qdrant   # Qdrant only
uv run uvicorn src.main:app --reload

Tests

uv run pytest tests/unit/ -v          # Unit tests
uv run pytest tests/integration/ -v   # Requires Qdrant
uv run pytest tests/e2e/ -v           # Full pipeline

Validation

uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
uv run mypy src/
uv run pytest --cov=src --cov-fail-under=80

RAG evaluation

Offline evaluation of search quality against the golden set (tests/eval/golden_questions.yml). Requires the server running with indexed documents.

uv run python3 scripts/eval_rag.py --tool search_hybrid    # or search_semantic
# Metrics: recall@1, recall@5, MRR, false-positive rate (off-domain), mean results

Architecture

src/
  main.py              # FastAPI app + /mcp endpoint
  core/                # Config, exceptions, logging
  api/routes/          # REST endpoints (health, documents, search)
  mcp/
    server.py          # JSON-RPC 2.0 router
    tools/             # 13 MCP tools
  services/
    pdf/               # Analysis, native extraction, Mistral OCR
    excel/             # Extraction + generation + editing
    word/              # docx2python extraction
    inspection/        # Generated-file inspection
    document/          # Multi-format router
    chunking/          # Chunk splitting
    embedding/         # Mistral embeddings (1024 dim)
    vector/            # Qdrant storage
  models/              # Pydantic schemas

Documentation

• MCP client setup — Claude Desktop, Zileo Chat, other clients

• Research guide — Indexing, hybrid search, reading

• Generation guide — Excel and Word options, design, examples

• API reference — REST endpoints and 13 MCP tools

• Architecture — Processing pipeline and components

• Configuration — Environment variables

• Deployment — Docker and local development

• Multi-format support — PDF, Excel, Word

• Code style — Conventions

Contributing

See CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md.

Quick path:

1. Fork the repository

2. Create a feature branch (git checkout -b feat/your-feature)

3. Commit with a conventional message (git commit -m "feat(scope): summary")

4. Push and open a Pull Request against main

5. Ensure CI is green and the PR checklist is satisfied

Security

To report a vulnerability, see SECURITY.md. Do not open public issues for security reports.

License

Distributed under the GNU Affero General Public License v3.0 or later.

Copyright 2025-2026 Assistance Micro Design
Licensed under the GNU Affero General Public License v3.0 or later

This license is mandatory because the project depends on PyMuPDF and pymupdf4llm (Artifex Software, Inc.), both distributed under AGPL-3.0. See THIRD_PARTY_LICENSES.md for the complete inventory and NOTICE for attribution.

Acknowledgments

• Mistral AI — Embeddings and OCR

• Qdrant — Vector database

• PyMuPDF and pymupdf4llm — PDF extraction

• FastAPI — Web framework

• Model Context Protocol — Tool protocol

• Built with Claude Code by Anthropic

Assistance Micro Design | GitHub