MCP 协议与工具集成 — 完整教程¶

一句话说明：MCP（Model Context Protocol，模型上下文协议）是一个开源标准，让 AI 应用（如 Claude Code、OpenCode）能用统一的方式连接外部工具、数据库和 API——白话说就是 AI 的"万能 USB-C 插头"。

目录¶

为什么要学 MCP
核心概念白话版
MCP 生态现状
实操教程：在 OpenCode 中添加 MCP Server
实操教程：在 Claude Code 中添加 MCP Server
实操教程：自己写一个 MCP Server
生信场景 MCP 应用
常见报错与解决
速查表
延伸学习资源

1. 为什么要学 MCP¶

MCP 解决什么问题？¶

在没有 MCP 之前，每个 AI 工具要连接外部服务（GitHub、数据库、搜索引擎等），都得自己写一套"连接器"。这就像每个手机厂商都做自己的充电口——你得准备一堆不同的线。

MCP 的出现就是把这些"充电口"统一了：

以前（没有 MCP）：Claude 想连 GitHub 需要一套代码，连数据库需要另一套，连 Slack 再来一套——每个 AI 工具都要重复造轮子
现在（有 MCP）：只要写一个标准的 MCP Server，所有支持 MCP 的 AI 客户端（Claude Code、OpenCode、Cursor、VS Code 等）都能直接用

白话类比：

就像 USB-C 接口统一了手机充电口。以前安卓用 Micro USB、苹果用 Lightning、笔记本用各种圆口。现在都用 USB-C，一根线走天下。MCP 就是 AI 工具界的 USB-C。

为什么 2025-2026 突然火了？¶

Anthropic 在 2024 年底开源了 MCP 规范，Claude 全线产品（Claude Desktop、Claude Code）率先支持
ChatGPT、VS Code Copilot、Cursor 相继宣布支持 MCP，形成了行业共识
AI Agent（智能体）的爆发：Agent 需要操作真实世界的工具（搜索、写代码、查数据库），MCP 提供了标准化的工具连接方式
开发者社区快速跟进：GitHub 上已有数百个开源 MCP Server，覆盖 GitHub、Notion、PostgreSQL、文件系统等

对你（生信方向）的意义：

你可以让 AI 直接查 NCBI 数据库、操作 R/Python 脚本、连接生信分析 pipeline
面试时能讲清楚 MCP，说明你对 AI 工具生态有深入理解，这是加分项

2. 核心概念白话版¶

2.1 MCP 是什么¶

官方定义：MCP 是一个开源协议，定义了 AI 应用与外部工具之间的通信标准。

白话版：MCP 就是一份"说明书"，告诉 AI 和工具怎么说话。就像餐厅里服务员（AI）和厨房（工具）之间有一套固定的点单格式——服务员按格式写单子，厨房按格式做菜，谁来当服务员都能用这套格式。

2.2 三个角色：Host、Client、Server¶

┌─────────────────────────────────┐
│  MCP Host（宿主/AI 应用）         │
│  比如 Claude Code / OpenCode     │
│                                  │
│  ┌───────────┐  ┌───────────┐   │
│  │ MCP Client│  │ MCP Client│   │  ← 每连一个 Server 就创建一个 Client
│  └─────┬─────┘  └─────┬─────┘   │
│        │              │          │
└────────┼──────────────┼──────────┘
         │              │
   ┌─────▼─────┐  ┌────▼──────┐
   │ MCP Server│  │ MCP Server│    ← 实际提供工具/数据的程序
   │ (GitHub)  │  │ (数据库)   │
   └───────────┘  └───────────┘

角色	白话解释	例子
Host（宿主）	就是你用的 AI 应用，它负责管理所有连接	Claude Code、OpenCode、Cursor
Client（客户端）	Host 内部自动创建的"连接管道"，每连一个 Server 就有一个 Client	你不需要手动管，自动的
Server（服务端）	实际提供功能的程序，可以跑在本地或远程	GitHub Server、文件系统 Server

白话类比：

Host 就像你的手机，Client 就像手机上的蓝牙连接器，Server 就像蓝牙耳机。你（Host）可以同时连好几个蓝牙设备（Server），每个连接就是一个 Client。

