Skip to content

Commit 6a48ad8

Browse files
author
tobias.neumann
committed
2 parents 444b9cf + 144f8d7 commit 6a48ad8

1 file changed

Lines changed: 217 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# 🧬 GenomicOps-MCP
2+
3+
**GenomicOps-MCP** is a dual-mode Python server that exposes genomic feature operations via:
4+
- 🧠 **Model Context Protocol (MCP)** — for integration with Claude Desktop and other AI clients.
5+
- 🌐 **FastAPI REST API** — for human-readable, local testing and web interaction.
6+
7+
It currently provides tools to query **UCSC genome browser tracks**, including feature overlaps and assembly listings.
8+
9+
---
10+
11+
## 🚀 Features
12+
13+
- **MCP integration:** Claude Desktop and other MCP-compatible LLM clients can call tools like `get_overlapping_features`.
14+
- **FastAPI web API:** Test and debug the same logic locally in a browser or via `curl`.
15+
- **Unified backend:** One codebase (`src/server/mcp_server.py`) supports both modes.
16+
- **FastMCP-powered:** Built with [FastMCP](https://gofastmcp.com) for standard-compliant and rapid MCP development.
17+
18+
---
19+
20+
## 📁 Project Structure
21+
22+
```
23+
GenomicOps-MCP/
24+
├── src/
25+
│ └── server/
26+
│ ├── mcp_server.py # Main MCP + FastAPI server
27+
│ └── tools.py # UCSC tools and helper functions
28+
├── pyproject.toml # Managed by uv (Python project metadata)
29+
├── uv.lock # uv dependency lockfile
30+
├── .gitignore
31+
└── README.md
32+
```
33+
34+
---
35+
36+
## 🧩 Installation
37+
38+
### 1️⃣ Prerequisites
39+
40+
- **Python ≥ 3.11**
41+
- **uv** (recommended for managing virtual environments and dependencies)
42+
43+
Install uv globally (if not already):
44+
45+
```bash
46+
curl -LsSf https://astral.sh/uv/install.sh | sh
47+
```
48+
49+
### 2️⃣ Clone and enter the project
50+
51+
```bash
52+
git clone https://github.com/YOUR_USERNAME/GenomicOps-MCP.git
53+
cd GenomicOps-MCP
54+
```
55+
56+
### 3️⃣ Install dependencies via `uv`
57+
58+
```bash
59+
uv sync
60+
```
61+
62+
This ensures your environment matches the locked versions in `uv.lock`.
63+
64+
---
65+
66+
## 🧠 Running in MCP Mode (for Claude Desktop)
67+
68+
Run the server as an **MCP endpoint**:
69+
70+
```bash
71+
uv run src/server/mcp_server.py
72+
```
73+
74+
This launches the MCP server over **stdio**, ready for a client like Claude Desktop to connect.
75+
76+
You should see something like:
77+
78+
```
79+
────────────────────────────────────────────────────────────────────────────╮
80+
│ │
81+
│ _ __ ___ _____ __ __ _____________ ____ ____ │
82+
│ _ __ ___ .'____/___ ______/ /_/ |/ / ____/ __ \ |___ \ / __ \ │
83+
│ _ __ ___ / /_ / __ `/ ___/ __/ /|_/ / / / /_/ / ___/ / / / / / │
84+
│ _ __ ___ / __/ / /_/ (__ ) /_/ / / / /___/ ____/ / __/_/ /_/ / │
85+
│ _ __ ___ /_/ \____/____/\__/_/ /_/\____/_/ /_____(*)____/ │
86+
│ │
87+
│ │
88+
│ FastMCP 2.0 │
89+
│ │
90+
│ │
91+
│ 🖥️ Server name: ucsc-mcp │
92+
│ 📦 Transport: STDIO │
93+
│ │
94+
│ 🏎️ FastMCP version: 2.12.4 │
95+
│ 🤝 MCP SDK version: 1.16.0 │
96+
│ │
97+
│ 📚 Docs: https://gofastmcp.com │
98+
│ 🚀 Deploy: https://fastmcp.cloud │
99+
│ │
100+
╰────────────────────────────────────────────────────────────────────────────╯
101+
102+
103+
[10/08/25 13:26:00] INFO Starting MCP server 'ucsc-mcp' with transport 'stdio'
104+
```
105+
106+
---
107+
108+
### 🧩 Add to Claude Desktop
109+
110+
To connect this MCP to Claude Desktop:
111+
112+
#### Option 1: Manual Configuration
113+
114+
Add this entry to your `claude_desktop_config.json`:
115+
116+
```json
117+
{
118+
"ucsc-mcp": {
119+
"command": "/Users/tobias.neumann/.local/bin/uv",
120+
"args": [
121+
"run",
122+
"--project",
123+
"/Users/tobias.neumann/dev/GenomicOps-MCP",
124+
"--with",
125+
"fastmcp",
126+
"fastmcp",
127+
"run",
128+
"/Users/tobias.neumann/dev/GenomicOps-MCP/src/server/mcp_server.py"
129+
],
130+
"env": {},
131+
"transport": "stdio",
132+
"type": null,
133+
"cwd": null,
134+
"timeout": null,
135+
"description": null,
136+
"icon": null,
137+
"authentication": null
138+
}
139+
}
140+
```
141+
142+
Then restart Claude Desktop — it should detect `ucsc-mcp` and register the `get_overlapping_features` tool.
143+
144+
#### Option 2: FastMCP CLI (Recommended)
145+
146+
You can install the server directly into Claude Desktop with one command:
147+
148+
```bash
149+
fastmcp install claude-desktop src/server/mcp_server.py \
150+
--python 3.11 \
151+
--project /Users/YOUR_USERNAME/dev/GenomicOps-MCP
152+
```
153+
154+
---
155+
156+
## 🌐 Running in FastAPI Mode (for local testing)
157+
158+
If you want to expose the same functionality as a REST API, use the `api` flag:
159+
160+
```bash
161+
uv run src/server/mcp_server.py api
162+
```
163+
164+
Then open your browser at:
165+
👉 [http://localhost:8000/docs](http://localhost:8000/docs)
166+
167+
You’ll see interactive FastAPI documentation (Swagger UI).
168+
169+
### Example endpoints:
170+
171+
| Method | Endpoint | Description |
172+
|--------|----------------------|--------------|
173+
| `POST` | `/overlaps` | Query overlapping genomic features |
174+
| `GET` | `/assemblies` | List supported genome assemblies |
175+
176+
---
177+
178+
## 🧪 Example Usage (API)
179+
180+
**POST /overlaps**
181+
```bash
182+
curl -X POST http://localhost:8000/overlaps \
183+
-H "Content-Type: application/json" \
184+
-d '{"region": "chr1:1000-2000", "assembly": "hg38"}'
185+
```
186+
187+
**GET /assemblies**
188+
```bash
189+
curl http://localhost:8000/assemblies
190+
```
191+
192+
---
193+
194+
## 🧰 Development Tips
195+
196+
- **Run with uv**
197+
```bash
198+
uv run src/server/mcp_server.py
199+
```
200+
- **Add new tools**
201+
Decorate Python functions with `@mcp.tool()` inside `mcp_server.py`.
202+
- **Debug locally**
203+
Use FastAPI mode (`uv run src/server/mcp_server.py api`) for quick JSON responses.
204+
205+
---
206+
207+
## 📚 References
208+
209+
- [Model Context Protocol Docs](https://modelcontextprotocol.io)
210+
- [FastMCP Documentation](https://gofastmcp.com)
211+
- [Claude Desktop MCP Guide](https://modelcontextprotocol.io/docs/tools/claude)
212+
213+
---
214+
215+
**Author:** Tobias Neumann
216+
**License:** MIT
217+
**Version:** 0.1.0

0 commit comments

Comments
 (0)
⚡