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.
Files changed (37) hide show
  1. simbiology_mcp-0.1.0/LICENSE +21 -0
  2. simbiology_mcp-0.1.0/PKG-INFO +246 -0
  3. simbiology_mcp-0.1.0/README.md +221 -0
  4. simbiology_mcp-0.1.0/pyproject.toml +52 -0
  5. simbiology_mcp-0.1.0/setup.cfg +4 -0
  6. simbiology_mcp-0.1.0/simbiology_mcp/__init__.py +1 -0
  7. simbiology_mcp-0.1.0/simbiology_mcp/__main__.py +9 -0
  8. simbiology_mcp-0.1.0/simbiology_mcp/core/__init__.py +1 -0
  9. simbiology_mcp-0.1.0/simbiology_mcp/core/sbio_model.py +591 -0
  10. simbiology_mcp-0.1.0/simbiology_mcp/core/sbio_service.py +173 -0
  11. simbiology_mcp-0.1.0/simbiology_mcp/engine/__init__.py +1 -0
  12. simbiology_mcp-0.1.0/simbiology_mcp/engine/exceptions.py +43 -0
  13. simbiology_mcp-0.1.0/simbiology_mcp/engine/matlab_layer.py +109 -0
  14. simbiology_mcp-0.1.0/simbiology_mcp/external/__init__.py +1 -0
  15. simbiology_mcp-0.1.0/simbiology_mcp/external/igem.py +176 -0
  16. simbiology_mcp-0.1.0/simbiology_mcp/external/pubmed.py +98 -0
  17. simbiology_mcp-0.1.0/simbiology_mcp/interfaces/__init__.py +1 -0
  18. simbiology_mcp-0.1.0/simbiology_mcp/interfaces/cli.py +139 -0
  19. simbiology_mcp-0.1.0/simbiology_mcp/interfaces/mcp_server.py +32 -0
  20. simbiology_mcp-0.1.0/simbiology_mcp/scripts/__init__.py +1 -0
  21. simbiology_mcp-0.1.0/simbiology_mcp/scripts/configure_mcp.py +624 -0
  22. simbiology_mcp-0.1.0/simbiology_mcp/scripts/get_skill.py +254 -0
  23. simbiology_mcp-0.1.0/simbiology_mcp/scripts/setup.py +167 -0
  24. simbiology_mcp-0.1.0/simbiology_mcp/scripts/tui.py +116 -0
  25. simbiology_mcp-0.1.0/simbiology_mcp/skills/SKILL.md +253 -0
  26. simbiology_mcp-0.1.0/simbiology_mcp/skills/__init__.py +1 -0
  27. simbiology_mcp-0.1.0/simbiology_mcp/tools/__init__.py +6 -0
  28. simbiology_mcp-0.1.0/simbiology_mcp/tools/analysis_tools.py +98 -0
  29. simbiology_mcp-0.1.0/simbiology_mcp/tools/external_tools.py +44 -0
  30. simbiology_mcp-0.1.0/simbiology_mcp/tools/registry.py +16 -0
  31. simbiology_mcp-0.1.0/simbiology_mcp/tools/sbio_tools.py +636 -0
  32. simbiology_mcp-0.1.0/simbiology_mcp.egg-info/PKG-INFO +246 -0
  33. simbiology_mcp-0.1.0/simbiology_mcp.egg-info/SOURCES.txt +35 -0
  34. simbiology_mcp-0.1.0/simbiology_mcp.egg-info/dependency_links.txt +1 -0
  35. simbiology_mcp-0.1.0/simbiology_mcp.egg-info/entry_points.txt +2 -0
  36. simbiology_mcp-0.1.0/simbiology_mcp.egg-info/requires.txt +12 -0
  37. 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
+ [![PyPI](https://img.shields.io/pypi/v/simbiology-mcp?logo=pypi\&logoColor=white)](https://pypi.org/project/simbiology-mcp/)
29
+ [![Python](https://img.shields.io/pypi/pyversions/simbiology-mcp?logo=python\&logoColor=white)](https://pypi.org/project/simbiology-mcp/)
30
+ [![Tests](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml?query=branch%3Amain)
31
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
32
+ [![MATLAB](https://img.shields.io/badge/MATLAB-R2024a%2B-orange)](https://www.mathworks.com/products/matlab.html)
33
+ [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](#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
+ [![PyPI](https://img.shields.io/pypi/v/simbiology-mcp?logo=pypi\&logoColor=white)](https://pypi.org/project/simbiology-mcp/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/simbiology-mcp?logo=python\&logoColor=white)](https://pypi.org/project/simbiology-mcp/)
5
+ [![Tests](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/Sepanta-Yalameha/SIMBIOLOGY-MCP/actions/workflows/test.yml?query=branch%3Amain)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
+ [![MATLAB](https://img.shields.io/badge/MATLAB-R2024a%2B-orange)](https://www.mathworks.com/products/matlab.html)
8
+ [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)](#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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1 @@
1
+ """SimBiology MCP package."""
@@ -0,0 +1,9 @@
1
+ """Module entry point for `python -m simbiology_mcp`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from .interfaces.cli import main
6
+
7
+
8
+ if __name__ == "__main__":
9
+ main()
@@ -0,0 +1 @@
1
+ """Core SimBiology session and model logic."""