2.3 三种能力：Tool / Resource / Prompt¶

MCP Server 能向 AI 提供三种东西：

能力	白话解释	例子
Tool（工具）	AI 可以调用的"函数/操作"	查天气、查数据库、创建 GitHub Issue
Resource（资源）	AI 可以读取的"数据/文件"	数据库表结构、API 返回的 JSON、文件内容
Prompt（提示模板）	预定义的对话模板，帮助 AI 更好地完成特定任务	代码审查模板、数据分析模板

白话类比：

Tool = 瑞士军刀上的工具（剪刀、开瓶器）——用来做事

Resource = 图书馆的书——用来看/读

Prompt = 考试的答题模板——告诉你怎么回答

最常用的是 Tool。大多数 MCP Server 主要暴露 Tool 给 AI 使用。

2.4 两种传输方式：stdio vs HTTP¶

MCP Server 和 Client 之间有两种"通信管道"：

传输方式	白话解释	适用场景
stdio（标准输入输出）	Server 作为本地程序运行，通过命令行的输入/输出通信	本地工具（文件操作、本地数据库）
Streamable HTTP	Server 跑在远程服务器上，通过 HTTP 网络请求通信	云端服务（GitHub API、Sentry、Notion）

白话类比：

stdio = 你在家里直接跟家人说话（面对面，不用网络）

HTTP = 你打电话给远方的朋友（需要网络，但能连远方的人）

底层都用 JSON-RPC 2.0 协议（就是一种格式化的 JSON 消息，用来发请求和收响应）。你不需要深究这个细节，知道有这个东西就行。

3. MCP 生态现状¶

3.1 哪些 AI 工具支持 MCP¶

截至 2026 年，主流 AI 编码工具基本都已支持 MCP：

工具	支持 MCP	备注
Claude Code	是	Anthropic 官方 CLI，MCP 支持最完善
Claude Desktop	是	桌面版 Claude
OpenCode	是	开源 AI 编码 agent，支持本地+远程 MCP
Cursor	是	AI 编辑器
VS Code (Copilot)	是	GitHub Copilot Chat 支持 MCP
ChatGPT	是	OpenAI 后来也跟进了 MCP 支持
Windsurf (Codeium)	是	AI 编码工具

3.2 常用 MCP Server 推荐¶

以下是社区中最常用的 MCP Server，按类别分类：

通用开发类¶

Server 名称	功能	传输方式
GitHub MCP	管理 Issue、PR、代码搜索	HTTP
filesystem	读写本地文件	stdio
PostgreSQL (dbhub)	查询数据库	stdio
Sentry	监控错误和异常	HTTP
Context7	搜索框架/库的最新文档	HTTP
Grep by Vercel	搜索 GitHub 上的代码示例	HTTP
Notion	读写 Notion 页面和数据库	HTTP
Slack	读取/发送消息	HTTP

生信相关（可自建）¶

Server 名称	功能	说明
NCBI Entrez	查 PubMed、GenBank	可封装 Biopython 接口
UniProt	蛋白质数据库查询	可封装 REST API
R/Bioconductor	运行 R 生信分析	可封装 R 脚本调用
BLAST	序列比对	可封装命令行 BLAST+

4. 实操教程：在 OpenCode 中添加 MCP Server¶

OpenCode 通过项目配置文件 opencode.jsonc（或 opencode.json）来管理 MCP Server。

4.1 配置方法¶

在项目根目录创建或编辑 opencode.jsonc：

// opencode.jsonc - OpenCode 的配置文件
{
  // 引入配置的 JSON Schema，提供自动补全
  "$schema": "https://opencode.ai/config.json",

  // mcp 字段定义所有 MCP Server
  "mcp": {
    // 每个 Server 需要一个唯一的名字
    "server-name": {
      // type: "local"（本地）或 "remote"（远程）
      // command: 本地 Server 的启动命令
      // url: 远程 Server 的地址
      // enabled: 是否启用（默认 true）
      // environment: 环境变量（本地 Server 用）
      // headers: HTTP 请求头（远程 Server 用）
    }
  }
}

4.2 添加远程 MCP Server（以 Context7 为例）¶

