Stella MCP Server

Stella MCP服务器

A. 模型上下文协议（MCP） 用于创建和操作的服务器 斯特拉 系统动力学模型。这使得像Claude这样的人工智能助手能够以编程方式构建、读取、验证和保存 .stmx XMILE格式的文件。

这是干什么用的？

斯特拉 是一种系统动力学建模工具，用于模拟生态学、生物地球化学、经济学和工程学等领域的复杂系统。此MCP服务器允许AI助手：

• 从头开始创建模型 -以编程方式构建库存和流程图
• 阅读现有模型 -解析和理解.stmx文件
• 验证模型 -检查是否存在未定义变量或缺少连接等错误
• 修改模型 -添加库存、流量、辅助设备和连接器
• 保存模型 -导出在Stella Professional中打开的有效XMILE文件

这对于以下情况特别有用：

• 教学系统动力学建模
• 通过自然语言快速制作模型原型
• 批量创建或修改模型
• 记录和解释现有模型

安装

来自PyPI

pip install stella-mcp

来源

git clone https://github.com/bradleylab/stella-mcp.git
cd stella-mcp
pip install -e .

需求

• Python 3.10+
• mcp>=1.0.0

配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "stella": {
      "command": "stella-mcp"
    }
  }
}

克劳德代码

添加到您的 .claude/settings.json:

{
  "mcpServers": {
    "stella": {
      "command": "stella-mcp"
    }
  }
}

开发模式

如果从源代码运行：

{
  "mcpServers": {
    "stella": {
      "command": "python",
      "args": ["-m", "stella_mcp.server"],
      "cwd": "/path/to/stella-mcp"
    }
  }
}

可用工具

模型创建和I/O

模板

模型构建

笔记：

• 工具接受可选 model_id 因此一个MCP会话可以安全地管理多个模型。
• create_model 和 read_model 设置会话的当前 model_id 并将其归还。
• add_flow 和 add_aux 支持可选 graphical_function 有效载荷(ypts 加上恰好一个 xscale 或 xpts).
• add_stock/add_flow/add_aux 拒绝跨变量类型的重复变量名； add_connector 要求这两个变量都存在。
• set_connector_routing 可以通过以下方式定位连接器 connector_uid 或通过 from_var + to_var.
• save_model 和 get_model_xml 接受 auto_layout （默认值 true)以及 resolve_layout_violations （默认值 false).
• read_model, save_model，以及 get_model_xml 接受 compat_mode:

- permissive （默认）：继续警告 - strict：兼容性问题失败

• set_module_style 更新模块视图样式并在XMILE视图中保留这些属性 `` 元素。
• save_as_template 将用户模板写入 ~/.stella-mcp/templates 默认情况下（通过覆盖 STELLA_MCP_TEMPLATE_DIR)并将元数据存储在 .meta.json 侧三轮。
• 工具故障返回结构化MCP错误 error.code, error.category，以及 error.message.

模型检查

工具有效载荷示例

创建会话模型并在会话模型之间切换：

{"name":"create_model","arguments":{"name":"Population","model_id":"pop_v1"}}

{"name":"create_model","arguments":{"name":"Carbon","model_id":"carbon_v1"}}

{"name":"list_models","arguments":{}}

列出并加载模板：

{"name":"list_templates","arguments":{}}

{"name":"list_templates","arguments":{"source":"builtin","query":"epidem","tags":["epidemiology"]}}

{"name":"get_template_info","arguments":{"template_name":"sir"}}

{"name":"load_template","arguments":{"template_name":"sir","model_id":"sir_baseline"}}

将当前模型另存为用户模板：

{"name":"save_as_template","arguments":{"model_id":"pop_v1","template_name":"my_population_template","description":"Baseline single-stock growth starter","tags":["intro","population"]}}

创建和管理模块：

{"name":"create_module","arguments":{"model_id":"sir_baseline","name":"Disease Dynamics","members":["Susceptible","Infected","Recovered"]}}

{"name":"add_to_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","members":["infection","recovery"]}}

{"name":"list_modules","arguments":{"model_id":"sir_baseline"}}

{"name":"remove_from_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","members":["recovery"]}}

{"name":"rename_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","new_name":"Disease Core"}}

{"name":"delete_module","arguments":{"model_id":"sir_baseline","module_name":"Disease Core"}}

安全地重命名和删除变量：

{"name":"rename_variable","arguments":{"model_id":"sir_baseline","old_name":"population_total","new_name":"total_population"}}

{"name":"delete_variable","arguments":{"model_id":"sir_baseline","name":"recovery"}}

{"name":"delete_variable","arguments":{"model_id":"sir_baseline","name":"Susceptible","force":true}}

直接设置模块视图几何图形：

{"name":"set_module_view","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","x":420,"y":280,"width":420,"height":240}}

设置模块视图样式：

{"name":"set_module_style","arguments":{"model_id":"sir_baseline","module_name":"Disease Dynamics","border_color":"#666666","background":"#FFF7E6","font_color":"#333333","font_size":"10pt","label_side":"top"}}

