MCP Gemini Minimal

BioE234 MCP入门指南

欢迎这份文件是 主要参考 对于最终的项目启动者。\ 在编写任何代码之前，从上到下阅读一次。

______________________________________________________________________

1.这个启动器是什么？

此存储库是用于构建 生物工程自动化工具 AI助手可以通过 MCP（模型上下文协议）.

该框架负责将Python代码连接到AI。

四大设计原则

1. 你写的是纯Python --只需要生物学逻辑，不需要网络或MCP代码。
2. 约定优于配置 --框架会自动按名称发现您的文件。
3. 工具文件中没有管道 --您从不导入MCP或注册码。
4. 复制>>修改>>扩展 --从示例开始并编辑它们。

______________________________________________________________________

2.项目结构

.
├── server.py                      # MCP server — do not edit
├── client_gemini.py               # Gemini CLI client — do not edit
├── requirements.txt
│
├── tests/
│   └── test_tools.py
│
└── modules/
    ├── __init__.py                # Scans all sub-modules — do not edit
    │
    └── seq_basics/                # EXAMPLE MODULE (copy this for your project)
        ├── __init__.py
        ├── SKILL.md               # AI guidance for this module (optional)
        ├── _utils.py              # Shared constants (codon table, etc.)
        ├── _plumbing/             # Auto-registration internals — do not edit
        │   ├── __init__.py
        │   ├── register.py
        │   └── resolve.py
        ├── data/
        │   └── pBR322.gb          # Sequence data files go here
        └── tools/
            ├── reverse_complement.py    # Example: Python implementation
            ├── reverse_complement.json  # Example: C9 JSON wrapper
            ├── translate.py
            ├── translate.json
            └── prompts.json             # Example test prompts

你花时间的地方： modules//tools/ 和 modules//data/.

______________________________________________________________________

3.管道是如何工作的

python client_gemini.py
        │
        ├─► launches server.py as a subprocess
        │         │
        │         └─► scans modules/  (one folder per project)
        │                   └─► for each folder: reads .py + .json pairs, registers tools
        │                                         reads .gb / .fasta files, registers resources
        │
        ├─► connects to server, lists tools and resources
        │
You:    └─► type a request
                │
                ▼
            Gemini decides which tool to call and with what arguments
                │
                ▼
            server calls your Python function
                │
                ▼
            result returned to Gemini, which explains it to you

______________________________________________________________________

4.快速启动

步骤0--先决条件

• Python 3.10或更新版本
• Visual Studio代码-- code.visualstudio.com

步骤1——创建虚拟环境

用VS Code打开终端(Terminal >> New Terminal):

python -m venv .venv
source .venv/bin/activate        # Mac / Linux
# .venv\Scripts\activate         # Windows

你应该看看 (.venv) 在终点线的起点。然后安装依赖项：

pip install -r requirements.txt

第2步-获取Gemini API密钥

1. 首选 https://aistudio.google.com/api-keys
2. 使用您的账号登录 加州大学伯克利分校谷歌账户 （包括免费访问）。
3. 点击 “创建API密钥” 并复制密钥。
4. 在项目根文件夹中，创建一个名为的文件 .env 包含：

GEMINI_API_KEY="paste_your_key_here"

🔴 安全警告： 从不上传 .env 到GitHub。确保 .env 列在 .gitignore. 在项目文件夹中运行以下命令： echo“.env”>>.gitignore

步骤3——运行客户端

python client_gemini.py

预期产量：

[server] Starting BioE234 MCP server...
[register] ✓ Tool registered:    dna_reverse_complement
[register] ✓ Tool registered:    dna_translate
[register] ✓ Resource registered: pBR322  (...)
[server] All modules registered. Server ready.

Connected to MCP server.
Discovered tools:
  - dna_reverse_complement: Return the reverse complement of a DNA sequence...
  - dna_translate: Translate DNA to protein...

尝试键入：

Translate the first 60bp of pBR322 in frame 1

那么你应该得到：

Gemini: The first 60bp of pBR322 translated in frame 1 is FSCLTAYHR*ALMR*FITVK.

______________________________________________________________________

5.每个工具是两个文件

对于您创建的每一个工具 两个具有相同词干名称的文件 在你的 tools/ 文件夹：

gc_content.py     ← Python implementation (the biology logic)
gc_content.json   ← C9 JSON wrapper      (the metadata / schema)

没有第三个“包装器”文件。 这 .json 文件 *是* 你的C9包装。这就是评分标准中“C9包装”的含义。Python文件只包含生物学代码，根本没有MCP特定的代码。

