Skip to content

CLAUDE.md

Latest commit

 

History

History
403 lines (301 loc) · 11 KB

CLAUDE.md

File metadata and controls

403 lines (301 loc) · 11 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Monorepo Architecture Overview

这是一个医疗 MCP (Model Context Protocol) 服务器的 monorepo，每个 src/ 下的目录都是独立的 TypeScript/Node.js 包，可以独立开发、构建、测试和发布到 npm registry。

核心特征

  • 独立包管理: 每个医疗工具都是独立的 npm 包
  • 统一脚手架: 所有包遵循相同的结构和标准
  • 批量操作: 支持批量构建、测试、发布
  • 无依赖关系: 包之间完全独立，无交叉依赖

开发命令

Monorepo 管理

# 安装所有依赖并构建
npm run bootstrap

# 构建所有包
npm run build

# 运行所有包的测试
npm run test

# 代码质量检查
npm run lint
npm run format

# 清理所有构建文件
npm run clean

# 列出所有工作空间包
npm run list-packages

包管理操作

# 创建新的医疗工具包
npm run create-package <包名> <显示名称> <功能描述>
# 示例：
npm run create-package egfr-calculator "EGFR计算器" "肾小球滤过率计算"

# 版本管理
npm run version:bump patch   # 所有包升级补丁版本
npm run version:bump minor   # 所有包升级次版本
npm run version:bump major   # 所有包升级主版本

# 发布管理
npm run publish:all          # 发布所有包到 npm
npm run publish:all --dry-run # 预览发布（不实际发布）

# DXT 扩展打包
npm run pack:dxt             # 为所有包打包DXT扩展（输出到 release/ 目录）
npm run pack:dxt:all         # 批量打包所有DXT扩展（统一输出到 release/ 目录）

# 更新 TypeScript 项目引用
npm run update-tsconfig

单个包开发

cd src/<package-name>

npm run dev          # 开发模式（自动重载）
npm run build        # 构建当前包
npm run test         # 测试当前包
npm run lint         # 检查当前包代码质量
npm start           # 运行构建后的包
npm run pack:dxt     # 打包为DXT扩展（输出到根目录 release/ 目录）

包结构标准

每个医疗工具包遵循以下标准结构：

src/<package-name>/
├── package.json          # 包配置 (@medical-mcp/<name>)
├── manifest.json         # DXT扩展清单文件 (必需)
├── tsconfig.json         # TypeScript 配置
├── src/
│   ├── index.ts          # MCP 服务器主文件
│   └── types.ts          # TypeScript 类型定义
├── scripts/
│   └── pack-dxt.js       # DXT打包脚本
├── README.md             # 包说明文档
├── examples.md           # 使用示例
└── dist/                 # 构建输出目录
    └── *.js              # 编译后的JS文件

包命名规范

  • npm 包名: @medical-mcp/<name> (例如: @medical-mcp/egfr-calculator)
  • 目录名: kebab-case 格式 (例如: egfr-calculator)
  • 显示名: 中文医疗术语 (例如: "EGFR计算器")

MCP 服务器实现标准

每个包都实现完整的 MCP 服务器，包含：

必须实现的组件

  1. 工具定义 (Tool Definition)

    • JSON Schema 输入验证
    • 清晰的中文描述
    • 合理的参数范围限制

  2. 医疗计算逻辑

    • 准确的医疗公式实现
    • 输入参数验证（年龄、性别、生理指标）
    • 异常值处理和边界检查

  3. 输出格式化

    • 标准化的中文医疗术语
    • 临床参考范围和意义解释
    • 风险分层和警告提示
    • 相关医学文献引用

  4. 错误处理

    • 输入验证错误
    • 计算过程错误
    • 统一的错误响应格式

技术标准

  • TypeScript: 严格模式，完整类型定义
  • MCP 协议: 完全符合 MCP 1.17.3 规范
  • ESM 模块: 使用 ES Module 语法
  • 错误处理: 完善的 try-catch 和验证机制
  • DXT 兼容: 必须包含有效的 manifest.json 文件
  • 工具命名: 遵循MCP最佳实践，使用描述性的工具名和说明
  • 双语文档: 必须同时提供中文和英文版本的README文档

文档标准

  • README.md: 中文版主文档，包含完整的功能介绍、使用指南和技术说明
  • README_EN.md: 英文版文档，与中文版保持内容同步和格式一致
  • 双语要求: 所有新生成的医疗工具必须同时提供中英双语文档
  • 内容一致性: 两个版本应包含相同的技术信息、使用示例和注意事项
  • 国际化考虑: 英文版应使用国际医学术语和标准单位

开发工作流

创建新医疗工具的完整流程

  1. 生成包结构

    npm run create-package bmi-calculator "BMI计算器" "体重指数计算"

  2. 进入包目录开发

    cd src/bmi-calculator
npm install

  3. 实现医疗逻辑

    • 编辑 src/index.ts 实现具体的医疗计算
    • 更新 src/types.ts 添加专用类型定义
    • 确保输入验证和临床警告完整

  4. 测试和构建

    npm run build    # 构建包
npm run test     # 运行测试
npm run lint     # 代码质量检查

  5. 创建DXT扩展

    npm run pack:dxt     # 生成DXT扩展文件（输出到根目录 release/ 目录）

  6. 更新文档

    • 完善 README.md 中的医疗背景和使用说明（中文版）
    • 创建 README_EN.md 英文版文档，保持内容和格式与中文版一致
    • 在 examples.md 中添加真实的临床使用示例
    • 确保 manifest.json 信息准确完整
    • 验证双语文档的完整性和准确性

  7. 发布包

    # 回到根目录
