Hgnc MCP

hgnc.mcp

  ](https://github.com/armish/hgnc.mcp/actions/workflows/docker-build.yaml)  

HGNC（HUGO基因命名委员会）基因命名资源的MCP（模型上下文协议）服务器。

概述

这个R包提供了访问HGNC基因命名数据的工具，包括搜索、解析和验证基因符号的功能。它还包括一个MCP（模型上下文协议）服务器，该服务器将这些工具暴露给LLM副驾驶和其他MCP兼容客户端。

安装

从GitHub安装

# Install the latest version from GitHub
remotes::install_github("armish/hgnc.mcp")

从源代码安装

如果您已在本地克隆了存储库：

# First, generate documentation (required before installation)
source("generate-docs.R")

# Then install the package
devtools::install(".")

或者，您可以手动生成文档：

roxygen2::roxygenise()
devtools::install(".")

数据管理

该软件包使用智能缓存来管理HGNC完整数据集：

• 首次使用：从官方HGNC源下载数据并在本地缓存
• 后续用途：从缓存加载以实现快速访问
• 更新：自动检查缓存是否过时（默认值：30天），并在需要时刷新

数据函数

# Load HGNC data (downloads and caches on first use)
hgnc  **备注**：MCP Prompts目前正在整合中。一旦出现以下情况，提示功能将自动启用 `plumber2mcp` 包NAMESPACE已更新为导出 `pr_mcp_prompt()`提示功能已实现并准备就绪。

提示是指导AI助手完成多步骤HGNC任务的工作流模板：

1. **使基因列表正常化** -指导将基因符号标准化为经批准的HGNC命名法。有助于批量符号解析、处理别名/以前的符号，以及可选地获取交叉引用。

1. **检查命名是否符合要求** -根据HGNC命名政策验证基因面板。识别未经批准的符号、撤回的基因和重复项，然后提供替换建议和理由。

1. **自那以后发生了什么变化** -生成自特定日期以来HGNC命名变化的人类可读摘要。可用于治理、合规性跟踪和监视列表监控。

1. **从群体中构建基因集** -通过关键字搜索发现HGNC基因组，并从成员中构建可重用的基因集定义。以多种格式（列表、表格、JSON）提供输出，并带有元数据以实现可重复性。

### API文档

当服务器在启用Swagger（默认）的情况下运行时，您可以访问以下位置访问交互式API文档：

http://localhost:8080/__docs__/

这提供了有关每个端点、请求/响应格式的详细信息，并允许您直接从浏览器测试API。

## 部署

HGNC MCP服务器可以根据您的需要以多种方式部署。

### Docker部署

部署服务器最简单的方法是使用Docker。预构建的图像是 **公开可用** 在GitHub容器注册表上，支持多种架构。

#### 可用图像

- **注册表**: `ghcr.io/armish/hgnc.mcp`
- **平台**: `linux/amd64`, `linux/arm64`
- **标签**:
  - `latest` -主分支最新稳定版本
  - `main` -主分支机构的最新承诺
  - `v*` -特定版本标签（例如。， `v1.0.0`)
  - `pr-*` -拉取请求构建以进行测试

每次通过GitHub Actions推送到主分支时，图像都会自动构建并发布。

#### Docker快速入门

Pull the pre-built image (supports both amd64 and arm64)

docker pull ghcr.io/armish/hgnc.mcp:latest

For Claude Desktop (stdio mode)

docker run --rm -i \ -v hgnc-cache:/home/hgnc/.cache/hgnc \ ghcr.io/armish/hgnc.mcp:latest --stdio

For HTTP server mode

docker run -d \ --name hgnc-mcp-server \ -p 8080:8080 \ -v hgnc-cache:/home/hgnc/.cache/hgnc \ ghcr.io/armish/hgnc.mcp:latest

Access the server (HTTP mode only)

open http://localhost:8080/__docs__/

#### 从源代码构建

Clone the repository

git clone https://github.com/armish/hgnc.mcp.git cd hgnc.mcp

Build the Docker image

