BioE234 MCP Starter — Student Guide

Welcome! This document is the primary reference for the final project starter.
Read it top to bottom once before writing any code.

---

1. What is this starter?

This repository is a framework for building bioengineering automation tools that an AI assistant can call via MCP (Model Context Protocol).

The framework handles connecting your Python codes to the AI.

Four design principles

1. You write pure Python — biology logic only, no networking or MCP code required.
2. Convention over configuration — the framework auto-discovers your files by name.
3. No plumbing in your tool files — you never import MCP or registration code.
4. Copy >> modify >> extend — start from the examples and edit them.

---

2. Project structure

.
├── 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

Where you spend your time: modules//tools/ and modules//data/.

---

3. How the pipeline works

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. Quick start

Step 0 — Prerequisites

• Python 3.10 or newer
• Visual Studio Code — code.visualstudio.com

Step 1 — Create a virtual environment