Context7 是一个帮助 AI 查找最新框架文档的 MCP Server：

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // context7: 查最新的框架/库文档
    "context7": {
      "type": "remote",                       // 远程服务器
      "url": "https://mcp.context7.com/mcp"   // 服务器地址
    }
  }
}

使用时在提示词中加上 use context7：

用 FastAPI 搭建一个 REST API，查一下最新用法。use context7

4.3 添加本地 MCP Server（以 filesystem 为例）¶

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // mcp_everything: 官方测试用的全功能 MCP Server
    "mcp_everything": {
      "type": "local",                                              // 本地服务器
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],  // 启动命令
      "enabled": true                                                // 启用
    }
  }
}

4.4 添加需要 API Key 的本地 Server¶

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // airtable: 连接 Airtable 数据库
    "airtable": {
      "type": "local",
      "command": ["npx", "-y", "airtable-mcp-server"],   // 用 npx 运行
      "enabled": true,
      "environment": {
        // 通过环境变量传入 API Key（不要硬编码密码！）
        "AIRTABLE_API_KEY": "your_api_key_here"
      }
    }
  }
}

4.5 添加需要认证的远程 Server（Sentry 为例）¶

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}   // 空对象表示使用自动 OAuth 认证
    }
  }
}

添加后，在终端执行认证：

# 在终端中手动触发认证流程
opencode mcp auth sentry

4.6 管理已添加的 MCP Server¶

# 查看所有 MCP Server 及其认证状态
opencode mcp list

# 登出某个 Server 的认证
opencode mcp logout sentry

在 OpenCode 中还可以： - 通过 "enabled": false 临时禁用某个 Server - 通过 tools 配置用 glob 模式批量管理 - 通过 agent 配置让特定 Agent 才能用某些 MCP

5. 实操教程：在 Claude Code 中添加 MCP Server¶

Claude Code 使用命令行方式管理 MCP Server。

5.1 添加远程 HTTP Server¶

# 语法：claude mcp add --transport http <名字> <URL>
# 例子：添加 Notion MCP Server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证头的例子
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

5.2 添加本地 stdio Server¶

# 语法：claude mcp add --transport stdio <名字> -- <启动命令>
# 例子：添加 PostgreSQL 查询工具
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/mydb"

# 带环境变量的例子
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

注意：所有选项（--transport、--env、--scope）必须放在 Server 名字之前。-- 双横线之后是传给 MCP Server 的命令和参数。

5.3 管理 Server¶

# 列出所有已配置的 Server
claude mcp list

# 查看某个 Server 的详情
claude mcp get github

# 删除某个 Server
claude mcp remove github

# 在 Claude Code 内部检查 Server 状态
/mcp

5.4 从 Claude Desktop 导入¶

如果你已经在 Claude Desktop 里配置过 MCP Server，可以直接导入：

# 自动导入 Claude Desktop 的 MCP 配置
claude mcp add-from-claude-desktop

5.5 配置作用域（scope）¶

Scope	说明	存储位置
`local`（默认）	仅当前项目、仅自己可用	项目目录 `.claude/settings.local.json`
`project`	当前项目、团队共享（提交到 Git）	项目根目录 `.mcp.json`
`user`	所有项目、仅自己可用	`~/.claude.json`

# 添加到用户级别（所有项目都能用）
claude mcp add --transport http sentry --scope user https://mcp.sentry.dev/mcp

6. 实操教程：自己写一个 MCP Server¶

下面分别用 Python 和 Node.js 写一个最简单的 MCP Server——提供一个"生信工具"，能计算 DNA 序列的 GC 含量和反向互补序列。

6.1 Python 版本¶

安装依赖¶

# 用 pip 安装 MCP Python SDK
pip install "mcp[cli]"

# 或者用 uv（更推荐）
uv add "mcp[cli]"

完整代码：`bioinfo_server.py`¶

#!/usr/bin/env python3
"""
生信 MCP Server - 提供 DNA 序列分析工具
功能：计算 GC 含量、生成反向互补序列
运行方式：python bioinfo_server.py（会以 stdio 模式启动）
"""

# 导入 FastMCP —— MCP Python SDK 的高级封装
# 它会自动把函数的类型注解和文档字符串转成 MCP 工具定义
from mcp.server.fastmcp import FastMCP