docker build -t hgnc-mcp:latest .

Run in stdio mode (for Claude Desktop)

docker run --rm -i \ -v hgnc-cache:/home/hgnc/.cache/hgnc \ hgnc-mcp:latest --stdio

Or run in HTTP mode

docker run -d \ --name hgnc-mcp-server \ -p 8080:8080 \ -v hgnc-cache:/home/hgnc/.cache/hgnc \ hgnc-mcp:latest

#### Docker Compose

要获得更完整的持久存储设置：

Start the server and supporting services

docker compose up -d

View logs

docker compose logs -f

Test the server

docker compose --profile test up hgnc-test-client

Stop the server

docker compose down

> **备注**：这使用了现代 `docker compose` 命令（Docker Compose V2）。如果您有传统的独立版本，请使用 `docker-compose` （用连字符）代替。

看  用于高级Docker部署选项，包括：

- 使用Nginx反向代理进行生产部署
- 热重载开发设置
- 资源限制和健康检查
- TLS/HTTPS配置

### 生产部署

对于生产环境，我们建议：

1. **使用Docker** -提供的Dockerfile使用多阶段构建，并以非root用户身份运行
1. **设置反向代理** -使用Nginx或类似工具进行TLS、速率限制和负载平衡
1. **持久缓存** -为HGNC数据缓存装载卷
1. **健康监测** -容器包括健康检查；与您的监控系统集成
1. **资源限制** -设置适当的CPU和内存限制（建议：2个CPU，4GB RAM）

示例生产docker组合配置：

services: hgnc-mcp-server: image: ghcr.io/armish/hgnc.mcp:latest ports: - "127.0.0.1:8080:8080" # Only expose to localhost volumes: - hgnc-cache:/home/hgnc/.cache/hgnc restart: unless-stopped deploy: resources: limits: cpus: '2' memory: 4G reservations: cpus: '0.5' memory: 1G healthcheck: test: ["CMD", "Rscript", "-e", "tryCatch(httr::GET('http://localhost:8080/__docs__/'), error = function(e) quit(status=1))"] interval: 30s timeout: 10s retries: 3

### 云部署

Docker镜像可以部署到任何支持容器的云平台：

#### AWS ECS/Fargate

Tag for AWS ECR

docker tag hgnc-mcp:latest .dkr.ecr..amazonaws.com/hgnc-mcp:latest

Push to ECR

docker push .dkr.ecr..amazonaws.com/hgnc-mcp:latest

Deploy using ECS task definition

#### 谷歌云运行

Tag for Google Container Registry

docker tag hgnc-mcp:latest gcr.io/ /hgnc-mcp:latest

Push to GCR

docker push gcr.io/ /hgnc-mcp:latest

Deploy to Cloud Run

gcloud run deploy hgnc-mcp \ --image gcr.io/ /hgnc-mcp:latest \ --port 8080 \ --memory 4Gi \ --cpu 2

#### Azure容器实例

Create resource group

az group create --name hgnc-mcp-rg --location eastus

Deploy container

az container create \ --resource-group hgnc-mcp-rg \ --name hgnc-mcp-server \ --image ghcr.io/armish/hgnc.mcp:latest \ --ports 8080 \ --cpu 2 \ --memory 4

### Kubernetes

对于Kubernetes部署，请参阅中的示例清单 `examples/kubernetes/` （即将推出）。

### 地方发展

对于没有Docker的本地开发：

Clone the repository

git clone https://github.com/armish/hgnc.mcp.git cd hgnc.mcp

Install dependencies

R -e "install.packages('remotes'); remotes::install_deps()"

Install the package

R CMD INSTALL .

Start the server

Rscript inst/scripts/run_server.R --port 8080

### CI/CD集成

该存储库包括GitHub Actions工作流，用于：

- **R CMD检查** -跨多个平台的包验证
- **测试覆盖率** -具有覆盖率报告的自动化测试
- **Docker构建** -多平台Docker镜像构建（amd64、arm64）

看 `.github/workflows/` 用于工作流配置。