______________________________________________________________________

6.Python文件-函数对象模式

您的Python文件必须遵循 功能对象模式：一个班级 initiate() 和 run() 方法和结构化文档字符串。这是整个课程中使用的相同模式。

• initiate() --一次性设置（构建查找表、加载配置等）
• run() --实际计算；每次工具调用调用一次

模板

class GcContent:
    """
    Description:
        Computes the fraction of G and C bases in a DNA sequence.

    Input:
        seq (str): DNA sequence (resource name or raw string).

    Output:
        float: GC fraction between 0.0 and 1.0.

    Tests:
        - Case:
            Input: seq="ATGCATGC"
            Expected Output: 0.5
            Description: Balanced sequence, 50% GC.
        - Case:
            Input: seq="AAAA"
            Expected Output: 0.0
            Description: All A bases, 0% GC.
        - Case:
            Input: seq=""
            Expected Output: 0.0
            Description: Edge case — empty sequence returns 0.
    """

    def initiate(self) -> None:
        pass   # nothing to set up for this tool

    def run(self, seq: str) -> float:
        """Return GC fraction between 0 and 1."""
        seq = seq.upper()
        gc = sum(1 for b in seq if b in "GC")
        return gc / len(seq) if seq else 0.0

# Optional: module-level alias so pytest can import the function directly.
_instance = GcContent()
_instance.initiate()
gc_content = _instance.run   # gc_content("ATGC") → 0.5

命名规则--关键

⚠️ 以文件的功能命名文件，而不是 bio_functions.py.\ 如果每个学生都使用 bio_functions.py，文件将发生冲突。

好名字： gc_content.py, find_pam_sites.py, design_primers.py, codon_count.py

这 类名 可以是任何描述性的。这 文件名 是您在JSON包装器中使用的 execution_details.source.

规则

• 始终添加类型提示： seq: str, frame: int, pam: str = "NGG"等等。
• 返回JSON可序列化值： str, int, float, list, dict.
• 提高 ValueError 对于无效输入，有明确的信息。
• 从不 print() 在工具内部——返回值。

______________________________________________________________________

7.JSON文件——C9包装器

这 .json 文件正式描述了您的工具。它遵循中的模式 Function_Development_Specification.md 评分员将其评估为“C9包装器”组件。

模板

{
  "id": "org.bioe234.function.seq.gc_content.v1",
  "name": "DNA GC Content",
  "description": "Compute the GC content (fraction of G and C bases) of a DNA sequence.",
  "type": "function",
  "keywords": ["DNA", "GC content", "sequence analysis"],
  "date_created": null,
  "date_last_modified": null,

  "inputs": [
    {
      "name": "seq",
      "type": "string",
      "description": "DNA sequence. Accepts a resource name (e.g. 'pBR322') or a raw sequence string."
    }
  ],

  "outputs": [
    {
      "type": "number",
      "description": "GC fraction between 0.0 (no GC) and 1.0 (all GC)."
    }
  ],

  "examples": [
    {
      "input":  { "seq": "ATGCATGC" },
      "output": { "result": 0.5 }
    },
    {
      "input":  { "seq": "AAAA" },
      "output": { "result": 0.0 }
    }
  ],

  "execution_details": {
    "language": "Python",
    "source": "modules/seq_basics/tools/gc_content.py",
    "initialization": "initiate",
    "execution": "run",
    "disposal": null,

    "mcp_name": "dna_gc_content",
    "seq_params": ["seq"]
  }
}

必填字段

execution_details.mcp_name 和 execution_details.seq_params 是特定于框架的扩展，它们存在于内部 execution_details 因为它们是关于你的代码是如何运行的，而不是它在生物学上的作用。

支持的输入/输出类型

string, integer, number, boolean, array, object

______________________________________________________________________

8.具有多个输入参数的工具

# hamming_distance.py
class HammingDistance:
    def initiate(self): pass
    def run(self, seq1: str, seq2: str) -> int:
        if len(seq1) != len(seq2):
            raise ValueError("Sequences must have equal length.")
        return sum(a != b for a, b in zip(seq1, seq2))

在JSON中，在下面列出这两个名称 seq_params:

"execution_details": {
  ...,
  "mcp_name": "dna_hamming_distance",
  "seq_params": ["seq1", "seq2"]
}

两者 seq1 和 seq2 可以是资源名称或原始序列。

______________________________________________________________________

9.非顺序工具

如果你的工具没有提取DNA/RNA序列， 省略 seq_params 完全：

