# Omarchy MCP Server

A Model Context Protocol (MCP) server providing semantic search over Omarchy, Arch Linux, and Hyprland documentation.

## Version Information

- **Omarchy:** v4.0.0 (pinned)
- **Omarchy Releases:** All versions up to v4.0.0
- **Arch Wiki:** Latest (updated via script)
- **Hyprland Wiki:** Latest (updated via script)

**Note:** This server contains Omarchy v4.0.0 documentation. Some features may differ if you are on a different version.

## Prerequisites

- **Arch-based Linux system** (uses pacman for arch-wiki-docs)
- Docker and Docker Compose
- Git
- 10 GB free disk space
- Internet connection for initial setup

## Quick Start

### 1. Clone the Repository

```
git clone https://github.com/Zeus-Deus/omarchy-mcp.git
cd omarchy-mcp
```

### 2. Run Setup

```
chmod +x scripts/setup.sh
./scripts/setup.sh
```

**This will take approximately 3-4 minutes and will:**

- Restore Omarchy v4.0.0 docs from snapshot
- Download latest Arch Wiki and Hyprland documentation
- Build and start Docker containers
- Process and ingest all documentation into vector database
- Create 8,500+ searchable documentation chunks

## Upgrading Omarchy Version

To upgrade to a new Omarchy version:

```bash
./scripts/upgrade.sh 3.4.2
docker-compose restart mcp-server
```

That's it - the script handles everything (download docs, process, ingest, create snapshot).

### 3. Configure Cursor IDE

Create or edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "omarchy-kb": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "omarchy-mcp-server",
        "python",
        "/app/mcp_server/main.py"
      ]
    }
  }
}
```

**Important:** Restart Cursor completely after adding the configuration.

### 4. Configure OpenCode

Create or edit `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false,
  "mcp": {
    "omarchy-kb": {
      "type": "local",
      "command": [
        "docker",
        "exec",
        "-i",
        "omarchy-mcp-server",
        "python",
        "/app/mcp_server/main.py"
      ]
    }
  }
}
```

### 5. Configure Claude Code

Run the following command in your terminal:

```bash
claude mcp add --scope user omarchy-kb -- docker exec -i omarchy-mcp-server python /app/mcp_server/main.py
```

Restart Claude Code after adding the configuration. Verify the server is connected:

```bash
claude mcp list
```

### 6. Use in Cursor / OpenCode / Claude Code

1. Open your IDE (Cursor, OpenCode, or Claude Code)
2. Switch to **Agent mode** (click "Ask" dropdown in bottom-left, select "Agent")
3. In the chat, type queries like:

```
Use omarchy-kb to search for waybar configuration
```

Or:

```
How do I configure Hyprland keybindings in Omarchy?
```

Or:

```
Use omarchy-kb to tell me what's new in Omarchy version 3.2.0
```

## Available Tools

The MCP server provides these tools:

- **search_documentation** - Semantic search across all documentation
- **find_config_location** - Find configuration file paths for applications
- **compare_omarchy_vs_arch** - Compare Omarchy vs vanilla Arch/Hyprland implementations
- **get_server_info** - View server statistics and capabilities

## Documentation Sources

The knowledge base includes:

| Source           | Priority    | Description                                           |
| ---------------- | ----------- | ----------------------------------------------------- |
| Omarchy          | 1 (highest) | Omarchy-specific documentation and customizations     |
| Omarchy Releases | 1 (highest) | GitHub release notes with changelogs and new features |
| Hyprland         | 2           | Hyprland window manager documentation                 |
| Arch Wiki        | 3           | Base Arch Linux documentation                         |

**Priority System:** When conflicts occur, Omarchy documentation takes precedence over Hyprland and Arch.

## Updating Documentation

**Note:** Omarchy documentation and release notes remain at v4.0.0 (pinned version). To update Arch Wiki and Hyprland documentation, re-run the setup script or manually execute the download and processing scripts.

## Manual Operations

### Stop the Server

```
docker-compose down
```

### Start the Server

```
docker-compose up -d
```

### View Logs

```
docker logs -f omarchy-mcp-server
```

### Rebuild After Code Changes

```
docker-compose down
docker-compose build
docker-compose up -d
```

## Project Structure

```
omarchy-mcp/
├── data/
│   ├── snapshots/
│   │   └── omarchy-4.0.0-processed/ # Version snapshot (in Git)
│   ├── raw/ # Downloaded HTML (ignored)
│   └── processed/ # Cleaned JSON (ignored)
├── scripts/
│   ├── setup.sh # Initial setup script
│   ├── 1_download_archwiki.sh # Download Arch Wiki
│   ├── 2_download_hyprland.sh # Download Hyprland wiki
│   ├── 3_download_omarchy.sh # Download Omarchy manual
│   ├── 4_clean_archwiki.py # Clean Arch HTML to JSON
│   ├── 5_clean_hyprland.py # Clean Hyprland MD to JSON
│   ├── 6_clean_omarchy.py # Clean Omarchy HTML to JSON
│   ├── 7_ingest_to_chroma.py # Ingest to vector database
│   ├── 8_download_omarchy_releases.py # Download Omarchy releases (NEW!)
│   └── 9_clean_omarchy_releases.py # Clean releases to JSON (NEW!)
├── mcp_server/
│   └── main.py # MCP server implementation
├── docker-compose.yml # Docker services definition
├── Dockerfile # Container build instructions
├── requirements.txt # Python dependencies
└── README.md
```

## Troubleshooting

### Server Not Connecting in Cursor

- Ensure Docker containers are running: `docker ps`
- Check server logs: `docker logs omarchy-mcp-server`
- Verify you are in **Agent mode** in Cursor (not "Ask" mode)
- Restart Cursor completely after updating config

### No Results from Queries

- Verify vector database is populated:

```
docker exec omarchy-mcp-server python -c "
import chromadb
client = chromadb.HttpClient(host='chromadb', port=8000)
collection = client.get_collection('omarchy_docs')
print(f'Documents: {collection.count()}')
"
```

- Should show approximately 8,500+ documents

### Setup Script Fails

- Ensure Docker daemon is running: `systemctl status docker`
- Check available disk space: `df -h`
- Verify internet connection
- Try running steps manually from `scripts/setup.sh`

## Technical Details

- **Vector Database:** ChromaDB
- **Embedding Model:** all-MiniLM-L6-v2 (sentence-transformers)
- **Chunk Size:** 400 words per document chunk
- **Search Method:** Cosine similarity on embeddings
- **Protocol:** Model Context Protocol (MCP) via stdio

## Contributing

Issues and pull requests welcome at https://github.com/Zeus-Deus/omarchy-mcp

## License

GNU General Public License v3.0 (GPL-3.0)

See [LICENSE](LICENSE) for full license text.