要在fork中使用这些工作流，请执行以下操作：

1. 在存储库设置中启用GitHub操作
1. 添加任何所需的秘密（例如。， `CODECOV_TOKEN`)
1. 按下以触发工作流

### 配置选项

服务器可以通过命令行参数或环境变量进行配置：

|选项|环境变量|默认值|描述|
|--------|---------------------|---------|-------------|
| `--port` | `MCP_SERVER_PORT` |8080 |服务器端口|
| `--host` | `MCP_SERVER_HOST` |0.0.0.0 |服务器主机|
| `--no-swagger` |-|false |禁用Swagger UI|
| `--check-cache` |-|false |启动前检查缓存|
| `--update-cache` |-|false |强制缓存更新|
| - | `HGNC_CACHE_DIR` |平台默认|缓存目录|

环境变量示例：

export HGNC_CACHE_DIR=/data/hgnc export MCP_SERVER_PORT=9090 Rscript inst/scripts/run_server.R

### 安全考虑

部署HGNC MCP服务器时：

1. **网络接入**：默认情况下，服务器绑定到 `0.0.0.0` （所有接口）。对于生产，绑定到 `127.0.0.1` 并使用反向代理
1. **速率限制**：服务器包括HGNC API调用的内部速率限制，但考虑通过反向代理添加外部速率限制
1. **认证**：MCP服务器不包括身份验证。如果需要，使用带有身份验证的反向代理
1. **传输层安全**：在生产环境中始终使用TLS/HTTPS。在反向代理级别进行配置
1. **资源限制**：设置适当的CPU和内存限制，以防止资源耗尽
1. **更新**：定期更新Docker镜像以获取安全补丁和HGNC数据更新

### 监控

监控以下生产部署：

- **健康终点**: `GET /__docs__/` -如果服务器正常，则返回200
- **集装箱健康状况**：已配置Docker/Kubernetes健康检查
- **资源使用**：监控CPU和内存使用情况
- **缓存新鲜度**：检查 `get_hgnc_cache_info()` 缓存年龄
- **错误率**：监视服务器日志中的错误

健康检查脚本示例：

#!/bin/bash

health_check.sh

if curl -f -s http://localhost:8080/__docs__/ > /dev/null; then echo "Server is healthy" exit 0 else echo "Server is unhealthy" exit 1 fi

### 故障排除

常见部署问题：

**端口已在使用中：**

Find what's using the port

lsof -i :8080

Use a different port

docker run -p 9090:8080 hgnc-mcp:latest

**内存不足：**

Increase Docker memory limit

docker update --memory="4g" hgnc-mcp-server

**缓存未持久化：**

Verify volume exists

docker volume inspect hgnc-cache

Check mount point

docker inspect hgnc-mcp-server | grep Mounts -A 10

有关更多部署示例和故障排除，请参阅：

- 
- [MCP客户端配置](examples/mcp-clients/README.md)
- 

## 用法示例

### 基本基因查找

library(hgnc.mcp)

Search for genes

results 你“我有一份来自旧微阵列研究的基因列表：BRCA1、p53、EGFR、HER-2、NBS1。您能否将这些标准化为当前的HGNC符号，并检查是否有任何符号已更新？"

克劳德: *使用normalize_list和validate_panel MCP工具分析基因，并提供包含当前符号、任何更改和建议的详细报告。*

文档

包装插图中提供了全面的文档：

• hgnc.mcp入门 -安装、基本用法和核心功能
• 临床小组基因列表的标准化 -临床基因组学工作流程的最佳实践
• 运行MCP服务器 -MCP服务器设置、配置和部署
• 与HGNC基因组合作 -从家庭和功能群体构建基因面板

在R中查看小插图：

# List all vignettes
vignette(package = "hgnc.mcp")

# View a specific vignette
vignette("getting-started", package = "hgnc.mcp")

贡献

欢迎投稿！请随时提交问题、功能请求或拉取请求。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

作者

布伦特·阿曼·阿克索伊(arman@aksoy.org)