simbiology-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- simbiology_mcp-0.1.0/LICENSE +21 -0
- simbiology_mcp-0.1.0/PKG-INFO +246 -0
- simbiology_mcp-0.1.0/README.md +221 -0
- simbiology_mcp-0.1.0/pyproject.toml +52 -0
- simbiology_mcp-0.1.0/setup.cfg +4 -0
- simbiology_mcp-0.1.0/simbiology_mcp/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/__main__.py +9 -0
- simbiology_mcp-0.1.0/simbiology_mcp/core/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/core/sbio_model.py +591 -0
- simbiology_mcp-0.1.0/simbiology_mcp/core/sbio_service.py +173 -0
- simbiology_mcp-0.1.0/simbiology_mcp/engine/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/engine/exceptions.py +43 -0
- simbiology_mcp-0.1.0/simbiology_mcp/engine/matlab_layer.py +109 -0
- simbiology_mcp-0.1.0/simbiology_mcp/external/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/external/igem.py +176 -0
- simbiology_mcp-0.1.0/simbiology_mcp/external/pubmed.py +98 -0
- simbiology_mcp-0.1.0/simbiology_mcp/interfaces/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/interfaces/cli.py +139 -0
- simbiology_mcp-0.1.0/simbiology_mcp/interfaces/mcp_server.py +32 -0
- simbiology_mcp-0.1.0/simbiology_mcp/scripts/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/scripts/configure_mcp.py +624 -0
- simbiology_mcp-0.1.0/simbiology_mcp/scripts/get_skill.py +254 -0
- simbiology_mcp-0.1.0/simbiology_mcp/scripts/setup.py +167 -0
- simbiology_mcp-0.1.0/simbiology_mcp/scripts/tui.py +116 -0
- simbiology_mcp-0.1.0/simbiology_mcp/skills/SKILL.md +253 -0
- simbiology_mcp-0.1.0/simbiology_mcp/skills/__init__.py +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp/tools/__init__.py +6 -0
- simbiology_mcp-0.1.0/simbiology_mcp/tools/analysis_tools.py +98 -0
- simbiology_mcp-0.1.0/simbiology_mcp/tools/external_tools.py +44 -0
- simbiology_mcp-0.1.0/simbiology_mcp/tools/registry.py +16 -0
- simbiology_mcp-0.1.0/simbiology_mcp/tools/sbio_tools.py +636 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/PKG-INFO +246 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/SOURCES.txt +35 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/dependency_links.txt +1 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/entry_points.txt +2 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/requires.txt +12 -0
- simbiology_mcp-0.1.0/simbiology_mcp.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Yojith Sai Biradavolu and Sepanta Yalameha
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: simbiology-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Model Context Protocol server for MATLAB SimBiology: build, modify, simulate, and export systems-biology models from AI agents.
|
|
5
|
+
Author-email: Yojith Sai Biradavolu <yojith23@gmail.com>, Sepanta Yalameha <sepantayalameha2006@gmail.com>
|
|
6
|
+
Project-URL: Repository, https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP
|
|
7
|
+
Project-URL: Issues, https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Releases, https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/releases
|
|
10
|
+
Keywords: mcp,simbiology,matlab,systems-biology,pk-pd,modeling
|
|
11
|
+
Requires-Python: >=3.12
|
|
12
|
+
Description-Content-Type: text/markdown
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Requires-Dist: fastmcp<4,>=3.4
|
|
15
|
+
Requires-Dist: httpx>=0.28
|
|
16
|
+
Requires-Dist: python-dotenv>=1.2
|
|
17
|
+
Requires-Dist: igem-registry-api>=0.1
|
|
18
|
+
Requires-Dist: tomlkit>=0.13
|
|
19
|
+
Provides-Extra: dev
|
|
20
|
+
Requires-Dist: coverage>=7; extra == "dev"
|
|
21
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
22
|
+
Provides-Extra: matlab
|
|
23
|
+
Requires-Dist: matlabengine; extra == "matlab"
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
# SimBiology MCP Server
|
|
27
|
+
|
|
28
|
+
[](https://pypi.org/project/simbiology-mcp/)
|
|
29
|
+
[](https://pypi.org/project/simbiology-mcp/)
|
|
30
|
+
[](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml?query=branch%3Amain)
|
|
31
|
+
[](LICENSE)
|
|
32
|
+
[](https://www.mathworks.com/products/matlab.html)
|
|
33
|
+
[](#requirements)
|
|
34
|
+
|
|
35
|
+
## Overview
|
|
36
|
+
|
|
37
|
+
The SimBiology MCP Server is a Model Context Protocol (MCP) interface for MATLAB SimBiology, enabling programmatic control of biological modeling and simulation workflows from AI agents and external tools.
|
|
38
|
+
|
|
39
|
+
It bridges large language model systems with MATLAB's SimBiology toolbox through the MATLAB Engine for Python, allowing automated creation, modification, and execution of computational biology models.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## Purpose
|
|
44
|
+
|
|
45
|
+
SimBiology is a powerful environment for modeling biochemical and pharmacokinetic systems, but it is primarily MATLAB-driven and interactive.
|
|
46
|
+
|
|
47
|
+
This MCP server provides a structured programmatic layer that:
|
|
48
|
+
|
|
49
|
+
- Exposes SimBiology functionality as MCP tools
|
|
50
|
+
- Enables automated model construction and simulation
|
|
51
|
+
- Supports agent-driven workflows for systems biology
|
|
52
|
+
- Removes the need for manual MATLAB interaction
|
|
53
|
+
- Supports workflows such as building PK/PD models, modifying reactions and parameters, simulating time courses, exporting results, and pulling supporting context from PubMed and iGEM
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
Choose one way to install the Python package, then complete the common setup steps below.
|
|
60
|
+
|
|
61
|
+
### 1. Manual repo checkout
|
|
62
|
+
|
|
63
|
+
Use this when you want the full source tree locally, including the repo skill files and tests.
|
|
64
|
+
|
|
65
|
+
```shell
|
|
66
|
+
git clone https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP.git
|
|
67
|
+
cd SIMBIOLOGY-MCP
|
|
68
|
+
python -m venv .venv
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Activate the virtual environment:
|
|
72
|
+
|
|
73
|
+
```powershell
|
|
74
|
+
# Windows PowerShell
|
|
75
|
+
.\.venv\Scripts\Activate.ps1
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```shell
|
|
79
|
+
# macOS or Linux
|
|
80
|
+
source .venv/bin/activate
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```shell
|
|
84
|
+
python -m pip install -e .
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### 2. Recommended: `uv tool install`
|
|
88
|
+
|
|
89
|
+
Use this when you want a cleaner install without cloning the repo.
|
|
90
|
+
|
|
91
|
+
```powershell
|
|
92
|
+
uv tool install simbiology-mcp
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 3. Plain `pip`
|
|
96
|
+
|
|
97
|
+
Use this if you do not want `uv tool install`.
|
|
98
|
+
|
|
99
|
+
```powershell
|
|
100
|
+
python -m pip install simbiology-mcp
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Complete the setup
|
|
104
|
+
|
|
105
|
+
The easiest option is the interactive setup. It installs the MATLAB Engine, configures an MCP client, and offers to install the matching skill:
|
|
106
|
+
|
|
107
|
+
```powershell
|
|
108
|
+
simbiology-mcp setup
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
For a fully interactive setup, follow the prompts to choose your MATLAB installation, client, configuration scope, and skill destination.
|
|
112
|
+
|
|
113
|
+
For headless or engine-only setup, install the MATLAB Engine for Python from your local MATLAB installation:
|
|
114
|
+
|
|
115
|
+
```powershell
|
|
116
|
+
simbiology-mcp setup --skip-configure
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
If multiple MATLAB installations are found, select one interactively or pass an index:
|
|
120
|
+
|
|
121
|
+
```powershell
|
|
122
|
+
simbiology-mcp setup --matlab-index 0 --skip-configure
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Configure an MCP client:
|
|
126
|
+
|
|
127
|
+
```powershell
|
|
128
|
+
simbiology-mcp configure --client cursor
|
|
129
|
+
simbiology-mcp configure --client codex --project
|
|
130
|
+
simbiology-mcp configure --list-clients
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
The configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot. The user scope is the default; use `--project` for project-local configuration. Existing matching entries are left unchanged; use `--force` to replace a different existing entry.
|
|
134
|
+
|
|
135
|
+
Install the synthetic biology modelling skill separately:
|
|
136
|
+
|
|
137
|
+
```powershell
|
|
138
|
+
simbiology-mcp get-skill --client codex
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Use `--client`, `--project`, `--user`, or `--install-path` to choose a destination directly. Run `simbiology-mcp get-skill` without flags for the interactive picker.
|
|
142
|
+
|
|
143
|
+
Add `--no-skill` to omit the skill installation.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Requirements
|
|
148
|
+
|
|
149
|
+
- MATLAB R2024a or later
|
|
150
|
+
- SimBiology Toolbox installed
|
|
151
|
+
- Python 3.12 or later
|
|
152
|
+
- A MATLAB-supported Windows, macOS, or Linux environment
|
|
153
|
+
- An MCP-compatible client; the configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Usage
|
|
158
|
+
|
|
159
|
+
Once setup has configured the MCP server for your chosen agent, launch or restart that agent's client session. The client starts the server automatically when it connects to it; you do not need to run `start` manually.
|
|
160
|
+
|
|
161
|
+
### Manual configuration and server start
|
|
162
|
+
|
|
163
|
+
Use manual configuration only when your client is not supported by `configure`:
|
|
164
|
+
|
|
165
|
+
Point your MCP client at the installed server executable. Use the absolute path so the client does not depend on your shell's `PATH`:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{
|
|
169
|
+
"mcpServers": {
|
|
170
|
+
"simbiology": {
|
|
171
|
+
"command": "C:/absolute/path/to/simbiology-mcp.exe",
|
|
172
|
+
"args": ["start"]
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Alternatively, run the server directly from an activated repository environment:
|
|
179
|
+
|
|
180
|
+
```powershell
|
|
181
|
+
python -m simbiology_mcp start
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The MATLAB engine starts lazily on the first tool call that needs it, so client startup stays fast.
|
|
185
|
+
|
|
186
|
+
### External API keys
|
|
187
|
+
|
|
188
|
+
PubMed works without a key but is rate-limited. To raise the limit, copy `.env.example` to `.env` and set `NCBI_API_KEY`.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Tools
|
|
193
|
+
|
|
194
|
+
The server exposes the following MCP tools:
|
|
195
|
+
|
|
196
|
+
| Tool name | Description | Inputs | Outputs |
|
|
197
|
+
| --- | --- | --- | --- |
|
|
198
|
+
| `load_project`, `create_project`, `save_project` | Load, create, and persist SimBiology projects. | Project path, model name, save target. | Confirmation plus project/model metadata. |
|
|
199
|
+
| `create_model`, `rename_model`, `remove_model`, `list_models` | Manage models inside the loaded project. | Model name or rename target. | Confirmation or model name lists. |
|
|
200
|
+
| `create_compartment`, `modify_compartment`, `remove_compartment`, `list_compartments` | Manage compartments. | Names plus compartment properties such as capacity and units. | Confirmation or compartment data. |
|
|
201
|
+
| `create_species`, `modify_species`, `remove_species`, `list_species` | Manage species. | Names plus species properties such as initial amount and units. | Confirmation or species data. |
|
|
202
|
+
| `create_reaction`, `modify_reaction`, `remove_reaction`, `list_reactions` | Manage reactions and rate expressions. | Reactants, products, reversibility, rate law fields. | Confirmation or reaction data. |
|
|
203
|
+
| `create_parameter`, `modify_parameter`, `remove_parameter`, `list_parameters` | Manage model parameters. | Names, values, units, and scope. | Confirmation or parameter data. |
|
|
204
|
+
| `get_simulation_settings`, `configure_simulation`, `simulate_model` | Inspect, configure, and run simulations. | Solver/settings fields, optional `species`, `doses`, `variants`, and output limits. | Current settings or simulation result rows. |
|
|
205
|
+
| `create_dose`, `modify_dose`, `remove_dose`, `list_doses` | Manage repeat and schedule doses. | Dose type, target, timing, amount/rate fields. Dose amounts use amount/mass units; dose rates use amount/time or mass/time units. | Confirmation or dose data. |
|
|
206
|
+
| `create_variant`, `modify_variant`, `remove_variant`, `list_variants` | Manage named model overrides. | Variant name and full content entries. | Confirmation or variant data. |
|
|
207
|
+
| `export_graph`, `export_csv` | Export the same run used by `simulate_model` to PNG or CSV. | Optional path plus optional `species`, `doses`, and `variants`. | File metadata or inline CSV text. |
|
|
208
|
+
| `list_series`, `steady_state`, `series_min`, `series_max` | Analyze exported CSV data without rerunning MATLAB. | CSV path and target series name. | Series names or computed values. |
|
|
209
|
+
| `pubmed_search`, `pubmed_summary`, `pubmed_article` | Pull literature context from PubMed. | Query, PubMed ID, and summary options. | Search hits, article details, or summaries. |
|
|
210
|
+
| `igem_part`, `igem_search`, `igem_search_best` | Look up parts from the iGEM registry. | Exact identifier or free-text query. | Part records or ranked matches. |
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Project layout
|
|
215
|
+
|
|
216
|
+
```text
|
|
217
|
+
simbiology_mcp/
|
|
218
|
+
├── core/ SimBiology session, per-model reads, and command builders
|
|
219
|
+
├── engine/ Singleton MATLAB engine wrapper and error types
|
|
220
|
+
├── tools/ MCP tool definitions and the shared registry
|
|
221
|
+
├── external/ PubMed and iGEM API wrappers
|
|
222
|
+
├── interfaces/ FastMCP server wiring
|
|
223
|
+
├── scripts/ CLI helpers like setup, configure, and get-skill
|
|
224
|
+
└── skills/ Packaged skill markdown
|
|
225
|
+
examples/ Runnable demos (e.g. demo_simulation.py)
|
|
226
|
+
tests/ Unit tests plus MATLAB/live integration tests
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
## Authors
|
|
230
|
+
|
|
231
|
+
- [Yojith Sai Biradavolu](https://github.com/yojith)
|
|
232
|
+
- [Sepanta Yalameha](https://github.com/Sepanta-Yalameha)
|
|
233
|
+
|
|
234
|
+
Contributions, issues, and feature requests are welcome through the project’s [GitHub repository](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP).
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## Development
|
|
239
|
+
|
|
240
|
+
Run the hermetic test suite (no MATLAB or network required):
|
|
241
|
+
|
|
242
|
+
```powershell
|
|
243
|
+
py -m pytest -m "not matlab and not live"
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
`matlab` tests require a working MATLAB Engine install. `live` tests hit external APIs and run only with `--run-live`.
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# SimBiology MCP Server
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/simbiology-mcp/)
|
|
4
|
+
[](https://pypi.org/project/simbiology-mcp/)
|
|
5
|
+
[](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml?query=branch%3Amain)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://www.mathworks.com/products/matlab.html)
|
|
8
|
+
[](#requirements)
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
The SimBiology MCP Server is a Model Context Protocol (MCP) interface for MATLAB SimBiology, enabling programmatic control of biological modeling and simulation workflows from AI agents and external tools.
|
|
13
|
+
|
|
14
|
+
It bridges large language model systems with MATLAB's SimBiology toolbox through the MATLAB Engine for Python, allowing automated creation, modification, and execution of computational biology models.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Purpose
|
|
19
|
+
|
|
20
|
+
SimBiology is a powerful environment for modeling biochemical and pharmacokinetic systems, but it is primarily MATLAB-driven and interactive.
|
|
21
|
+
|
|
22
|
+
This MCP server provides a structured programmatic layer that:
|
|
23
|
+
|
|
24
|
+
- Exposes SimBiology functionality as MCP tools
|
|
25
|
+
- Enables automated model construction and simulation
|
|
26
|
+
- Supports agent-driven workflows for systems biology
|
|
27
|
+
- Removes the need for manual MATLAB interaction
|
|
28
|
+
- Supports workflows such as building PK/PD models, modifying reactions and parameters, simulating time courses, exporting results, and pulling supporting context from PubMed and iGEM
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
Choose one way to install the Python package, then complete the common setup steps below.
|
|
35
|
+
|
|
36
|
+
### 1. Manual repo checkout
|
|
37
|
+
|
|
38
|
+
Use this when you want the full source tree locally, including the repo skill files and tests.
|
|
39
|
+
|
|
40
|
+
```shell
|
|
41
|
+
git clone https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP.git
|
|
42
|
+
cd SIMBIOLOGY-MCP
|
|
43
|
+
python -m venv .venv
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Activate the virtual environment:
|
|
47
|
+
|
|
48
|
+
```powershell
|
|
49
|
+
# Windows PowerShell
|
|
50
|
+
.\.venv\Scripts\Activate.ps1
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
```shell
|
|
54
|
+
# macOS or Linux
|
|
55
|
+
source .venv/bin/activate
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```shell
|
|
59
|
+
python -m pip install -e .
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### 2. Recommended: `uv tool install`
|
|
63
|
+
|
|
64
|
+
Use this when you want a cleaner install without cloning the repo.
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
uv tool install simbiology-mcp
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### 3. Plain `pip`
|
|
71
|
+
|
|
72
|
+
Use this if you do not want `uv tool install`.
|
|
73
|
+
|
|
74
|
+
```powershell
|
|
75
|
+
python -m pip install simbiology-mcp
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## Complete the setup
|
|
79
|
+
|
|
80
|
+
The easiest option is the interactive setup. It installs the MATLAB Engine, configures an MCP client, and offers to install the matching skill:
|
|
81
|
+
|
|
82
|
+
```powershell
|
|
83
|
+
simbiology-mcp setup
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
For a fully interactive setup, follow the prompts to choose your MATLAB installation, client, configuration scope, and skill destination.
|
|
87
|
+
|
|
88
|
+
For headless or engine-only setup, install the MATLAB Engine for Python from your local MATLAB installation:
|
|
89
|
+
|
|
90
|
+
```powershell
|
|
91
|
+
simbiology-mcp setup --skip-configure
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
If multiple MATLAB installations are found, select one interactively or pass an index:
|
|
95
|
+
|
|
96
|
+
```powershell
|
|
97
|
+
simbiology-mcp setup --matlab-index 0 --skip-configure
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Configure an MCP client:
|
|
101
|
+
|
|
102
|
+
```powershell
|
|
103
|
+
simbiology-mcp configure --client cursor
|
|
104
|
+
simbiology-mcp configure --client codex --project
|
|
105
|
+
simbiology-mcp configure --list-clients
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot. The user scope is the default; use `--project` for project-local configuration. Existing matching entries are left unchanged; use `--force` to replace a different existing entry.
|
|
109
|
+
|
|
110
|
+
Install the synthetic biology modelling skill separately:
|
|
111
|
+
|
|
112
|
+
```powershell
|
|
113
|
+
simbiology-mcp get-skill --client codex
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Use `--client`, `--project`, `--user`, or `--install-path` to choose a destination directly. Run `simbiology-mcp get-skill` without flags for the interactive picker.
|
|
117
|
+
|
|
118
|
+
Add `--no-skill` to omit the skill installation.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## Requirements
|
|
123
|
+
|
|
124
|
+
- MATLAB R2024a or later
|
|
125
|
+
- SimBiology Toolbox installed
|
|
126
|
+
- Python 3.12 or later
|
|
127
|
+
- A MATLAB-supported Windows, macOS, or Linux environment
|
|
128
|
+
- An MCP-compatible client; the configuration helper supports Claude Code, Cursor, Codex, Windsurf, GitHub Copilot CLI, and Visual Studio Code/GitHub Copilot
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Usage
|
|
133
|
+
|
|
134
|
+
Once setup has configured the MCP server for your chosen agent, launch or restart that agent's client session. The client starts the server automatically when it connects to it; you do not need to run `start` manually.
|
|
135
|
+
|
|
136
|
+
### Manual configuration and server start
|
|
137
|
+
|
|
138
|
+
Use manual configuration only when your client is not supported by `configure`:
|
|
139
|
+
|
|
140
|
+
Point your MCP client at the installed server executable. Use the absolute path so the client does not depend on your shell's `PATH`:
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"mcpServers": {
|
|
145
|
+
"simbiology": {
|
|
146
|
+
"command": "C:/absolute/path/to/simbiology-mcp.exe",
|
|
147
|
+
"args": ["start"]
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Alternatively, run the server directly from an activated repository environment:
|
|
154
|
+
|
|
155
|
+
```powershell
|
|
156
|
+
python -m simbiology_mcp start
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The MATLAB engine starts lazily on the first tool call that needs it, so client startup stays fast.
|
|
160
|
+
|
|
161
|
+
### External API keys
|
|
162
|
+
|
|
163
|
+
PubMed works without a key but is rate-limited. To raise the limit, copy `.env.example` to `.env` and set `NCBI_API_KEY`.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Tools
|
|
168
|
+
|
|
169
|
+
The server exposes the following MCP tools:
|
|
170
|
+
|
|
171
|
+
| Tool name | Description | Inputs | Outputs |
|
|
172
|
+
| --- | --- | --- | --- |
|
|
173
|
+
| `load_project`, `create_project`, `save_project` | Load, create, and persist SimBiology projects. | Project path, model name, save target. | Confirmation plus project/model metadata. |
|
|
174
|
+
| `create_model`, `rename_model`, `remove_model`, `list_models` | Manage models inside the loaded project. | Model name or rename target. | Confirmation or model name lists. |
|
|
175
|
+
| `create_compartment`, `modify_compartment`, `remove_compartment`, `list_compartments` | Manage compartments. | Names plus compartment properties such as capacity and units. | Confirmation or compartment data. |
|
|
176
|
+
| `create_species`, `modify_species`, `remove_species`, `list_species` | Manage species. | Names plus species properties such as initial amount and units. | Confirmation or species data. |
|
|
177
|
+
| `create_reaction`, `modify_reaction`, `remove_reaction`, `list_reactions` | Manage reactions and rate expressions. | Reactants, products, reversibility, rate law fields. | Confirmation or reaction data. |
|
|
178
|
+
| `create_parameter`, `modify_parameter`, `remove_parameter`, `list_parameters` | Manage model parameters. | Names, values, units, and scope. | Confirmation or parameter data. |
|
|
179
|
+
| `get_simulation_settings`, `configure_simulation`, `simulate_model` | Inspect, configure, and run simulations. | Solver/settings fields, optional `species`, `doses`, `variants`, and output limits. | Current settings or simulation result rows. |
|
|
180
|
+
| `create_dose`, `modify_dose`, `remove_dose`, `list_doses` | Manage repeat and schedule doses. | Dose type, target, timing, amount/rate fields. Dose amounts use amount/mass units; dose rates use amount/time or mass/time units. | Confirmation or dose data. |
|
|
181
|
+
| `create_variant`, `modify_variant`, `remove_variant`, `list_variants` | Manage named model overrides. | Variant name and full content entries. | Confirmation or variant data. |
|
|
182
|
+
| `export_graph`, `export_csv` | Export the same run used by `simulate_model` to PNG or CSV. | Optional path plus optional `species`, `doses`, and `variants`. | File metadata or inline CSV text. |
|
|
183
|
+
| `list_series`, `steady_state`, `series_min`, `series_max` | Analyze exported CSV data without rerunning MATLAB. | CSV path and target series name. | Series names or computed values. |
|
|
184
|
+
| `pubmed_search`, `pubmed_summary`, `pubmed_article` | Pull literature context from PubMed. | Query, PubMed ID, and summary options. | Search hits, article details, or summaries. |
|
|
185
|
+
| `igem_part`, `igem_search`, `igem_search_best` | Look up parts from the iGEM registry. | Exact identifier or free-text query. | Part records or ranked matches. |
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Project layout
|
|
190
|
+
|
|
191
|
+
```text
|
|
192
|
+
simbiology_mcp/
|
|
193
|
+
├── core/ SimBiology session, per-model reads, and command builders
|
|
194
|
+
├── engine/ Singleton MATLAB engine wrapper and error types
|
|
195
|
+
├── tools/ MCP tool definitions and the shared registry
|
|
196
|
+
├── external/ PubMed and iGEM API wrappers
|
|
197
|
+
├── interfaces/ FastMCP server wiring
|
|
198
|
+
├── scripts/ CLI helpers like setup, configure, and get-skill
|
|
199
|
+
└── skills/ Packaged skill markdown
|
|
200
|
+
examples/ Runnable demos (e.g. demo_simulation.py)
|
|
201
|
+
tests/ Unit tests plus MATLAB/live integration tests
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Authors
|
|
205
|
+
|
|
206
|
+
- [Yojith Sai Biradavolu](https://github.com/yojith)
|
|
207
|
+
- [Sepanta Yalameha](https://github.com/Sepanta-Yalameha)
|
|
208
|
+
|
|
209
|
+
Contributions, issues, and feature requests are welcome through the project’s [GitHub repository](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP).
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## Development
|
|
214
|
+
|
|
215
|
+
Run the hermetic test suite (no MATLAB or network required):
|
|
216
|
+
|
|
217
|
+
```powershell
|
|
218
|
+
py -m pytest -m "not matlab and not live"
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
`matlab` tests require a working MATLAB Engine install. `live` tests hit external APIs and run only with `--run-live`.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "simbiology-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Model Context Protocol server for MATLAB SimBiology: build, modify, simulate, and export systems-biology models from AI agents."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.12"
|
|
11
|
+
authors = [{ name = "Yojith Sai Biradavolu", email = "yojith23@gmail.com" },
|
|
12
|
+
{ name = "Sepanta Yalameha", email = "sepantayalameha2006@gmail.com" }]
|
|
13
|
+
keywords = ["mcp", "simbiology", "matlab", "systems-biology", "pk-pd", "modeling"]
|
|
14
|
+
|
|
15
|
+
# Direct runtime dependencies only. The fully pinned transitive closure lives in
|
|
16
|
+
# uv.lock.
|
|
17
|
+
dependencies = [
|
|
18
|
+
"fastmcp>=3.4,<4",
|
|
19
|
+
"httpx>=0.28",
|
|
20
|
+
"python-dotenv>=1.2",
|
|
21
|
+
"igem-registry-api>=0.1",
|
|
22
|
+
"tomlkit>=0.13",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
[project.urls]
|
|
26
|
+
Repository = "https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP"
|
|
27
|
+
Issues = "https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/issues"
|
|
28
|
+
Changelog = "https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/blob/main/CHANGELOG.md"
|
|
29
|
+
Releases = "https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/releases"
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = ["coverage>=7", "pytest>=8"]
|
|
33
|
+
# The `matlab` extra pulls `matlabengine` from PyPI, whose version must match the
|
|
34
|
+
# installed MATLAB release. simbiology_mcp/scripts/setup.py installs it straight
|
|
35
|
+
# from the local MATLAB installation instead; prefer that unless the PyPI version matches.
|
|
36
|
+
matlab = ["matlabengine"]
|
|
37
|
+
|
|
38
|
+
[project.scripts]
|
|
39
|
+
simbiology-mcp = "simbiology_mcp.interfaces.cli:main"
|
|
40
|
+
|
|
41
|
+
[tool.setuptools.packages.find]
|
|
42
|
+
include = ["simbiology_mcp*"]
|
|
43
|
+
|
|
44
|
+
[tool.setuptools.package-data]
|
|
45
|
+
"simbiology_mcp.skills" = ["SKILL.md"]
|
|
46
|
+
|
|
47
|
+
[tool.coverage.run]
|
|
48
|
+
source = ["simbiology_mcp"]
|
|
49
|
+
|
|
50
|
+
[tool.black]
|
|
51
|
+
line-length = 200
|
|
52
|
+
target-version = ["py312"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""SimBiology MCP package."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Core SimBiology session and model logic."""
|