oorep-mcp

# OOREP MCP Server

[![npm version](https://img.shields.io/npm/v/oorep-mcp.svg)](https://www.npmjs.com/package/oorep-mcp)
[![CI](https://github.com/Dhi13man/oorep-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Dhi13man/oorep-mcp/actions/workflows/ci.yml)
[![CodeQL](https://github.com/Dhi13man/oorep-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/Dhi13man/oorep-mcp/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Dhi13man/oorep-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/Dhi13man/oorep-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP server and TypeScript client SDK that gives AI assistants access to
OOREP's homeopathic repertory and materia medica reference data.

## TL;DR

```bash
# Install and run (no setup required)
npx -y oorep-mcp
```

```typescript
// Or use programmatically
import { createOOREPClient } from 'oorep-mcp';

const client = createOOREPClient();
const results = await client.searchRepertory({ symptom: 'headache worse motion' });
console.log(results.rubrics);
client.destroy();
```

**Ask your AI assistant:** *"Search OOREP for remedies for throbbing headache worse from light"*

## What is OOREP?

**OOREP (Open Online Repertory)** is an open-source homeopathic database containing:

- **12+ Repertories** - Systematic indexes of symptoms mapped to remedies (Kent, Boger, Boericke, etc.)
- **Multiple Materia Medicas** - Detailed remedy descriptions and therapeutic indications
- **600+ Remedies** - Comprehensive remedy database with names, abbreviations, and alternates

### How Homeopathic Data is Structured

```mermaid
graph TB
    subgraph Repertory[Repertory Structure]
        Chapter[Chapter<br/>e.g. Head]
        Rubric[Rubric<br/>e.g. Pain - Throbbing]
        R1[Belladonna - 4]
        R2[Glonoine - 3]
        R3[Natrum mur - 2]
        Chapter --> Rubric
        Rubric --> R1
        Rubric --> R2
        Rubric --> R3
    end

    subgraph MateriaMedica[Materia Medica Structure]
        Remedy[Remedy<br/>e.g. Belladonna]
        S1[Mind: Sudden onset...]
        S2[Head: Throbbing pain...]
        S3[...]
        Remedy --> S1
        Remedy --> S2
        Remedy --> S3
    end
```

This MCP server enables AI assistants to query this data programmatically.

## Features

| Feature | Description |
|---------|-------------|
| **Search Repertories** | Query symptoms across 12+ repertories, get matching rubrics with weighted remedies |
| **Search Materia Medicas** | Find remedy descriptions and indications from multiple sources |
| **Remedy Information** | Get comprehensive details for 600+ remedies |
| **List Resources** | Browse available repertories, materia medicas, and remedies |
| **Guided Workflows** | Prompts for symptom analysis, remedy comparison, case repertorization |
| **Structured Responses** | MCP 2025-06-18 compliant with outputSchema and structuredContent |
| **Performance** | Built-in caching (5min TTL), request deduplication, automatic retries |
| **Type Safety** | Full TypeScript with Zod validation on all inputs |
| **Security** | Input sanitization, error message sanitization, no credentials required |
| **SDK Adapters** | Direct integration with OpenAI, Vercel AI SDK, LangChain, Google Gemini |

## Quick Start

Requires [Node.js 20 or newer](https://nodejs.org/) with npm/npx.

### 1. Add to Claude Desktop

**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"]
    }
  }
}
```

### 2. Restart Claude Desktop

Quit completely (Cmd+Q / Alt+F4), then reopen.

### 3. Start Using

**You:** "Search OOREP for remedies for headache worse at night"

**Claude will:**

1. Call `search_repertory` with symptom "headache worse night"
2. Return matching rubrics with remedies and their weights
3. Explain the results in context

## Installation

### NPX (Recommended)

No installation required:

```bash
npx -y oorep-mcp
```

### npm Global

```bash
npm install -g oorep-mcp
oorep-mcp
```

### npm Local (for SDK usage)

```bash
npm install oorep-mcp
```

## Platform Configuration

### Claude Code

#### Option A: CLI

```bash
claude mcp add oorep -- npx -y oorep-mcp
```

#### Option B: Config file (`~/.claude.json`)

```json
{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

Verify: Run `/mcp` in Claude Code

### Claude Desktop

**Config locations:**

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

**Important:** Quit completely (Cmd+Q), not just close window.

### Codex CLI

**Config:** `~/.codex/config.toml` (macOS/Linux) or `C:\Users\<Username>\.codex\config.toml` (Windows)

```toml
[mcp_servers.oorep]
command = "npx"
args = ["-y", "oorep-mcp"]
startup_timeout_sec = 15.0
tool_timeout_sec = 60.0

[mcp_servers.oorep.env]
OOREP_MCP_BASE_URL = "https://www.oorep.com"
OOREP_MCP_LOG_LEVEL = "info"
```

Or via CLI:

```bash
codex mcp add oorep --env OOREP_MCP_BASE_URL=https://www.oorep.com --env OOREP_MCP_LOG_LEVEL=info -- npx -y oorep-mcp
```

Verify: Run `codex mcp list`

### Gemini CLI

**Config:** `~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "oorep": {
      "command": "npx",
      "args": ["-y", "oorep-mcp"],
      "env": {
        "OOREP_MCP_BASE_URL": "https://www.oorep.com",
        "OOREP_MCP_LOG_LEVEL": "info"
      },
      "timeout": 30000
    }
  }
}
```

## Usage Examples

Once installed, you can interact with OOREP through Claude naturally:

### Searching for Remedies

**You:** "Can you search OOREP for remedies for headache that's worse at night?"

**Claude will:**

1. Use the `search_repertory` tool
2. Search for "headache worse night" in the default repertory
3. Return matching rubrics with remedy recommendations and their weights

### Getting Detailed Remedy Information

**You:** "Tell me more about Aconite - what conditions is it used for?"

**Claude will:**

1. Use the `get_remedy_info` tool to fetch details about Aconite
2. Provide information about its common uses, characteristics, and therapeutic applications

### Comparing Remedies

**You:** "Compare Aconite and Belladonna for fever symptoms"

**Claude will:**

1. Use the `remedy-comparison` prompt
2. Search materia medicas for both remedies
3. Provide a side-by-side comparison focusing on fever symptoms
4. Highlight key differentiating factors

### Case Repertorization

**You:** "I want to repertorize a case with these symptoms: anxiety, palpitations, and insomnia"

**Claude will:**

1. Use the `repertorization-workflow` prompt
2. Guide you through systematic symptom analysis
3. Search relevant rubrics for each symptom
4. Help synthesize results to identify well-indicated remedies

### Browsing Available Resources

**You:** "What repertories are available in OOREP?"

**Claude will:**

1. Use the `list_available_repertories` tool
2. Show all 12+ available repertories with their names and descriptions

## API Reference

### Tools

#### `search_repertory`

Search for symptoms in homeopathic repertories.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `symptom` | string | Yes | - | Symptom to search (3-200 chars). Supports wildcards. |
| `repertory` | string | No | `publicum` | Repertory abbreviation (e.g., `kent`, `boger`) |
| `minWeight` | number | No | `1` | Minimum remedy weight (1-4) |
| `maxResults` | number | No | `20` | Maximum rubrics to return (1-100) |
| `includeRemedyStats` | boolean | No | `true` | Include aggregated remedy statistics |

**Returns:**

```typescript
{
  totalResults: number;
  rubrics: Array<{
    rubric: string;           // Full path: "Head > Pain > Throbbing"
    text: string | null;      // Additional rubric text
    repertory: string;        // Repertory abbreviation
    remedies: Array<{
      name: string;           // Full name: "Belladonna"
      abbreviation: string;   // "Bell."
      weight: number;         // 1-4
    }>;
  }>;
  remedyStats?: Array<{       // If includeRemedyStats=true
    name: string;
    abbreviation: string;
    count: number;            // Times appearing
    cumulativeWeight: number; // Sum of weights
  }>;
}
```

#### `search_materia_medica`

Search materia medica texts for remedy descriptions.

**Parameters:**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `symptom` | string | Yes | - | Symptom to search (3-200 chars) |
| `materiamedica` | string | No | `boericke` | Materia medica abbreviation |
| `remedy` | string | No | - | Filter to specific remedy |
| `maxResults` | number | No | `10` | Maximum results (1-50) |

**Returns:**

```typescript
{
  totalResults: number;
  results: Array<{
    remedy: string;           // "Aconitum napellus"
    materiaMedica: string;    // "boericke"
    sections: Array<{
      heading: string;        // "Mind", "Head", etc.
      content: string;        // Section text
      depth: number;          // Heading depth
    }>;
  }>;
}
```

#### `get_remedy_info`

Get detailed information about a specific remedy.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `remedy` | string | Yes | Remedy name, abbreviation, or alternate name (1-100 chars) |

**Returns:**

```typescript
{
  id: number;
  nameAbbrev