# 创建一个 MCP Server 实例，名字叫 "bioinfo"
# 这个名字会在客户端（Claude Code/OpenCode）里显示
mcp = FastMCP("bioinfo")


@mcp.tool()  # 这个装饰器把函数注册为一个 MCP Tool
def gc_content(sequence: str) -> str:
    """
    计算 DNA 序列的 GC 含量（GC content）。

    Args:
        sequence: DNA 序列字符串，只包含 A/T/G/C 四种碱基
    """
    # 把序列统一转成大写，避免大小写问题
    seq = sequence.upper().strip()

    # 检查序列是否只包含合法碱基
    valid_bases = set("ATGC")               # 合法碱基集合
    invalid = set(seq) - valid_bases        # 找出不合法的字符
    if invalid:
        # 如果有非法字符，返回错误提示
        return f"错误：序列包含非法字符 {invalid}，只允许 A/T/G/C"

    if len(seq) == 0:
        return "错误：序列为空"

    # 统计 G 和 C 的数量
    gc_count = seq.count("G") + seq.count("C")

    # 计算 GC 含量百分比
    gc_percent = (gc_count / len(seq)) * 100

    # 返回结果
    return (
        f"序列长度: {len(seq)} bp\n"
        f"G 数量: {seq.count('G')}\n"
        f"C 数量: {seq.count('C')}\n"
        f"GC 含量: {gc_percent:.2f}%"
    )


@mcp.tool()  # 再注册一个工具
def reverse_complement(sequence: str) -> str:
    """
    生成 DNA 序列的反向互补序列（Reverse Complement）。

    Args:
        sequence: DNA 序列字符串
    """
    seq = sequence.upper().strip()

    # 碱基互补配对规则：A-T, G-C
    complement_map = {
        "A": "T",   # 腺嘌呤 ↔ 胸腺嘧啶
        "T": "A",
        "G": "C",   # 鸟嘌呤 ↔ 胞嘧啶
        "C": "G",
    }

    # 逐个碱基做互补转换
    try:
        complemented = "".join(
            complement_map[base] for base in seq
        )
    except KeyError as e:
        return f"错误：序列包含非法碱基 {e}"

    # 反向（reverse）互补序列 = 先互补再反转
    rev_comp = complemented[::-1]  # Python 切片反转

    return (
        f"原始序列:     5'-{seq}-3'\n"
        f"反向互补序列: 3'-{rev_comp}-5'\n"
        f"（通常写作:   5'-{rev_comp}-3'）"
    )


@mcp.tool()
def sequence_stats(sequence: str) -> str:
    """
    统计 DNA 序列的基本信息（碱基组成、长度等）。

    Args:
        sequence: DNA 序列字符串
    """
    seq = sequence.upper().strip()

    if len(seq) == 0:
        return "错误：序列为空"

    # 统计各碱基数量
    counts = {base: seq.count(base) for base in "ATGC"}

    # 计算分子量（粗略估算，每个核苷酸约 330 Da）
    mol_weight = len(seq) * 330

    return (
        f"序列长度: {len(seq)} bp\n"
        f"碱基组成:\n"
        f"  A (腺嘌呤):  {counts['A']} ({counts['A']/len(seq)*100:.1f}%)\n"
        f"  T (胸腺嘧啶): {counts['T']} ({counts['T']/len(seq)*100:.1f}%)\n"
        f"  G (鸟嘌呤):  {counts['G']} ({counts['G']/len(seq)*100:.1f}%)\n"
        f"  C (胞嘧啶):  {counts['C']} ({counts['C']/len(seq)*100:.1f}%)\n"
        f"GC 含量: {(counts['G']+counts['C'])/len(seq)*100:.2f}%\n"
        f"估算分子量: ~{mol_weight:,} Da"
    )


# 主入口：以 stdio 方式运行 Server
if __name__ == "__main__":
    # transport="stdio" 表示通过标准输入/输出通信
    # 这是本地 MCP Server 的标准方式
    mcp.run(transport="stdio")