# restriction_site_count.py
class RestrictionSiteCount:
    def initiate(self): pass
    def run(self, dna: str, site: str) -> int:
        return dna.upper().count(site.upper())

"execution_details": {
  "language": "Python",
  "source": "modules/seq_basics/tools/restriction_site_count.py",
  "initialization": "initiate",
  "execution": "run",
  "mcp_name": "dna_restriction_site_count"
}

______________________________________________________________________

10.如何自动解析序列

当参数在中列出时 seq_params，框架会自动将其转换为 run() 被称为：

你的函数总是收到一个干净的大写字符串。不需要文件解析。

______________________________________________________________________

11.添加序列数据文件

掉落 .gb 或 .fasta 文件进入 modules//data/。重新启动服务器，它们将立即作为资源可用。

data/
  pBR322.gb       →  resource name "pBR322"
  mg1655.fasta    →  resource name "mg1655"

______________________________________________________________________

12.测试提示--prompts.json

您必须提交 prompts.json 将文件放在工具旁边。每个条目都是用户可能键入的自然语言提示，与预期的工具调用配对。看 modules/seq_basics/tools/prompts.json 确切的格式。

[
  {
    "prompt": "What is the GC content of ATGCATGC?",
    "expected_tool": "dna_gc_content",
    "expected_args": { "seq": "ATGCATGC" },
    "notes": "Basic raw sequence input."
  }
]

______________________________________________________________________

13.SKILL.md——引导人工智能

每个模块可以包含一个 SKILL.md 文件。找到后，其内容会自动 在启动时注入Gemini的系统提示，提供AI背景知识 它需要正确使用你的工具。

需要吗？ 不。没有它，系统就可以工作。但没有它，双子座只有 短的 description 您的字段 .json 包装纸可以继续。很好 SKILL.md 有意义地提高双子座的反应质量——它知道你的资源是什么 包含、如何解释结果以及需要注意哪些边缘情况。

放什么进去：

• 模块在一个段落中的作用
• 资源表及其包含的内容
• 对于每种工具：何时使用，参数意味着什么，如何解释输出
• 双子座需要的任何领域词汇或生物背景

模板 --创建 modules//SKILL.md:

#  — Skill Guidance for Gemini

## What this module does
One paragraph describing the biological domain and purpose of this module.

## Available resources
| Resource name | Description |
|---------------|-------------|
| `my_genome`   | E. coli K-12 MG1655 complete genome, 4.6 Mbp. |

## Tools and when to use them

### `my_tool_mcp_name`
What it computes and when Gemini should call it.
- Trigger phrases: "find X", "scan for Y", "does this sequence contain Z"
- Parameter notes: what each parameter means in plain language
- Output notes: how to interpret the result

## Interpreting results
Any domain knowledge that helps Gemini explain results correctly.

看 modules/seq_basics/SKILL.md 一个完整的工作示例。

代币预算： SKILL.md包含在每个请求中。保持在300线以下。 长文件会增加成本，并可能将其他上下文挤出Gemini的窗口。

______________________________________________________________________

14.创建自己的模块

modules/
  /
    __init__.py          ← copy from seq_basics/ (can be empty)
    SKILL.md             ← describe what this module does for the AI
    data/
      my_genome.gb       ← example data
    tools/
      find_pam.py        ← example tool 1
      find_pam.json      ← example json file for tool 1
      prompts.json       ← example tool 2
      test_find_pam.py   ← example json file for tool 2

modules/__init__.py 自动发现新文件夹——您不需要编辑它。

______________________________________________________________________

15.运行测试

pytest -vv -l

编写涵盖典型输入和边缘情况的测试。看 tests/test_tools.py 例如，它显示了如何直接测试类和通过模块级别名测试类。

______________________________________________________________________

16.提交什么

在bCourses上提交您的GitHub仓库URL。回购应反映您的 个人 贡献，而不是整个团队的工作。

______________________________________________________________________

17.故障排除

启动后工具未出现\ 寻找 [register] WARNING 终端中的线路。该消息将准确说明缺少的内容——通常是 .json 包装文件，丢失 run() 方法或格式错误的JSON。

API密钥错误\ 确保 .env 位于项目根目录（不是子文件夹）中，包含 GEMINI_API_KEY="...".创建文件后重新启动终端。

双子座503\ 服务器繁忙。等待30秒——客户端会自动重试。

python 未找到\ 使用 python3 在Mac/Linux上。

ModuleNotFoundError\ 首先激活您的虚拟环境： source .venv/bin/activate.

______________________________________________________________________

还在卡住吗？

给助教发电子邮件： javadamn@berkeley.edu