Metadata-Version: 2.4
Name: mauve-mcp-server
Version: 0.1.0
Summary: A Model Context Protocol server for NCBI.
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython==1.88
Requires-Dist: fastmcp==4.0.2
Requires-Dist: ncbi-genome-download==0.3.3
Requires-Dist: pandas>=2.3.3
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic>=2.10
Requires-Dist: pydantic-settings>=2.10
Requires-Dist: redis>=8.1.0
Requires-Dist: starlette==1.6.0
Requires-Dist: uvicorn>=0.52.4
Dynamic: license-file


# mauve-mcp-server

单个 Python 包 `mauve_mcp_server`，一个 MCP server 同时提供三块能力：

- **Mauve MCP server**（`mauve_mcp_server`）：异步在线 NCBI BLAST + 基因组下载。
- **Mauve 工具**（由 `mauve-mcp` 项目迁入）：`run_progressive_mauve_tool` /
  `check_mauve_binary`，带内存/超时监控；二进制需自行准备（系统 PATH 或本地 bin/，不随仓库/PyPI 分发）。
- **切片 + Redis**：`slice_homologous_segments` 用本地 backbone 切同源片段；
  `blast_search` 的注释结果写入 Redis `RID:<rid>`。

## 目录结构

```raw
mauve-mcp-server/
├── bin/                    # 可选：本地放置 progressiveMauve / mauveAligner（不入库）
├── data/sequences/         # 示例序列（seq1..5.fasta）
├── mauve_mcp_server/        # 唯一 Python 包
│ ├── blast.py              # 异步 BLAST 引擎（在线重试/限流）
│ ├── download.py           # NCBI 基因组下载引擎
│ ├── mauve.py              # Mauve 配置 + 同步/异步执行器
│ ├── slice.py              # backbone -> 同源片段（本地）
│ ├── redis_store.py        # 第二次比对(BLAST)结果存取 Redis
│ ├── server.py             # 主 MCP server（以上工具统一注册）
│ └── ...
├── examples/               # Mauve MCP 客户端示例
│ └── run_flow_demo.py      # 端到端演示（输出到 out/）
├── test/                   # pytest（25 个用例）
├── out/                    # 端到端演示产物（已 gitignore）
└── pyproject.toml
```

## 安装

```bash
uv sync
```

## 运行 NCBI 服务

```bash
# stdio
uv run mauve-mcp-server
# 或
python -m mauve_mcp_server

# Streamable HTTP（默认 127.0.0.1:8080）
python -m mauve_mcp_server --http --port 8080
```

## Mauve 全基因组比对

Mauve（progressiveMauve）由原 `mauve-mcp` 项目迁入，逻辑并入主 MCP server：

- 跨平台（Windows / Linux / macOS），通过 `psutil` 做内存/超时监控
- 异步执行 + 并发限制（默认同时最多 2 个 progressiveMauve 任务）
- 完整的二进制自动探测与错误处理（系统 PATH → 本地 bin/）
- 不再提供独立的 `mauve-mcp` 命令或 `MAUVE_MCP_*` 环境变量入口

### 二进制

progressiveMauve / mauveAligner 二进制**不随仓库或 PyPI 包分发**，需要自行获取并放置：

```bash
# Linux
mkdir -p bin/linux/x64
cp /path/to/progressiveMauve bin/linux/x64/ && chmod +x bin/linux/x64/progressiveMauve

# macOS
cp /path/to/progressiveMauve bin/macos/ && chmod +x bin/macos/progressiveMauve

# Windows
mkdir -p bin/windows/win64
cp /path/to/progressiveMauve.exe bin/windows/win64/
```

自动检测顺序：

1. 系统 PATH
2. 项目根目录 `bin/<platform>/`（含 `win32/win64`、`x86/x64` 架构子目录）
3. `bin/` 根目录

> 注意：原 mauve-mcp 的 `MAUVE_BINARY_DIR` 环境变量并未在代码中生效；
> 自定义二进制目录请用 `BinaryManager(binary_dir=...)`，或在工具参数中传 `mauve_binary`。

### 工具

`run_progressive_mauve_tool(input_files, output_prefix, ...)`

- `input_files`：输入 FASTA 路径列表
- `output_prefix`：结果前缀（生成 `.backbone` / `.alignment`）
- `max_memory_gb`：内存上限（默认 8）
- `timeout_seconds`：超时（默认 3600）
- `mauve_binary`：可选，覆盖自动检测
- `extra_args`：附加命令行参数
- `scratch_dir`：临时目录

`check_mauve_binary()`：返回可用二进制、自动检测结果与有效性。

## Mauve 切片 + Redis 缓存

第一次比对（Mauve）与切片产物都保存在**本地文件**；第二次比对（NCBI BLAST
注释）结果写入 Redis `RID:<rid>`。MCP 工具直接接收本地路径，形成
`下载 → 第一次比对 → 切片（本地）→ 第二次比对（入 Redis）→ LLM` 的闭环。

```bash
# Redis 连接信息默认已在 .env 中，可按需覆盖
REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD=foobared REDIS_DB=0
```

相关 MCP 工具：

- `run_progressive_mauve_tool(input_files, output_prefix, ...)` — 第一次比对，结果落本地文件
- `blast_search(...)` — 第二次比对（BLAST）结果自动写入 `RID:<rid>`
- `slice_homologous_segments(input_files, output_dir, backbone_path)` — 读本地 backbone 切出同源片段（存本地）
- `get_alignment_result(rid="<rid>")` — 查询 `RID:<rid>` 里的 BLAST 结果
- `check_redis()` — 检查 Redis 可用性与键/字段格式

端到端演示（第一次比对 -> 切片 -> 第二次比对 -> Redis）：

```bash
uv run python -m examples.run_flow_demo
```

产物写在 `out/`（不在 git 中）。注意：`data/sequences` 里的样例序列只有几十 bp，
Mauve 比对不出同源区；演示脚本在这种情况下会自动回退用第一条序列跑 BLAST。

`RID:<rid>` 的 HASH 字段对齐 db0 参考键 `RID:65D31GPG016`：
`Program` / `Database` / `Job Title` / `Description` / `Molecule type` /
`Query Length` / `Alignment`（BLAST 注解结果放在 `Alignment` 的 JSON 中）。

客户端调用示例见 `examples/client_example.py`；完整端到端流程见上文演示命令。

## 测试

```bash
uv run pytest test/
```

当前 25 个用例全部通过（包含真实 Mauve 端到端与真实 Redis 写读删）。

## MCP 客户端配置（Mauve MCP）

```json
{
  "McpServer": {
    "mauve-mcp-server": {
      "name": "mauve-mcp-server",
      "type": "streamableHttp",
      "description": "A Model Context Protocol server for NCBI.",
      "isActive": false,
      "provider": "星旅人",
      "providerUrl": "https://white-album.top",
      "logoUrl": "https://white-album.top/favicon.ico",
      "tags": [
       "biopython",
       "ncbi",
       "mcp"
      ],
      "baseUrl": "http://localhost:8000/mcp",
      "headers": {
        "X-MCP-API-TOKEN": ""
      }
    }
  }
}
```