配置到 OpenCode¶

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bioinfo": {
      "type": "local",
      "command": ["python", "/home/pweaz/mcp-servers/bioinfo_server.py"],
      "enabled": true
    }
  }
}

配置到 Claude Code¶

claude mcp add --transport stdio bioinfo -- python /home/pweaz/mcp-servers/bioinfo_server.py

6.2 Node.js / TypeScript 版本¶

初始化项目¶

# 创建项目目录
mkdir bioinfo-mcp && cd bioinfo-mcp

# 初始化 npm 项目
npm init -y

# 安装 MCP TypeScript SDK 和 Zod（参数校验）
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript

# 创建源码目录
mkdir src

`package.json` 关键配置¶

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node build/index.js"
  }
}

`tsconfig.json`¶

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src/**/*"]
}

完整代码：`src/index.ts`¶

/**
 * 生信 MCP Server (TypeScript 版本)
 * 提供 DNA 序列分析工具：GC 含量、反向互补、碱基统计
 */

// 导入 MCP SDK 的核心类
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
// 导入 stdio 传输层（通过标准输入输出通信）
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
// 导入 zod 用于参数校验（MCP SDK 用它定义工具的输入格式）
import { z } from "zod";

// 创建 MCP Server 实例
const server = new McpServer({
  name: "bioinfo",       // Server 名称
  version: "1.0.0",      // 版本号
});

// 注册工具 1：计算 GC 含量
server.registerTool(
  "gc_content",  // 工具名称（AI 调用时用这个名字）
  {
    // 工具描述（AI 用这个描述来判断什么时候该调用这个工具）
    description: "计算 DNA 序列的 GC 含量百分比",
    // 输入参数的 schema（用 zod 定义）
    inputSchema: {
      sequence: z
        .string()                           // 参数类型：字符串
        .describe("DNA 序列，只包含 A/T/G/C"),  // 参数描述
    },
  },
  // 工具的实际执行逻辑
  async ({ sequence }) => {
    const seq = sequence.toUpperCase().trim();  // 转大写、去空格

    // 校验序列合法性
    if (!/^[ATGC]+$/.test(seq)) {
      return {
        content: [{ type: "text", text: "错误：序列包含非法字符，只允许 A/T/G/C" }],
      };
    }

    // 统计 G 和 C 的数量
    const gcCount = (seq.match(/[GC]/g) || []).length;
    const gcPercent = ((gcCount / seq.length) * 100).toFixed(2);

    return {
      // MCP 工具的返回格式：content 数组，每个元素有 type 和 text
      content: [
        {
          type: "text",
          text: `序列长度: ${seq.length} bp\nGC 含量: ${gcPercent}%`,
        },
      ],
    };
  }
);

// 注册工具 2：反向互补序列
server.registerTool(
  "reverse_complement",
  {
    description: "生成 DNA 序列的反向互补序列",
    inputSchema: {
      sequence: z.string().describe("DNA 序列"),
    },
  },
  async ({ sequence }) => {
    const seq = sequence.toUpperCase().trim();

    // 碱基互补映射
    const complementMap: Record<string, string> = {
      A: "T", T: "A", G: "C", C: "G",
    };

    // 生成互补序列
    const complement = seq
      .split("")
      .map((base) => complementMap[base] || "?")
      .join("");

    // 反转得到反向互补
    const revComp = complement.split("").reverse().join("");

    return {
      content: [
        {
          type: "text",
          text: `原始序列: 5'-${seq}-3'\n反向互补: 5'-${revComp}-3'`,
        },
      ],
    };
  }
);

// 主函数：启动 Server
async function main() {
  // 创建 stdio 传输层
  const transport = new StdioServerTransport();
  // 连接 Server 到传输层
  await server.connect(transport);
  // 日志输出到 stderr（重要！stdio Server 不能用 console.log）
  console.error("Bioinfo MCP Server 已启动 (stdio 模式)");
}

// 运行主函数
main().catch((error) => {
  console.error("启动失败:", error);
  process.exit(1);
});

构建和使用¶

# 编译 TypeScript
npm run build

# 配置到 Claude Code
claude mcp add --transport stdio bioinfo -- node /path/to/bioinfo-mcp/build/index.js

