┌─────────────────────────────────────────────────────────┐
│                   AI Agent (Claude Code / Cursor)       │
│                                                         │
│   "帮我生成一个 5x5 随机矩阵，求其特征值"                  │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP Protocol (stdio / SSE)
                       ▼
┌─────────────────────────────────────────────────────────┐
│              Python MCP Server (baltamatica-mcp)        │
│                                                         │
│   ┌───────────┐  ┌──────────┐  ┌────────────────────┐   │
│   │ Tool:     │  │ Tool:    │  │ Tool:              │   │
│   │ exec_code │  │ list_var │  │ get_variable_value │   │
│   └─────┬─────┘  └────┬─────┘  └─────────┬──────────┘   │
│         └──────────────┴──────────────────┘              │
│                        │ TCP Socket / stdin pipe         │
└────────────────────────┼────────────────────────────────┘
                         ▼
┌─────────────────────────────────────────────────────────┐
│           Baltamatica Engine (北太天元内核)                │
│                                                         │
│   bxEvalIn()  bxGetVariableNames()  bxAddVariable()     │
│   bxGetDoublesRO()  bxCallBaltamatica()                 │
└─────────────────────────────────────────────────────────┘

git clone https://github.com/wzlwww/baltamatica.mcp.git
cd baltamatica.mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

{
  "mcpServers": {
    "baltamatica": {
      "command": "/path/to/baltamatica.mcp/.venv/bin/python",
      "args": ["-m", "baltamatica_mcp"]
    }
  }
}

claude mcp add baltamatica -- /path/to/baltamatica.mcp/.venv/bin/python -m baltamatica_mcp

baltamatica.mcp/
├── README.md                   # 项目说明文档
├── LICENSE                     # MIT 开源许可证
├── pyproject.toml              # Python 项目配置 & 依赖管理
├── .gitignore                  # Git 忽略规则
│
├── src/
│   └── baltamatica_mcp/
│       ├── __init__.py         # 包初始化
│       ├── __main__.py         # 入口：python -m baltamatica_mcp
│       ├── server.py           # MCP Server 主逻辑 & Tool 注册
│       ├── engine.py           # 北太天元进程管理与通信
│       └── serializer.py       # 变量序列化（矩阵→JSON）
│
├── bex/                        # BEX 插件源码（C 语言，Phase 2）
│   ├── CMakeLists.txt          # 跨平台编译配置
│   ├── mcp_bridge.c            # BEX 插件核心：Socket 监听 + API 调用
│   └── mcp_bridge.h            # 头文件
│
├── tests/
│   ├── test_engine.py          # 引擎通信单元测试
│   ├── test_server.py          # MCP Tool 集成测试
│   └── fixtures/
│       └── sample_script.m     # 测试用 .m 脚本
│
├── docs/
│   ├── architecture.md         # 架构设计详细说明
│   ├── sdk-api-reference.md    # 北太天元 BEX SDK API 速查
│   └── contributing.md         # 贡献指南
│
└── examples/
    ├── monte_carlo_pi.m        # 蒙特卡洛估算 Pi
    └── matrix_demo.m           # 矩阵运算示例

feat: 添加 execute_code 工具实现
fix: 修复控制台输出截断问题
docs: 更新 README 安装说明
refactor: 重构引擎通信模块
test: 添加变量序列化单元测试
chore: 更新 CI 配置