MathFresh MCP

English | 简体中文

把数学软件封装为一个本地 MCP 入口。项目主体已实现，当前为开发预览版；三个包均有真实底层调用和端到端示例，不以接口数量代表科研能力。

网关使用 Python 3.12、官方 MCP Python SDK 2.3.0。Atlas、CVX、KnottedGraph 分别安装在独立虚拟环境中。开发预览版支持 Windows x64；其他平台尚未验收。

已实现

全部启用时有 13 个工具：9 个数学工具和 4 个公共工具。默认只暴露 Atlas。注册目录保留 preview 状态及具体测试范围；没有自动升级或自动准入。

Related MCP server: Awaitless

安装与运行

下载或克隆仓库后，在项目根目录打开 PowerShell，先安装网关和 Atlas，再运行示例：

.\scripts\setup.ps1
.\.venv\Scripts\python.exe -m mathfresh.cli doctor
.\.venv\Scripts\python.exe -m mathfresh.cli submit atlas_verify_batch examples\atlas.json --wait
.\.venv\Scripts\python.exe -m mathfresh.cli submit atlas_verify_witness examples\atlas-witness.json --wait

提交接口先可靠保存任务，再返回 job_id。--wait 轮询直至终态。底层 Python API 是 mathfresh.core.service.Service。

运行三包完整示例，包括 Rust 构建和数值对照：

$env:MATHFRESH_PACKAGES = 'atlas,cvxgenrust,knottedgraph'
.\.venv\Scripts\python.exe examples\run_all.py

报告在 .mathfresh\example-results.json，完整输入、上游原始记录、证据、依赖环境、日志和版本信息在 .mathfresh\artifacts，任务在 .mathfresh\jobs.sqlite3。计算结果由工具生成；不随下载自动获取论文或私有数据库。

接入 MCP 客户端

先在客户端之外启动持久协调进程：

.\scripts\start-worker.ps1
# 全部三包：
.\scripts\start-worker.ps1 -Packages 'atlas,cvxgenrust,knottedgraph'

客户端配置模板为 mcp.example.json，其中 <PROJECT_ROOT> 是占位符。Windows 上可在项目根目录运行以下命令，自动生成带有正确绝对路径的 mcp.local.json：

.\scripts\configure-mcp.ps1
# 全部三包：
.\scripts\configure-mcp.ps1 -Packages 'atlas,cvxgenrust,knottedgraph'

将生成配置中的 mathfresh 条目加入 MCP 客户端配置。mcp.local.json 已被 Git 和源码打包排除；项目移动后重新生成。也可以复制模板，手动替换所有 <PROJECT_ROOT>；客户端不会自动展开该占位符。

.\.venv\Scripts\python.exe -m mathfresh.cli serve

serve 的标准输出专供 MCP 协议，不是交互菜单。MCP 参数形如 {"request":{...}}；公共工具如 job_status 直接传 job_id。每个数学工具均返回应用层任务句柄，通过 job_status 查询，再通过 artifact_read 分页取原始记录。本版没有宣称实现 MCP Tasks 扩展。

独立协调进程是必要的：部分 MCP 客户端断开时会结束服务器的整个子进程树。网关仅落盘和查询；协调进程启动各任务 supervisor，后者在指定包的环境中运行 worker。未启动协调进程时，MCP 提交仍落盘并显示 queued，同时返回启动提示。重新启动协调进程会执行排队任务；失联任务被标记 failed/partial，已完成单项保留，不自动重算。

.\scripts\stop-worker.ps1

停止协调进程不会删除任务或结果。运行中的任务可用 job_cancel 或 mathfresh cancel <job_id> 取消。

重新安装

需要 Python 3.12。全部包还需要 Rust stable、MSVC x64/C++17 Build Tools。网关与各 worker 的精确依赖分别锁在 locks。Windows 上：

.\scripts\setup.ps1              # 网关与 Atlas
.\scripts\setup.ps1 -AllPackages # 另含 CVX、KnottedGraph 和 Cargo 依赖预取

setup 是明确的开发安装操作，会使用网络下载锁定依赖。计算工具不会提供 pip、shell 或源码执行入口。CVX 计算期用锁定的 Cargo.lock 和 --offline --locked 构建；缺少预取依赖会失败并保存日志。KnottedGraph 锁定 921159b83f4589cfef1b80ec6c34d4bc7d129f27，不使用旧 PyPI 0.1.2 或可变 main。

