关于 oorep-mcp
oorep-mcp 为 AI 助手提供 OOREP 顺势疗法 repertory 和 materia medica 参考数据的查询接口,也提供 TypeScript SDK。可搜索症状、浏览药物信息,并通过提示词引导症状分析、药物比较和病例 repertorization。
主要功能
- 01跨多个 repertory 搜索症状
- 02搜索 materia medica 文本
- 03查询药物详细信息
- 04浏览 repertory、文本和药物资源
- 05提供症状分析与药物比较工作流
- 06支持结构化 MCP 响应
适用场景
- 01按症状查找 rubrics 和对应药物
- 02检索特定药物的描述与适应指征
- 03并排比较多个药物
- 04按步骤整理病例并进行 repertorization
MCP 相关
该 MCP 服务向客户端提供 repertory 与 materia medica 搜索、药物信息和资源列表工具,并提供引导工作流的提示词。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
5收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| symptom | string | 是 | 症状搜索词(3–200 个字符)。支持通配符(*)、排除项(-term)和精确短语("phrase")。示例:"headache"、"head*"、"fever -night"、'"worse from cold"' |
| minWeight | number | 否 | 可选:要包含的最低药剂权重/等级(1–4)。权重越高表示关联越强。1=轻微,2=中等,3=强,4=非常强 |
| repertory | string | 否 | 可选:按特定的索引缩写筛选。使用 list_available_repertories 查看可用选项。如果未指定,则使用已配置的默认索引(OOREP_MCP_DEFAULT_REPERTORY)。 |
| maxResults | number | 否 | 可选:返回结果的最大数量(1–500)。省略时默认为 OOREP_MCP_MAX_RESULTS(100)。 |
| includeRemedyStats | boolean | 否 | 可选:包含药剂汇总统计,显示出现频率最高的药剂。默认值:true |
详细介绍
OOREP MCP 服务
一个 MCP 服务和 TypeScript 客户端 SDK,让 AI 助手能够访问 OOREP 的顺势疗法 repertory 和 materia medica 参考数据。
TL;DR
# Install and run (no setup required)
npx -y oorep-mcp
// 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();
向你的 AI 助手提问: “在 OOREP 中搜索因光线而加重的搏动性头痛对应的疗法”
什么是 OOREP?
OOREP(Open Online Repertory) 是一个开源顺势疗法数据库,包含:
- 12+ 个 Repertory - 将症状映射到疗法的系统索引(Kent、Boger、Boericke 等)
- 多部 Materia Medica - 详细的疗法描述和治疗适应症
- 600+ 种疗法 - 全面的疗法数据库,包含名称、缩写和别名
顺势疗法数据的结构
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
此 MCP 服务支持 AI 助手以编程方式查询这些数据。
功能
| 功能 | 描述 |
|---|---|
| 搜索 Repertory | 在 12+ 个 repertory 中查询症状,获取包含加权疗法的匹配 rubrics |
| 搜索 Materia Medica | 从多个来源查找疗法描述和适应症 |
| 疗法信息 | 获取 600+ 种疗法的详细信息 |
| 列出资源 | 浏览可用的 repertory、materia medica 和疗法 |
| 引导式工作流 | 提供症状分析、疗法比较和病例 repertorization 的提示词 |
| 结构化响应 | 符合 MCP 2025-06-18 规范,支持 outputSchema 和 structuredContent |
| 性能 | 内置缓存(TTL 为 5 分钟)、请求去重和自动重试 |
| 类型安全 | 全面的 TypeScript 支持,所有输入均通过 Zod 验证 |
| 安全性 | 输入清理、错误消息清理,无需凭据 |
| SDK 适配器 | 可直接集成 OpenAI、Vercel AI SDK、LangChain、Google Gemini |
快速开始
需要安装 Node.js 22.12 或更高版本,并使用 npm/npx。
1. 添加到 Claude Desktop
macOS: 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: 编辑 %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"oorep": {
"command": "npx",
"args": ["-y", "oorep-mcp"]
}
}
}
2. 重启 Claude Desktop
完全退出(Cmd+Q / Alt+F4),然后重新打开。
3. 开始使用
你:“在 OOREP 中搜索夜间加重的头痛对应的疗法”
Claude 将会:
- 使用症状“夜间加重的头痛”调用
search_repertory - 返回匹配的 rubrics,以及疗法及其权重
- 结合上下文解释结果
安装
NPX(推荐)
无需安装:
npx -y oorep-mcp
npm 全局安装
npm install -g oorep-mcp
oorep-mcp
npm 本地安装(用于 SDK)
npm install oorep-mcp
平台配置
Claude Code
选项 A:CLI
claude mcp add oorep -- npx -y oorep-mcp
选项 B:配置文件(~/.claude.json)
{
"mcpServers": {
"oorep": {
"command": "npx",
"args": ["-y", "oorep-mcp"],
"env": {
"OOREP_MCP_BASE_URL": "https://www.oorep.com",
"OOREP_MCP_LOG_LEVEL": "info"
}
}
}
}
验证:在 Claude Code 中运行 /mcp
Claude Desktop
配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"oorep": {
"command": "npx",
"args": ["-y", "oorep-mcp"],
"env": {
"OOREP_MCP_BASE_URL": "https://www.oorep.com",
"OOREP_MCP_LOG_LEVEL": "info"
}
}
}
}
重要提示: 请完全退出(Cmd+Q),不要只关闭窗口。
Codex CLI
配置文件: ~/.codex/config.toml(macOS/Linux)或 C:\Users\<Username>\.codex\config.toml(Windows)
[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"
也可以通过 CLI 配置:
codex mcp add oorep --env OOREP_MCP_BASE_URL=https://www.oorep.com --env OOREP_MCP_LOG_LEVEL=info -- npx -y oorep-mcp
验证:运行 codex mcp list
Gemini CLI
配置文件: ~/.gemini/settings.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
}
}
}
使用示例
安装后,你可以直接通过 Claude 自然地与 OOREP 交互:
搜索治疗药剂
你:“你能在 OOREP 中搜索夜间加重的头痛对应的治疗药剂吗?”
Claude 将:
- 使用
search_repertory工具 - 在默认的医学目录中搜索“夜间加重的头痛”
- 返回匹配的条目,以及推荐的治疗药剂和对应权重
获取治疗药剂的详细信息
你:“告诉我更多关于 Aconite 的信息——它用于治疗哪些病症?”
Claude 将:
- 使用
get_remedy_info工具获取 Aconite 的详细信息 - 提供其常见用途、特征和治疗应用方面的信息
比较治疗药剂
你:“比较 Aconite 和 Belladonna 对发热症状的适用情况”
Claude 将:
- 使用
remedy-comparison提示词 - 搜索这两种治疗药剂的药物学资料
- 提供并排比较,重点关注发热症状
- 突出关键区别
病例医学目录分析
你:“我想对一个病例进行医学目录分析,症状包括:焦虑、心悸和失眠”
Claude 将:
- 使用
repertorization-workflow提示词 - 引导你系统地分析症状
- 搜索每种症状对应的相关条目
- 帮助综合分析结果,找出适应证明确的治疗药剂
浏览可用资源
你:“OOREP 中有哪些可用的医学目录?”
Claude 将:
- 使用
list_available_repertories工具 - 显示全部 12 个以上可用的医学目录及其名称和描述
API 参考
工具
search_repertory
在顺势疗法医学目录中搜索症状。
参数:
| 名称 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
symptom | string | 是 | - | 要搜索的症状(3-200 个字符)。支持通配符。 |
repertory | string | 否 | publicum | 医学目录缩写(例如,kent、boger) |
minWeight | number | 否 | 1 | 治疗药剂的最低权重(1-4) |
maxResults | number | 否 | 20 | 最多返回的条目数(1-100) |
includeRemedyStats | boolean | 否 | true | 包含汇总的治疗药剂统计信息 |
返回:
{
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
在药物学资料文本中搜索治疗药剂描述。
参数:
| 名称 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
symptom | string | 是 | - | 要搜索的症状(3-200 个字符) |
materiamedica | string | 否 | boericke | 药物学资料缩写 |
remedy | string | 否 | - | 筛选指定的治疗药剂 |
maxResults | number | 否 | 10 | 最多返回的结果数(1-50) |
返回:
{
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
获取特定治疗药剂的详细信息。
参数:
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
remedy | string | 是 | 治疗药剂名称、缩写或别名(1-100 个字符) |
返回:
{
id: number;
nameAbbrev: string; // "Acon."
nameLong: string; // "Aconitum napellus"
namealt: string[]; // ["Aconite", "Monkshood"]
} | null // null if not found
匹配行为:
- 对缩写、全名或别名进行精确匹配(不区分大小写)
- 查询长度 ≥3 个字符时进行部分匹配
list_available_repertories
列出所有可访问的医学目录。
参数:
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
language | string | 否 | 按语言代码筛选(例如,en、de) |
返回:
Array<{
abbreviation: string; // "kent"
title: string; // "Kent Repertory"
author: string; // "James Tyler Kent"
language: string; // "en"
}>
list_available_materia_medicas
列出所有可访问的药物学资料文本。
参数:
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
language | string | 否 | 按语言代码筛选 |
返回:
Array<{
abbreviation: string; // "boericke"
title: string; // "Boericke Materia Medica"
author: string; // "William Boericke"
language: string; // "en"
}>
结构化响应格式
所有工具均支持 MCP 2025-06-18 规范中的结构化响应:
响应结构:
{
// Text content for backwards compatibility
content: [{
type: 'text',
text: '{"totalResults": 42, "rubrics": [...]}' // JSON string
}],
// Machine-parseable structured content
structuredContent: {
totalResults: 42,
rubrics: [...] // Actual JavaScript object
}
}
优势:
- outputSchema:每个工具定义都包含一个 JSON Schema,用于定义预期的输出结构
- structuredContent:无需解析 JSON,即可直接访问类型化结果
- 向后兼容:始终包含文本内容,以兼容旧版客户端
- 错误处理:发生错误时会返回
isError: true,供大模型自行纠正
资源
| URI | 描述 | 内容类型 |
|---|---|---|
oorep://remedies/list | 所有 600 多种药物的完整列表 | JSON |
oorep://repertories/list | 所有可用的索引及其元数据 | JSON |
oorep://materia-medicas/list | 所有可用的药物学资料 | JSON |
oorep://help/search-syntax | 搜索语法指南及示例 | 文本 |
提示词
analyze-symptoms
用于系统分析症状的引导式工作流。
参数:
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
symptom_description | string | 否 | 初始症状描述 |
工作流: 引导用户收集症状 → 分析症状诱因和缓解因素 → 搜索索引 → 综合分析
remedy-comparison
并排比较多种药物。
参数:
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
remedies | string | 是 | 以逗号分隔的药物名称(2-6 种) |
示例: remedies: "Aconite, Belladonna, Gelsemium"
repertorization-workflow
逐步进行病例采集和索引分析。
工作流: 从症状收集到药物鉴别,共分 7 个步骤。
搜索语法
基本搜索
headache # Simple term
headache night # Multiple terms (AND)
通配符
head* # Matches: head, headache, heading
*ache # Matches: headache, stomachache
精确短语
"worse at night" # Exact phrase match
"throbbing pain" # Must appear together
排除项
headache -migraine # Headache but not migraine
fever -intermittent # Fever excluding intermittent
组合搜索
head* pain -chronic "worse motion"
提示
- 每个词至少 3 个字符
- 通配符只能用于词边界
- 使用特定索引中的术语可获得更好的结果
SDK 集成
如需通过 AI 框架以编程方式使用,请参阅 SDK 集成指南。
支持的框架: OpenAI、Vercel AI SDK、LangChain/LangGraph、Google Gemini
快速示例:
import { createOOREPClient } from 'oorep-mcp';
const client = createOOREPClient();
const results = await client.searchRepertory({ symptom: 'headache worse motion' });
console.log(results.rubrics);
client.destroy();
配置
所有配置均通过环境变量设置:
| 变量 | 默认值 | 描述 |
|---|---|---|
OOREP_MCP_BASE_URL | https://www.oorep.com | OOREP API 基础 URL |
OOREP_MCP_TIMEOUT_MS | 30000 | 请求超时时间(毫秒) |
OOREP_MCP_CACHE_TTL_MS | 300000 | 缓存 TTL(毫秒),设为 0 可禁用 |
OOREP_MCP_MAX_RESULTS | 100 | 结果数量上限 |
OOREP_MCP_LOG_LEVEL | info | debug | info | warn | error |
OOREP_MCP_DEFAULT_REPERTORY | publicum | 默认索引 |
OOREP_MCP_DEFAULT_MATERIA_MEDICA | boericke | 默认药物学资料 |
OOREP_MCP_REMOTE_USER | (unset) | 如果已设置,则在所有上游请求中发送 X-Remote-User 标头(数字形式的成员 ID) |
MCP 服务会自动维护匿名 OOREP 会话。它会执行一次轻量级引导请求,以获取所需的 Cookie,并在后续搜索请求中重复使用,因此访问公共数据无需额外设置身份验证。
自定义配置示例:
{
"mcpServers": {
"oorep": {
"command": "npx",
"args": ["-y", "oorep-mcp"],
"env": {
"OOREP_MCP_TIMEOUT_MS": "60000",
"OOREP_MCP_CACHE_TTL_MS": "600000",
"OOREP_MCP_LOG_LEVEL": "debug"
}
}
}
}
架构
graph TB
subgraph Client[MCP Client]
MCPClient((Claude, Codex,<br/>Gemini, etc.))
end
subgraph Server[OOREP MCP Server]
Tools[Tools]
Resources[Resources]
Prompts[Prompts]
SDK[SDK]
subgraph SDKClient[OOREPClient]
Cache[(Cache)]
Dedup[Deduplicator]
Validators[Validators]
end
subgraph HTTPClient[OOREPClient - HTTP]
Session[Session mgmt]
Retry[Retry logic]
Timeout[Timeout handling]
end
Tools --> SDKClient
Resources --> SDKClient
Prompts --> SDKClient
SDK --> SDKClient
SDKClient --> HTTPClient
end
subgraph External[OOREP API]
API[https://www.oorep.com]
end
MCPClient -->|MCP Protocol| Server
HTTPClient -->|HTTPS| API
关键组件:
- 缓存:带可配置 TTL 的内存 LRU 缓存(默认为 5 分钟)
- 去重器:防止对相同数据发起重复的并发请求
- 验证器:使用 Zod Schema 在 API 调用前验证所有输入
- 会话管理:自动处理 OOREP API 的 Cookie
安全注意事项
输入验证
所有输入均使用 Zod Schema 进行验证:
- 症状搜索:3-200 个字符,并会去除首尾空白字符
- 药物名称:1-100 个字符
- 服务端清理:OOREP API 会进行额外的输入清理
错误处理
- 返回给客户端前,所有错误都会经过脱敏处理
- 绝不会暴露内部详情(堆栈跟踪、文件路径)
- 网络错误会返回通用消息
数据隐私
- 不会存储或要求提供用户凭据
- OOREP 会话为匿名且基于 Cookie
- 不会将数据持久化到磁盘(仅使用内存缓存)
- 所有输入均使用 Zod 模式进行验证
- 返回给客户端前,错误都会经过脱敏处理
速率限制
OOREP MCP Server 不实现内部速率限制。不过:
OOREP API 限制
上游 OOREP API 可能设有速率限制。如果超出限制,你会收到 RateLimitError:
{
content: [{ type: 'text', text: 'Error: Rate limit exceeded. Please try again later.' }],
isError: true
}
缓解策略
-
启用缓存(默认:TTL 为 5 分钟)
"env": { "OOREP_MCP_CACHE_TTL_MS": "300000" } -
使用具体的搜索词,以减少并发请求
-
增加缓存 TTL,用于频繁访问的数据
"env": { "OOREP_MCP_CACHE_TTL_MS": "600000" }
请求去重
SDK 客户端会自动对并发的相同请求进行去重,从而减少 API 负载。
TypeScript 类型导入
直接从程序包导入类型,以实现类型安全的开发:
import type {
// Tool argument types
SearchRepertoryArgs,
SearchMateriaMedicaArgs,
GetRemedyInfoArgs,
ListRepertoriesArgs,
ListMateriaMedicasArgs,
// Result types
RepertorySearchResult,
MateriaMedicaSearchResult,
RemedyInfo,
RepertoryMetadata,
MateriaMedicaMetadata,
// Supporting types
Rubric,
Remedy,
MateriaMedicaResult,
MateriaMedicaSection,
// SDK Client types
OOREPClient,
OOREPSDKConfig,
} from 'oorep-mcp';
模式验证
你也可以导入 Zod 模式进行运行时验证:
import {
SearchRepertoryArgsSchema,
RepertorySearchResultSchema,
RemedyInfoSchema,
} from 'oorep-mcp';
// Validate external data
const validated = SearchRepertoryArgsSchema.parse(untrustedInput);
故障排除
Claude Desktop 中未显示服务器
问题: 配置后未显示 MCP 指示器。
解决方案:
- 完全退出 Claude Desktop(macOS 上按 Cmd+Q,而不是仅关闭窗口)
- 重启 Claude Desktop,等待 10-15 秒以完成 MCP 初始化
- 检查配置文件是否包含有效的 JSON 语法(使用 JSON 验证器)
- 检查日志:
- macOS:
~/Library/Logs/Claude/mcp*.log - Windows:
%APPDATA%\Claude\Logs\mcp*.log
- macOS:
- 验证 npx 是否可用: 在终端中运行
npx -y oorep-mcp,检查服务器是否启动
连接超时错误
问题: 出现“连接超时”或“请求超时”错误。
解决方案:
-
在配置中增加超时时间:
"env": { "OOREP_MCP_TIMEOUT_MS": "60000" } -
检查到 https://www.oorep.com 的网络连接:
curl https://www.oorep.com -
检查是否存在可能阻止连接的防火墙或代理问题
未返回结果
问题: 搜索返回空结果或“未找到结果”。
解决方案:
- 尝试使用更宽泛的搜索词(例如,使用“头痛”而不是“左侧太阳穴头痛,下午 3 点加重”)
- 移除筛选条件,例如
minWeight或特定的 repertory 限制 - 检查是否可以访问 OOREP 网站: https://www.oorep.com
- 尝试其他 repertory: 向 Claude 提问:“改为在 Kent repertory 中搜索”
内存使用量过高
问题: MCP 服务占用过多内存。
解决方案:
-
缩短缓存 TTL,以更频繁地清除缓存:
"env": { "OOREP_MCP_CACHE_TTL_MS": "60000" } -
减少最大结果数:
"env": { "OOREP_MCP_MAX_RESULTS": "50" } -
定期重启 Claude Desktop 以清除缓存
macOS/Linux 上的权限错误
问题: 运行服务时出现“权限被拒绝”。
解决方案:
-
全局安装时: 确保 npm 权限设置正确
sudo npm install -g oorep-mcp -
使用 npx(推荐): 无需权限,使用
-y标志:npx -y oorep-mcp
查看详细日志
如需查看用于故障排除的详细调试日志:
-
将日志级别设为 debug:
"env": { "OOREP_MCP_LOG_LEVEL": "debug" } -
检查 MCP 日志:
- macOS:
tail -f ~/Library/Logs/Claude/mcp*.log - Windows: 检查
%APPDATA%\Claude\Logs\
- macOS:
-
查找特定的错误模式:
NetworkError- 连接问题TimeoutError- 请求耗时过长ValidationError- 输入无效RateLimitError- 请求过多
问题仍未解决?
- 查看现有问题: https://github.com/Dhi13man/oorep-mcp/issues
- 报告新问题: 请提供:
- 你的操作系统及版本
- Node.js 版本(
node --version) - Claude Desktop 版本
- 配置(移除任何敏感数据)
- MCP 日志文件中的错误日志
- 参与讨论: 分享你的使用体验并获取社区帮助
开发
前置条件
- Node.js ≥ 22.12.0
- npm ≥ 10.0.0
设置
git clone https://github.com/Dhi13man/oorep-mcp.git
cd oorep-mcp
npm ci
命令
npm run build # Compile TypeScript
npm run typecheck # Type checking only
npm run dev # Development mode with watch
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report
npm run test:e2e # Live OOREP integration (requires network access)
npm run lint # ESLint
npm run format # Prettier
测试结构
src/
├── **/*.unit.test.ts # Unit tests (mocked dependencies)
└── **/*.integration.test.ts # Integration tests (real implementations)
- 1100+ 项测试,覆盖率达 95%+
- 单元测试使用模拟依赖项
- 集成测试使用真实实现,并模拟 HTTP
免责声明
此工具仅用于教育和信息提供。
- 不构成医疗建议 - 不能替代专业医疗咨询
- 咨询从业者 - 请务必咨询具备资质的顺势疗法从业者
- 不用于诊断 - 不用于诊断或治疗疾病
顺势疗法应仅在具备资质的专业人士指导下进行。
许可证
MIT 许可证 - 详情请参阅 LICENSE 文件。
致谢
- OOREP 团队:感谢创建并维护开源 OOREP 平台
- Anthropic:感谢提供 Model Context Protocol 和 Claude
- MCP 社区:感谢提供工具、文档和支持
链接
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。