genome-mcp: Instructions file for Claude Code

CLAUDE.md

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

🧬 项目概述

Genome MCP v0.2.5 是一个智能基因组数据服务器，通过MCP协议提供高质量的基因信息查询、同源基因分析和进化研究功能。该项目采用模块化架构，完全基于权威数据库，无模拟数据，科学严谨可靠。

🎯 核心功能

• 🧬 基因信息查询: 基于NCBI Gene数据库的准确基因信息
• 🔄 同源基因分析: 基于Ensembl API的跨物种同源基因查询（253+ TP53同源基因）
• 🧬 进化分析: 系统发育关系构建和保守性分析
• 🔍 语义搜索: 理解查询意图的智能搜索功能
• 📊 批量处理: 优化的并发查询，支持大规模数据分析
• 🔬 科学可靠: 基于权威数据库，完全无模拟数据

🚀 现代化开发工作流（基于uv工具链）

🌟 环境设置和安装

# 🚀 推荐：使用uv进行完整环境管理
uv sync --dev                # 一键创建虚拟环境并安装所有依赖

# ✅ 完成！环境已准备就绪
# uv会自动管理虚拟环境，无需手动激活

# 🔧 传统方式（兼容性，不推荐）
make install                 # 需要手动管理虚拟环境

🔧 代码质量（uv优先）

# 🎯 现代化uv工作流（推荐）
uv run ruff format .         # 智能代码格式化
uv run ruff check .          # 快速代码质量检查
uv run ruff check --fix .    # 自动修复可修复的问题

# 📊 完整质量检查流程
uv run ruff format . && uv run ruff check . && uv run pytest

# 🔧 Makefile方式（兼容性）
make format                  # 传统格式化
make lint                    # 传统代码检查
make check                   # 完整检查
make ci                      # CI流程

🧪 测试（uv方式）

# 🚀 使用uv运行测试（推荐）
uv run pytest                # 运行所有测试
uv run pytest -v             # 详细输出
uv run pytest --cov=genome_mcp --cov-report=html  # 覆盖率报告

# 🎯 运行特定测试
uv run pytest tests/unit/test_core_functionality.py -v
uv run pytest tests/integration/ -v

# 🔧 Makefile方式（兼容性）
make test                    # 传统测试方式
make test-cov                # 传统覆盖率测试

📦 构建和发布（uv现代化）

# 🚀 现代化构建流程（推荐uv）
uv build                     # 构建wheel和source包
uv publish                   # 发布到PyPI（需要认证）

# 🎯 运行MCP服务器（uv方式）
uv run -m genome_mcp         # STDIO模式（推荐）
uv run -m genome_mcp --port 8080      # HTTP模式
uv run -m genome_mcp --mode sse --port 8080  # SSE模式

# 🌐 零安装运行（uvx方式）
uvx genome-mcp               # 直接运行，无需本地安装
uvx genome-mcp --port 8080   # HTTP模式

# 🔧 传统方式（兼容性）
python -m genome_mcp         # 传统启动方式
make build                   # Makefile构建

🔧 uv 高级开发和部署

# 📦 依赖管理
uv add requests              # 添加生产依赖
uv add --dev pytest          # 添加开发依赖
uv remove requests           # 移除依赖
uv sync                      # 重新同步所有依赖

# 🌍 环境检查
uv run python --version      # 查看Python版本
uv run pip list             # 查看已安装包
uv tree                      # 查看依赖树

# 🚀 快速开发和调试
uv run                       # 启动交互式shell
uv run script.py            # 运行Python脚本
uv run python -c "print('Hello')"  # 快速执行Python代码