locks/distribution-hashes.json 记录各版本 PyPI 发布文件哈希，供验收审计；目前 setup 使用版本锁，不是 --require-hashes 安装流程。Rust 的 Cargo.lock 自带注册包校验和。源码构建条件记录在 docs/verification.md。

输入和证据

Atlas 的 coefficients=[a2,a3,...] 表示 f(z)=z+a2*z^2+...，不包含常数或一次项。有理数用 {"numerator":1,"denominator":10}。适配器仅用受控的 SymPy 数值构造多项式，不解析用户公式字符串。

atlas_coefficients 区分 phi 和 f_phi：生成器 phi=1+B1*z+... 的系数不是归一化函数的 a2,a3,...。见证 API 只复核上游支持的、可精确表示为 binary64 的输入；如 1/10 的精确有理数见证会被拒绝，应走符号批量检查。浮点输入按其实际 binary64 值解释。

execution_status=succeeded 只表示执行完成。evidence 分别表示 numerical_screen、sufficient_condition、verified_witness、exact_computation、numerical_solution、build_record 或 unknown；上游记录原样保存在产物中。未满足充分条件不等于违例，未知 Taylor 余项不能得到完整函数结论。

CVX 接口只求指定实例，不证明一般定理。KnottedGraph 的精确计算对象是记录的 PD 编码；几何投影是数值处理。不同图同多项式不能推出拓扑等价；有限案例相等不能证明图族公式。未归一化时保留负指数。

验证和后续范围

.\scripts\test.ps1
.\.venv\Scripts\ruff.exe check src examples tests scripts maintenance
.\.venv\Scripts\python.exe maintenance\scan_updates.py

测试包括真实上游调用、精确系数、星形/凸性的不同判据、NNLS 解析解和非唯一解基线、投影一致性、非法输入、部分失败、超时、取消、重启恢复、产物路径与校验和，以及真实 MCP 客户端断开后的持续运行。

Windows 测试入口在隐藏窗口中运行，输出保存在 .mathfresh/test-output.log 和 .mathfresh/test-error.log，结束后显示到当前终端。后台 Python、工具探测和编译进程使用隐藏启动；编译器的子进程继承隐藏控制台。

已实现公共任务底座、固定优化模板和基础空间图工具。完整跨平台准入、广泛图族回归、人工数学复核、升级 PR/回滚发布流水线、模型任务对照和远程多租户服务仍属于后续工作。

这是本地单用户服务：有时间/内存/进程数/输出预算和结构化输入约束，但独立虚拟环境不是 OS 沙箱，进程没有完整文件系统或网络隔离。不要把当前版本公开为不可信多租户执行服务。构建和计算依赖只读来源记录，引用及许可证见 docs/verification.md。

开源协议与上传

项目原创代码采用 MIT。上游保留各自协议：Atlas 和 KnottedGraph 为 MIT，cvxgenrust 为 Apache-2.0；网关依赖还包含 BSD-3-Clause 等协议。完整声明见 THIRD_PARTY_NOTICES.md，发布检查说明见 docs/license-audit.md。项目的 MIT 声明不覆盖第三方软件。

仓库只提交源码、示例、依赖锁和公开文档。虚拟环境、运行数据、构建产物、mcp.local.json、环境变量文件和原始规划参考均在 .gitignore 中排除。检查并生成源码上传包：

.\.venv\Scripts\python.exe scripts\prepare_release.py

输出为 dist/mathfresh-mcp-0.1.0-source.zip，内含顶层许可证及第三方声明。MathFresh wheel 也携带这些声明，不包含数学库或生成的求解器二进制。若以后另行发布求解器、依赖环境或容器，需要针对实际随包分发的组件补齐声明。

目录

src/mathfresh/
  gateway.py          MCP 注册
  core/               Schema、设置、SQLite、产物及服务 API
  adapters/           三个固定版本适配器
  workers/            持久协调器、任务 supervisor、独立运行入口
  registry/           可用范围、来源和 Cargo 锁
locks/                四份 Python 依赖锁和分发哈希
examples/             三包可重跑输入及完整流程
tests/                契约、数学、任务生命周期与 MCP 测试
scripts/              安装、配置生成、依赖预取、worker 启停及发布检查
maintenance/          只读更新候选扫描
docs/                 测试说明、许可证与发布检查说明