Hardware Manual RAG MCP Server

A Model Context Protocol (MCP) server that provides Local RAG (Retrieval-Augmented Generation) over hardware manuals (PDF & HTML). It indexes your manuals into ChromaDB using local embeddings and exposes a query_hardware_manual tool so Claude Code can look up pinouts, registers, schematics, and other hardware specifications — all running locally inside a Docker container.

How It Works

Your PDF/HTML Manuals  →  Docker Container  →  ChromaDB (vectors)  →  Claude Code via MCP

• Files are parsed and chunked into 800-character overlapping segments
• Each chunk is embedded with all-MiniLM-L6-v2 (local, no API key needed)
• Incremental indexing: only new or changed files are re-indexed on restart
• Vectors persist on a Docker named volume so 20+ MB of manuals aren't re-indexed every time

---

Prerequisites

• Docker & Docker Compose installed
• Claude Code (or any MCP-compatible client)
• At least ~2 GB free disk space (for Docker image + embedding model + vector store)

---

Option 1: Pull from GitHub Container Registry (GHCR)

The Docker image is published to GHCR. You don't need to clone the repo.

# Pull the latest image
docker pull ghcr.io/YOUR_ORG/hum_mcp:latest

Then use the docker-compose override below to use the prebuilt image.

docker-compose.prod.yml

Create a docker-compose.prod.yml file:

services:
  hardware-mcp:
    image: ghcr.io/YOUR_ORG/hum_mcp:latest
    pull_policy: always
    container_name: hardware-mcp
    restart: unless-stopped
    init: true
    volumes:
      - ./manuals_repo:/app/manuals:ro
      - chroma_data:/app/chroma_db
    environment:
      - PYTHONUNBUFFERED=1

volumes:
  chroma_data:

Replace YOUR_ORG with your GitHub username or organization name.

Start it:

docker compose -f docker-compose.prod.yml up -d

---

Option 2: Build from Source

Clone and build locally:

git clone https://github.com/YOUR_ORG/hum_mcp.git
cd hum_mcp

# Build and start the container
docker compose up -d --build

---

Setup

1. Place Your Hardware Manuals

Copy your PDF or HTML hardware manuals into the manuals_repo/ directory:

# Linux / macOS
cp ~/Downloads/stm32f4-datasheet.pdf ./manuals_repo/
cp ~/Downloads/esp32-technical-reference.html ./manuals_repo/

# Windows (PowerShell)
Copy-Item ~\Downloads\stm32f4-datasheet.pdf .\manuals_repo\

Supported formats: .pdf, .html, .htm

2. Start the Container

docker compose up -d

On first start, the container will:

1. Download the embedding model (~80 MB, all-MiniLM-L6-v2) — one time only
2. Index all manuals in manuals_repo/ into ChromaDB
3. Log progress to Docker logs

3. Verify It's Running

# Check container status
docker ps --filter name=hardware-mcp

# View indexing logs
docker logs hardware-mcp

Look for a line like:

Indexing complete: 2 file(s) indexed, 0 skipped, 45 total chunks in collection
Server ready — 45 total chunks available

---

Runtime Usage

Connect Claude Code

Add this to your MCP configuration file:

macOS / Linux: ~/.config/claude/config.json
Windows: %APPDATA%\Claude\config.json

{
  "mcpServers": {
    "hardware-manual-server": {
      "command": "docker",
      "args": ["exec", "-i", "hardware-mcp", "python", "-m", "mcp", "run", "src/server.py"]
    }
  }
}

Restart Claude Code after saving. You should see a tools icon appear indicating the MCP server is connected.

Query Your Manuals

Once connected, Claude Code can answer hardware questions by calling query_hardware_manual. Simply ask questions like:

• "What is the pinout for the STM32F407 SPI1 interface?"
• "What are the electrical characteristics of GPIO pins at 3.3V?"
• "Show me the register map for the UART control registers"
• "What is the maximum clock frequency for the ESP32-S3?"

The tool returns the top 5 most relevant chunks with source filenames and relevance scores.

Adding or Updating Manuals

1. Add/update files in manuals_repo/
2. Restart the container:

docker compose restart

Only new or changed files are re-indexed — existing chunks are preserved.

Removing Manuals

1. Delete the file from manuals_repo/
2. Restart the container — orphaned chunks are automatically cleaned up:

docker compose restart

---

Useful Commands

Command	Description
docker compose up -d	Start the container (detached)
docker compose down	Stop and remove the container (vector data persists)
docker compose restart	Restart to pick up new/changed manuals
docker compose down -v	Destroy everything including the vector database
docker logs hardware-mcp	View server logs
docker logs hardware-mcp -f	Follow logs in real time
docker exec -it hardware-mcp ls /app/manuals	List indexed manuals inside the container
docker compose build --no-cache	Rebuild the image from scratch

---

Project Structure

hum_mcp/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── manuals_repo/          # ← Put your PDF/HTML manuals here
│   └── README.txt
├── src/
│   ├── __init__.py
│   └── server.py          # Main application
└── .github/
    └── workflows/
        └── docker-build.yml

---

Troubleshooting

"No hardware manuals have been indexed yet"

Place at least one .pdf or .html file in manuals_repo/ and run docker compose restart.

"Error querying hardware manuals: …"

Check the logs for details: docker logs hardware-mcp

Container keeps restarting

This typically means the embedding model failed to download. Check your internet connection and retry:

docker compose down -v
docker compose up -d

Scanned PDFs (image-only) don't produce results

pypdf cannot extract text from scanned/image-based PDFs. Use OCR software to create text-searchable PDFs first, or convert them to HTML.

Slow first startup

The embedding model (~80 MB) is downloaded on first run. Subsequent starts are fast.