# 配置到 OpenCode（在 opencode.jsonc 中）

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bioinfo": {
      "type": "local",
      "command": ["node", "/path/to/bioinfo-mcp/build/index.js"],
      "enabled": true
    }
  }
}

6.3 重要注意事项¶

stdio Server 禁止用 print()/console.log() 输出到 stdout——这会破坏 JSON-RPC 消息格式。调试信息用 print(..., file=sys.stderr) 或 console.error()
Tool 的描述要写清楚——AI 靠描述来决定什么时候调用你的工具
参数要有类型注解和说明——这样 AI 才知道传什么参数

7. 生信场景 MCP 应用¶

7.1 连接 NCBI 数据库¶

你可以写一个 MCP Server，封装 Biopython 的 Entrez 接口：

from mcp.server.fastmcp import FastMCP
from Bio import Entrez  # Biopython 的 NCBI 接口

mcp = FastMCP("ncbi")
Entrez.email = "your_email@example.com"  # NCBI 要求提供邮箱

@mcp.tool()
def search_pubmed(query: str, max_results: int = 5) -> str:
    """
    在 PubMed 上搜索文献。

    Args:
        query: 搜索关键词（如 "gut microbiome type 2 diabetes"）
        max_results: 返回结果数量，默认 5
    """
    # 调用 NCBI Entrez 搜索接口
    handle = Entrez.esearch(db="pubmed", term=query, retmax=max_results)
    record = Entrez.read(handle)
    handle.close()

    ids = record["IdList"]  # 获取文献 ID 列表
    if not ids:
        return f"未找到与 '{query}' 相关的文献"

    # 获取文献摘要
    handle = Entrez.efetch(db="pubmed", id=ids, rettype="abstract", retmode="text")
    abstracts = handle.read()
    handle.close()

    return f"找到 {record['Count']} 篇文献，展示前 {len(ids)} 篇:\n\n{abstracts}"

7.2 自动化分析 pipeline¶

用 MCP 把你的生信分析脚本暴露给 AI：

import subprocess
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("bioinfo_pipeline")

@mcp.tool()
def run_fastqc(input_file: str) -> str:
    """
    对 FASTQ 文件运行 FastQC 质控。

    Args:
        input_file: FASTQ 文件的绝对路径
    """
    # 执行 FastQC 命令
    result = subprocess.run(
        ["fastqc", input_file, "-o", "/home/pweaz/results/qc/"],
        capture_output=True,  # 捕获标准输出和标准错误
        text=True             # 以文本模式返回
    )

    if result.returncode == 0:
        return f"FastQC 完成！结果保存在 /home/pweaz/results/qc/\n{result.stdout}"
    else:
        return f"FastQC 失败：\n{result.stderr}"

@mcp.tool()
def run_kraken2(input_file: str, database: str = "/db/kraken2/standard") -> str:
    """
    用 Kraken2 进行物种分类（宏基因组分析核心步骤）。

    Args:
        input_file: 输入的 FASTQ 文件路径
        database: Kraken2 数据库路径
    """
    output_file = input_file.replace(".fastq", "_kraken2.txt")
    report_file = input_file.replace(".fastq", "_kraken2_report.txt")

    result = subprocess.run(
        [
            "kraken2",
            "--db", database,
            "--output", output_file,
            "--report", report_file,
            input_file
        ],
        capture_output=True,
        text=True
    )

    if result.returncode == 0:
        return f"Kraken2 分类完成！\n报告: {report_file}\n{result.stderr}"
    else:
        return f"Kraken2 失败：\n{result.stderr}"

7.3 面试中怎么讲 MCP + 生信¶

你可以这样在面试中展示你的 AI 工具理解：

"我在毕业项目中研究了 2 型糖尿病的肠道菌群宏基因组数据。在日常分析中，我使用了 MCP 协议把常用的生信工具（如 FastQC、Kraken2、PubMed 搜索）封装成 MCP Server，这样 AI 编码助手就能直接帮我调用这些工具，比如说'帮我对 sample_01.fastq 做质控'，AI 就会自动调用 FastQC 并返回结果。MCP 的好处是标准化——同一个 Server 在 Claude Code、OpenCode、Cursor 里都能用，不用重复配置。"

8. 常见报错与解决¶