从当前成员位置自动放置模块框：

{"name":"auto_place_module_boxes","arguments":{"model_id":"sir_baseline","padding":40,"only_missing":true}}

在以后的调用中针对特定模型：

{"name":"add_stock","arguments":{"model_id":"pop_v1","name":"Population","initial_value":"100"}}

阅读时进行严格的兼容性检查：

{"name":"read_model","arguments":{"filepath":"./external_model.stmx","model_id":"imported","compat_mode":"strict"}}

在允许模式（默认）下预览XML，并在出现兼容性警告时返回：

{"name":"get_model_xml","arguments":{"model_id":"imported","compat_mode":"permissive"}}

有效的图形函数有效载荷：

{
  "name": "add_aux",
  "arguments": {
    "model_id": "pop_v1",
    "name": "lookup_rate",
    "equation": "GRAPH(Time)",
    "graphical_function": {
      "xscale": {"min": 0, "max": 100},
      "ypts": [0.1, 0.2, 0.4, 0.6],
      "type": "continuous"
    }
  }
}

图形函数有效负载无效（被拒绝）：

{
  "name": "add_aux",
  "arguments": {
    "name": "bad_lookup",
    "equation": "GRAPH(Time)",
    "graphical_function": {
      "xscale": {"min": 0, "max": 100},
      "xpts": [0, 10, 20, 30],
      "ypts": [0.1, 0.2, 0.4, 0.6]
    }
  }
}

示例用法

创建一个简单的人口模型

User: Create a simple exponential growth model with a population starting at 100
      and a growth rate of 0.1 per year

Claude: [Uses create_model, add_stock, add_aux, add_flow, add_connector, save_model]
        Creates population_growth.stmx with:
        - Stock: Population (initial=100)
        - Aux: growth_rate (0.1)
        - Flow: growth (Population * growth_rate) into Population

阅读和分析现有模型

User: Read the carbon cycle model and explain what it does

Claude: [Uses read_model, list_variables]
        This model has 3 stocks (Atmosphere, Land Biota, Soil) and 6 flows
        representing carbon exchange through photosynthesis, respiration...

构建生物地球化学模型

User: Create a two-box ocean model with surface and deep nutrients

Claude: [Uses create_model, add_stock (x4), add_aux (x8), add_flow (x6), save_model]
        Creates a model with nutrient cycling between surface and deep ocean
        including upwelling, downwelling, biological uptake, and remineralization

验证

这 validate_model 工具检查：

• 未定义变量 -引用不存在的变量
• 质量平衡问题 -没有流量的库存，流量引用不存在的库存
• 缺少连接 -使用不带连接器的变量的方程（警告）
• 连接器端点完整性 -指向缺失变量的连接器（错误）
• 孤儿流 -与任何股票无关的流量
• 循环依赖 -辅助计算中的无限循环
• 模块完整性 -空模块（警告）和引用缺失成员的模块（错误）

XMILE兼容性

• 输出文件使用 XMILE标准
• 兼容 斯特拉专业1.9+ 和 斯特拉建筑师
• 自动布局合理定位元素；如果需要，在Stella中手动调整
• 带空格的变量名在内部转换为下划线
• 解析器对导入的库存流入/流出和连接器端点引用进行规范化
• 时间步长导出避免了有损的倒数舍入（非精确倒数被导出为明文 dt)
• 导入/导出在支持的部分（标头、sim_specs、变量、视图/模型附加内容）上保留未知的attr/element，以减少往返数据丢失
• 兼容性语料库回归测试上线 tests/fixtures/compat_corpus/ 并在CI中运行
• 维护助手： python scripts/sync_compat_corpus_manifest.py --check 验证语料库清单同步

项目结构

stella-mcp/
├── README.md
├── LICENSE
├── pyproject.toml
└── stella_mcp/
    ├── __init__.py
    ├── server.py      # MCP server wiring + schemas
    ├── tool_handlers.py # Tool handler implementations/registration
    ├── tool_schemas.py  # MCP tool schema definitions
    ├── xmile.py       # Core model types + layout logic
    ├── xmile_io.py    # XMILE parsing/export helpers
    └── validator.py   # Model validation logic

贡献

欢迎投稿！请随时提交问题或拉取请求。

维护人员发布

PyPI发布由以下人员处理 .github/workflows/publish.yml 使用PyPI可信 出版。要发布新版本，请执行以下操作：

1. 更新中的版本 pyproject.toml 和 stella_mcp/__init__.py.
2. 将发布更改合并到 main.
3. 例如，创建并发布带有匹配标签的GitHub版本 v0.5.0.

GitHub发布事件构建源代码分发和轮，然后发布 通过配置的可信发布者将它们发送到PyPI。

许可证

MIT许可证-请参阅 许可证 了解详情。

致谢

• 模型上下文协议 通过Anthropic
• ISEE系统 Stella和XMILE格式