cd ../..
npm run version:bump patch
npm run publish:all
npm run pack:dxt:all  # 批量生成DXT扩展（统一输出到 release/ 目录）

批量操作工作流

# 开发多个包后，统一处理
npm run build              # 构建所有包
npm run test               # 测试所有包
npm run lint               # 检查所有包
npm run pack:dxt:all       # 批量生成DXT扩展（统一输出到 release/ 目录）
npm run version:bump minor # 统一升级版本
npm run publish:all        # 批量发布

重要脚本说明

包创建脚本 (scripts/create-package.js)

  • 自动生成标准包结构
  • 包含完整的 MCP 服务器模板
  • 预配置 TypeScript 和 npm 设置
  • 生成标准化文档模板

版本管理脚本 (scripts/version-bump.js)

  • 支持批量版本升级
  • 支持指定特定包升级
  • 支持设置固定版本号
  • 包含安全检查和预览功能

发布脚本 (scripts/publish-all.js)

  • 批量发布到 npm registry
  • 自动检查包的可发布性
  • 跳过已存在的版本
  • 支持 dry-run 模式预览

构建脚本 (scripts/build-all.js)

  • 并行构建所有包
  • 智能跳过无源码的包
  • 支持监听模式
  • 详细的构建状态报告

DXT打包脚本 (scripts/pack-all-dxt.js)

  • 批量生成DXT扩展文件
  • 自动识别包含manifest.json的包
  • 并行打包提高效率
  • 详细的打包状态报告和错误处理

Desktop Extensions (DXT) 支持

DXT 扩展规范

本项目完全支持 Desktop Extensions (DXT) 格式，这是一种类似于Chrome扩展(.crx)或VS Code扩展(.vsix)的zip归档格式，用于分发本地MCP服务器。

DXT 设计原则

  1. 单击安装: 用户可以通过双击.dxt文件一键安装MCP服务器
  2. 自包含: 包含所有必需的依赖和运行时文件
  3. 安全隔离: 明确声明权限需求，提供安全边界
  4. 版本管理: 支持自动更新和版本控制
  5. 标准化: 遵循统一的manifest规范，确保跨应用兼容性

DXT 核心组件

每个DXT扩展必须包含：

  1. manifest.json - 扩展元数据和配置

    {
  "dxt_version": "1.0",
  "manifest_version": "1.0",
  "name": "@medical-mcp/package-name",
  "version": "1.0.0",
  "description": "医疗工具描述",
  "author": {
    "name": "Author Name",
    "email": "author@example.com"
  },
  "license": "MIT",
  "server": {
    "entry_point": "dist/index.js",
    "runtime": "node",
    "node": {
      "min_version": "18.0.0"
    }
  },
  "mcp_config": {
    "capabilities": ["tools"],
    "tools": [...]
  },
  "permissions": {
    "network": false,
    "filesystem": false
  }
}

  2. 服务器代码 - 编译后的MCP服务器

  3. 依赖包 - 所有必需的node_modules

  4. 文档 - README.md和使用示例

DXT 打包工作流

单个包DXT打包

cd src/egfr-calculator
npm run pack:dxt
# 生成: dist/egfr-calc-mcp-server.dxt

批量DXT打包

# 在根目录
npm run pack:dxt:all
# 为所有包含manifest.json的包生成DXT文件

DXT 安装使用

  1. 生成DXT文件: 运行npm run pack:dxt，所有DXT文件统一输出到根目录的 release/ 目录
  2. 分发扩展: 将生成的.dxt文件提供给用户
  3. 一键安装: 用户双击.dxt文件，在支持的应用中自动安装
  4. 配置使用: 扩展自动配置MCP服务器连接

重要说明: 所有DXT文件都会输出到项目根目录的 release/ 目录中，便于统一管理和分发。

DXT 兼容性

  • Claude for macOS/Windows: 原生支持DXT格式
  • 其他AI应用: 遵循开放标准，易于集成
  • 开发者工具: 可通过MCP Inspector调试

Claude Desktop 集成

单个工具配置

{
  "mcpServers": {
    "{mcp-server-name}": {
      "command": "npx",
      "args": ["@medical-mcp/{toolnameA}"]
    }
  }
}

医疗工具开发标准

输入验证要求

  • 年龄范围：0-120 岁
  • 性别选项：male/female
  • 生理指标：合理的医学范围
  • 单位换算：支持常用医学单位

输出格式要求

  • 计算结果：数值 + 单位
  • 临床意义：参考范围 + 风险分层
  • 注意事项：异常值警告
  • 参考文献：相关医学指南

中文本地化

  • 所有用户界面文本使用中文
  • 医疗术语使用标准中文表述
  • 错误消息提供中文说明
  • 临床解释符合中国医疗实践

关键开发注意事项

  1. 医疗准确性: 所有计算公式必须经过医学验证
  2. 安全警告: 必须包含适当的医疗免责声明
  3. 类型安全: 使用严格的 TypeScript 类型检查
  4. 错误处理: 完善的输入验证和异常处理
  5. 文档完整: 详细的使用说明和临床背景
  6. 版本管理: 遵循语义化版本控制

故障排除

常见问题

  • 构建失败: 检查 TypeScript 配置和类型定义
  • 发布失败: 确认 npm 登录状态和包名唯一性
  • 包依赖: 确保各包独立，无交叉依赖
  • 版本冲突: 使用版本管理脚本统一处理

调试命令

npm run list-packages     # 检查包状态
npm run clean             # 清理构建缓存
npm run update-tsconfig   # 修复 TypeScript 引用
npm run build -- --verbose # 详细构建信息

这个 monorepo 架构为医疗 MCP 服务器提供了完整的开发、构建和发布流程，确保每个医疗工具都能独立开发和维护，同时保持统一的质量标准。