报错 1：`spawn xxx ENOENT`¶

原因：系统找不到 MCP Server 的启动命令（如 npx、python、node）。

解决：

# 检查命令是否在 PATH 中
which npx    # Linux/Mac
where npx    # Windows

# 如果找不到，用绝对路径
claude mcp add --transport stdio bioinfo -- /usr/bin/python3 /path/to/server.py

报错 2：`Server connection failed` / `timeout`¶

原因：MCP Server 启动超时（默认 5 秒）。Server 可能在安装依赖或初始化。

解决：

# Claude Code：增加超时时间（毫秒）
MCP_TIMEOUT=30000 claude

# OpenCode：在配置中设置 timeout
"my-server": {
  "type": "local",
  "command": ["npx", "-y", "some-server"],
  "timeout": 30000   // 30 秒
}

报错 3：`JSON-RPC error` / Server 返回乱码¶

原因：Server 代码中用了 print()（Python）或 console.log()（Node.js）输出到 stdout，破坏了 JSON-RPC 消息。

解决：

# Python：错误写法
print("调试信息")           # 会写到 stdout，破坏通信

# Python：正确写法
import sys
print("调试信息", file=sys.stderr)   # 写到 stderr，不影响通信
import logging
logging.info("调试信息")             # logging 默认写 stderr

// Node.js：错误写法
console.log("调试信息");    // 写到 stdout

// Node.js：正确写法
console.error("调试信息");  // 写到 stderr

报错 4：`Tool not found` / AI 说找不到工具¶

原因：MCP Server 已配置但工具没被 AI 发现，或 Server 未成功启动。

解决：

# 在 Claude Code 中检查 Server 状态
/mcp

# 在 OpenCode 中查看 mcp 列表
opencode mcp list

# 确认 Server 启动没报错——手动运行试试
python bioinfo_server.py   # 应该会挂起等待输入，而不是报错

报错 5：`401 Unauthorized` / 认证失败¶

原因：远程 MCP Server 需要认证（OAuth 或 API Key），但没有提供或已过期。

解决：

# Claude Code：重新认证
/mcp
# 选择对应 Server -> Clear authentication -> 重新认证

# OpenCode：手动触发认证
opencode mcp auth server-name

# 检查 API Key 是否正确设置
echo $MY_API_KEY

报错 6：`context limit exceeded` / 上下文超限¶

原因：MCP 工具定义太多，占用了大量上下文 token。GitHub MCP Server 尤其容易出这个问题。

解决：

# 方案 1：只启用真正需要的 MCP Server
# 方案 2：在 Claude Code 中开启 Tool Search（默认已开）
ENABLE_TOOL_SEARCH=true claude

# 方案 3：在 OpenCode 中按 agent 分配 MCP
# 全局禁用所有 MCP 工具，然后在特定 agent 中启用需要的
"tools": { "my-mcp*": false },
"agent": {
  "my-agent": {
    "tools": { "my-mcp*": true }
  }
}

9. 速查表¶

MCP 核心概念速查¶

概念	白话一句话
MCP	AI 工具的"万能 USB-C 插头"标准
Host	你用的 AI 应用（Claude Code/OpenCode）
Client	Host 内部自动创建的连接管道
Server	提供工具/数据的程序
Tool	AI 能调用的函数（做事）
Resource	AI 能读取的数据（看/读）
Prompt	预定义的对话模板
stdio	本地进程通信（不走网络）
HTTP	远程网络通信（走网络）

OpenCode MCP 配置速查¶

// opencode.jsonc 模板
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    // 本地 Server
    "local-example": {
      "type": "local",
      "command": ["python", "/path/to/server.py"],
      "enabled": true,
      "environment": { "KEY": "value" },
      "timeout": 10000
    },
    // 远程 Server
    "remote-example": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Claude Code MCP 命令速查¶

命令	说明
`claude mcp add --transport http <名字> <URL>`	添加远程 HTTP Server
`claude mcp add --transport stdio <名字> -- <命令>`	添加本地 stdio Server
`claude mcp add-json <名字> '<JSON>'`	用 JSON 直接添加
`claude mcp list`	列出所有 Server
`claude mcp get <名字>`	查看 Server 详情
`claude mcp remove <名字>`	删除 Server
`claude mcp add-from-claude-desktop`	从 Claude Desktop 导入
`/mcp`	在会话中查看 Server 状态

