semarcy-mcp

semarcy-mcp

MCP server that provides AI assistants with RAG-powered access to Semarchy documentation (xDM, xDI, xDG). Connect it to Claude Desktop or any MCP-compatible client to search and retrieve relevant Semarchy docs.

Prerequisites

• Docker
• A Voyage AI API key (free tier covers this project's needs)

Quick Start (Docker)

1. Clone the repo

git clone <repo-url> && cd semarcy-mcp

2. Build the Docker image

The image includes pre-ingested documentation, so it's ready to use immediately.

docker build -t semarcy-mcp .

3. Set up your API key

cp .env.example .env

Edit .env and replace the placeholder with your actual Voyage AI key. This file is used by Docker (--env-file) and by local development (loaded automatically via python-dotenv).

4. Configure Claude Desktop

Add the server to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "semarcy-docs": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/semarcy-mcp/.env",
        "semarcy-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/semarcy-mcp/.env with the actual path to your .env file.

5. Restart Claude Desktop

You can now ask Claude questions about Semarchy xDM, xDI, and xDG.

Updating the Documentation Index

The Docker image includes pre-ingested documentation, so most users never need to re-ingest. If Semarchy updates their docs and you want the latest content:

docker run --rm --env-file .env -v semarcy-data:/data/chroma semarcy-mcp \
  ingest --db-path /data/chroma --clear

Then update your Claude Desktop config to mount the same volume:

{
  "mcpServers": {
    "semarcy-docs": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/absolute/path/to/semarcy-mcp/.env",
        "-v", "semarcy-data:/data/chroma",
        "semarcy-mcp"
      ]
    }
  }
}

Local Development (without Docker)

# Install dependencies
uv sync

# Set up your API key (python-dotenv loads this automatically)
cp .env.example .env
# Edit .env with your actual key

# Ingest docs (takes a while on first run)
uv run semarcy-mcp ingest

# Run the MCP server
uv run semarcy-mcp serve

# Test with MCP Inspector
mcp dev src/semarcy_mcp/server.py

Available MCP Tools

| Tool | Description | |------|-------------| | search_semarchy_docs | Search Semarchy documentation with a natural language query. Returns relevant chunks with source URLs. | | list_semarchy_topics | List available topic areas across Semarchy products. Useful for discovering what documentation is indexed. |

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | VOYAGE_API_KEY | Yes | Voyage AI API key for embedding search queries | | SEMARCY_DB_PATH | No | Override ChromaDB storage path (default: ./chroma_data locally, /data/chroma in Docker) |