SAMtools MCP (模型控制协议)

SAMtools 的模型控制协议实现，为处理 SAM/BAM/CRAM 文件提供了一个标准化的接口。

特性

• 查看和转换 SAM/BAM/CRAM 文件
• 排序 alignment 文件
• 索引 BAM/CRAM 文件
• 生成统计信息
• 合并多个 BAM 文件
• 计算 read depth
• 索引 FASTA 文件
• 更多...

核心功能

• 文件格式支持: 处理 SAM (文本), BAM (二进制), 和 CRAM (压缩) alignment 文件
• 格式转换: 在 SAM, BAM, 和 CRAM 格式之间无缝转换
• 区域特定分析: 提取和分析特定的基因组区域
• 基于 Flag 的过滤: 基于 SAM flags 过滤 reads
• 性能优化: 多线程操作用于排序和合并
• 统计分析: 生成全面的 alignment 统计信息

工具概览

工具	描述	主要特性
view	查看和转换 alignment 文件	- 格式转换 (SAM/BAM/CRAM)<br>- 区域过滤<br>- 基于 Flag 的过滤<br>- Header 操作
sort	排序 alignment 文件	- 基于坐标的排序<br>- 基于名称的排序<br>- 每个线程的内存控制<br>- 多线程支持
index	索引 BAM/CRAM 文件	- BAI 索引生成<br>- CSI 索引支持<br>- CRAM 索引创建
merge	合并多个 BAM/CRAM 文件	- 多文件合并<br>- 线程启用处理<br>- Header 协调
depth	计算 read depth	- Per-base depth 计算<br>- 区域特定分析<br>- 多文件支持
flagstat	生成 alignment 统计信息	- 全面的 flag 统计信息<br>- 质量检查<br>- Paired-end 指标
idxstats	BAM/CRAM 索引统计信息	- 参考序列统计信息<br>- Mapped/unmapped 计数<br>- 长度信息
faidx	索引 FASTA 文件	- FASTA 索引<br>- 区域提取<br>- 序列检索

安装

使用 Docker (推荐)

使用 SAMtools MCP 最简单的方法是通过 Docker:

# 拉取 Docker 镜像
docker pull nadhir/samtools-mcp:latest

# 运行容器
docker run -it --rm nadhir/samtools-mcp:latest

# 要处理 BAM 文件，挂载一个 volume:
docker run -it --rm -v /path/to/your/bam/files:/data nadhir/samtools-mcp:latest

本地安装

1. 克隆仓库:

git clone https://github.com/your-username/samtools_mcp.git
cd samtools_mcp

2. 安装依赖:

pip install uv
uv pip install -r requirements.txt

配置

MCP 服务器配置

要配置 MCP 服务器以使用 Docker 镜像，请将以下内容添加到您的 MCP 配置文件中：

{
  "servers": {
    "samtools": {
      "type": "docker",
      "image": "nadhir/samtools-mcp:latest",
      "volumes": [
        {
          "source": "/path/to/your/data",
          "target": "/data"
        }
      ]
    }
  }
}

本地 MCP 配置

要配置 MCP 以使用 uv 运行，请将以下内容添加到您的 ~/.cursor/mcp.json 中：

{
  "samtools_mcp": {
    "command": "uv",
    "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/samtools_mcp.py"]
  }
}

将 /path/to/samtools_mcp.py 替换为您的 samtools_mcp.py 文件的实际路径。

用法

基本命令

1. 查看 BAM 文件:

from samtools_mcp import SamtoolsMCP

mcp = SamtoolsMCP()
result = mcp.view(input_file="/data/example.bam")

2. 排序 BAM 文件:

result = mcp.sort(input_file="/data/example.bam", output_file="/data/sorted.bam")

3. 索引 BAM 文件:

result = mcp.index(input_file="/data/sorted.bam")

高级用法

1. 查看带有 flags 的特定区域:

result = mcp.view(
    input_file="/data/example.bam",
    region="chr1:1000-2000",
    flags_required="0x2",
    output_format="SAM"
)

2. 按 read name 排序:

result = mcp.sort(
    input_file="/data/example.bam",
    output_file="/data/namesorted.bam",
    sort_by_name=True
)

3. 计算具有多个输入文件的 depth:

result = mcp.depth(
    input_files=["/data/sample1.bam", "/data/sample2.bam"],
    region="chr1:1-1000000"
)

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。