Python MCP Server 模板¶

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """工具描述，AI 靠这个来判断何时调用。"""
    return f"结果: {param}"

if __name__ == "__main__":
    mcp.run(transport="stdio")

10. 延伸学习资源¶

官方资源¶

资源	链接	说明
MCP 官方文档	https://modelcontextprotocol.io	协议规范、SDK 文档
MCP GitHub	https://github.com/modelcontextprotocol	SDK 源码、示例 Server
OpenCode MCP 文档	https://opencode.ai/docs/mcp-servers/	OpenCode 配置指南
Claude Code MCP 文档	https://docs.anthropic.com/en/docs/claude-code/mcp	Claude Code 配置指南

社区资源¶

资源	说明
https://github.com/modelcontextprotocol/servers	官方维护的 MCP Server 合集
MCP Inspector	调试 MCP Server 的交互式工具
Awesome MCP Servers	GitHub 上的社区 Server 推荐列表

MCP 协议与工具集成 — 完整教程¶

目录¶

1. 为什么要学 MCP¶

MCP 解决什么问题？¶

为什么 2025-2026 突然火了？¶

2. 核心概念白话版¶

2.1 MCP 是什么¶

2.2 三个角色：Host、Client、Server¶

2.3 三种能力：Tool / Resource / Prompt¶

2.4 两种传输方式：stdio vs HTTP¶

3. MCP 生态现状¶

3.1 哪些 AI 工具支持 MCP¶

3.2 常用 MCP Server 推荐¶

通用开发类¶

生信相关（可自建）¶

4. 实操教程：在 OpenCode 中添加 MCP Server¶

4.1 配置方法¶

4.2 添加远程 MCP Server（以 Context7 为例）¶

4.3 添加本地 MCP Server（以 filesystem 为例）¶

4.4 添加需要 API Key 的本地 Server¶

4.5 添加需要认证的远程 Server（Sentry 为例）¶

4.6 管理已添加的 MCP Server¶

5. 实操教程：在 Claude Code 中添加 MCP Server¶

5.1 添加远程 HTTP Server¶

5.2 添加本地 stdio Server¶

5.3 管理 Server¶

5.4 从 Claude Desktop 导入¶

5.5 配置作用域（scope）¶

6. 实操教程：自己写一个 MCP Server¶

6.1 Python 版本¶

安装依赖¶

完整代码：bioinfo_server.py¶

配置到 OpenCode¶

配置到 Claude Code¶

6.2 Node.js / TypeScript 版本¶

初始化项目¶

package.json 关键配置¶

tsconfig.json¶

完整代码：src/index.ts¶

构建和使用¶

6.3 重要注意事项¶

7. 生信场景 MCP 应用¶

7.1 连接 NCBI 数据库¶

7.2 自动化分析 pipeline¶

7.3 面试中怎么讲 MCP + 生信¶

8. 常见报错与解决¶

报错 1：spawn xxx ENOENT¶

报错 2：Server connection failed / timeout¶

报错 3：JSON-RPC error / Server 返回乱码¶

报错 4：Tool not found / AI 说找不到工具¶

报错 5：401 Unauthorized / 认证失败¶

报错 6：context limit exceeded / 上下文超限¶

9. 速查表¶

MCP 核心概念速查¶

OpenCode MCP 配置速查¶

Claude Code MCP 命令速查¶

Python MCP Server 模板¶

10. 延伸学习资源¶

官方资源¶

社区资源¶

推荐学习路径¶

完整代码：`bioinfo_server.py`¶

`package.json` 关键配置¶

`tsconfig.json`¶

完整代码：`src/index.ts`¶

报错 1：`spawn xxx ENOENT`¶

报错 2：`Server connection failed` / `timeout`¶

报错 3：`JSON-RPC error` / Server 返回乱码¶

报错 4：`Tool not found` / AI 说找不到工具¶

报错 5：`401 Unauthorized` / 认证失败¶

报错 6：`context limit exceeded` / 上下文超限¶