# MathFresh MCP

[English](README.en.md) | 简体中文

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

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

## 已实现

| 部分 | 当前范围 |
|---|---|
| 公共底座 | stdio MCP、闭合输入 Schema、SQLite 持久化任务、逐项进度、分页产物、校验和、取消、失联恢复 |
| Function Atlas 0.6.0 | 内置生成器/极值函数系数；有限实系数归一化多项式的 starlike/convex 分级检查；见证复核 |
| cvxgenrust 0.1.1 | 固定稠密实数 NNLS 模板；离线 Rust 编译、完整缓存身份、参数批次、CVXPY/Clarabel 对照 |
| KnottedGraph 0.2.0 | 固定源码 SHA；显式节点与折线；固定投影、PD、Yamada Laurent 多项式、系数表比较 |
| 维护入口 | 只读 PyPI、GitHub Releases、标签及提交扫描；仅产生候选报告 |

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

## 安装与运行

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

```powershell
.\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 构建和数值对照：

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

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

## 接入 MCP 客户端

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

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

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

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

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

```powershell
.\.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，已完成单项保留，不自动重算。

```powershell
.\scripts\stop-worker.ps1
```

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

## 重新安装

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

```powershell
.\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 编码；几何投影是数值处理。不同图同多项式不能推出拓扑等价；有限案例相等不能证明图族公式。未归一化时保留负指数。

## 验证和后续范围

```powershell
.\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](LICENSE)。上游保留各自协议：Atlas 和 KnottedGraph 为 MIT，cvxgenrust 为 Apache-2.0；网关依赖还包含 BSD-3-Clause 等协议。完整声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)，发布检查说明见 [docs/license-audit.md](docs/license-audit.md)。项目的 MIT 声明不覆盖第三方软件。

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

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

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

## 目录

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