# semarcy-mcp

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

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/)
- A [Voyage AI](https://www.voyageai.com/) API key (free tier covers this project's needs)

## Quick Start (Docker)

### 1. Clone the repo

```bash
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.

```bash
docker build -t semarcy-mcp .
```

### 3. Set up your API key

```bash
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):

```json
{
  "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:

```bash
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:

```json
{
  "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)

```bash
# 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) |