# Origin MCP（Hardened）

> 面向 Codex 与其他 MCP 客户端的本地 Origin/OriginPro 自动化插件，覆盖数据导入、工作表处理、科学分析、绘图、版式调整、项目组织与文件导出。

**English summary:** A hardened Windows-local MCP integration for Origin and OriginPro, with typed workflow tools, an authenticated UI-thread bridge, constrained file access, compact tool profiles, and explicit gating for raw LabTalk.

当前插件版本为 `0.1.4-hardened.1`。Python 包采用等价的 PEP 440 版本 `0.1.4+hardened.1`。

## 项目定位

Origin 的自动化对象要求调用发生在合适的 Windows 与 UI 上下文中。本项目将 MCP 服务与 Origin 内桥接拆开：MCP 客户端通过 stdio 调用类型化工具；Origin Start App 在 Origin 进程内启动经过认证的本机桥接；工具请求再被排队到 Origin 可安全执行的线程。

本仓库基于 [`Ge-Shun/origin-mcp`](https://github.com/Ge-Shun/origin-mcp) 固定提交 `2cee56acad1d531b603ba6b9ef0bcffb7bce29eb`，保留 MIT 许可、原作者信息和第三方色板归属。硬化分支增加了更严格的 LabTalk、文件路径和依赖边界，详情见 [HARDENING.md](HARDENING.md) 与 [NOTICE.md](NOTICE.md)。

## 核心能力

- 导入 CSV、Excel 及结构化数据，读取和整理工作簿、工作表、矩阵与列指定。
- 执行变换、统计、拟合、信号处理、峰分析和批处理工作流。
- 创建并调整二维、三维、等高线、统计图、图像图及专业图形。
- 管理项目文件夹、图层、模板、Notes、分析结果和图形组合。
- 使用可复用配色、模板、FigureSpec 与出版图样式生成可审计的科研图件。
- 查询内置知识与能力目录，在执行前确认当前 Origin/OriginPro 能力。

## Hardened 差异

- 默认 `compact` profile 只暴露高层常用工具，减少误选和过度授权。
- 原始 LabTalk 不出现在普通 profile；仅 `full`/`expert` 可注册，并同时要求 `ORIGIN_MCP_ALLOW_RAW_LABTALK=1` 与单次 `confirm=true`。
- 导入、导出及其他路径型操作必须位于 `ORIGIN_MCP_ALLOWED_ROOTS`。
- MCP SDK 固定在兼容的 v1 范围 `<2`，避免不兼容导入破坏服务。
- 发布配置默认关闭 raw LabTalk，只启用诊断、读取、推荐与任务状态工具；写操作需客户端审批并按需开放。

## 架构与调用链

```text
Codex / MCP client
  └─ stdio MCP + tool profile + write approvals
       └─ origin_mcp Python service
            └─ authenticated localhost bridge
                 └─ Origin Start App / UI-thread task queue
                      └─ Origin/OriginPro Python & automation APIs
                           ├─ project / worksheet / graph
                           ├─ analysis operations
                           └─ constrained import/export
```

完整组件、握手、任务队列和故障边界见 [docs/architecture.md](docs/architecture.md)。

## 仓库结构

```text
.
├── .codex-plugin/plugin.json    # Codex 插件元数据
├── .mcp.json                    # 可移植、无密钥、无绝对路径的 MCP 配置
├── addon.py                     # Origin 侧桥接入口
├── src/origin_mcp/              # MCP 服务、客户端、桥接和工具实现
├── skills/origin/SKILL.md       # Agent 决策与安全约束
├── scripts/                     # App 构建、诊断、安装、启动和发布检查
├── docs/                        # 工具、配置、桥接与架构文档
├── examples/                    # 不含个人数据的可公开样例
├── tests/                       # Mock/离线测试及可选真实 Origin 验证
├── .env.example                 # 仅变量名
└── pyproject.toml               # Python 包与工具链定义
```

## 系统要求

- Windows 10/11。
- Python 3.10+ 与 [`uv`](https://docs.astral.sh/uv/)。
- 有效安装并授权的 Origin 或 OriginPro；当前目标系列为 Origin 2026/2026b。
- 真实分析能力取决于 Origin 版本、产品许可与已安装模块。

## 安装

### 1. 获取源码并安装环境

```powershell
git clone https://github.com/ZNaiGaomu/origin.git
Set-Location origin
./scripts/setup.ps1
```

若要同时暂存 Origin Start/Stop Apps：

```powershell
./scripts/setup.ps1 -InstallOriginApps
```

脚本会输出需要在 Origin 中打包和注册的 App 路径。已有安装仅在显式提供 `-Force` 时替换。详细步骤见 [docs/origin-ui-buttons.md](docs/origin-ui-buttons.md)。

### 2. 配置私密信息与工作目录

将 `.env.example` 复制为 `.env` 并仅在本机填写。至少应审查：

- `ORIGIN_MCP_BRIDGE_TOKEN`：桥接认证令牌；优先使用安装程序生成的握手文件，不要提交或分享令牌。
- `ORIGIN_MCP_ALLOWED_ROOTS`：任务专用的导入/导出根目录。
- `ORIGIN_MCP_TOOL_PROFILE`：默认推荐 `compact`。
- `ORIGIN_MCP_LOG_FILE`：可选本机诊断日志；日志可能包含文件名，应放在私有位置。

`.env`、项目文件、导出图、日志、状态与握手文件均不进入 Git。

### 3. 启动与诊断

在 Origin 中点击 **Origin MCP Bridge Start**，然后运行：

```powershell
uv run --frozen origin-mcp status
uv run --frozen origin-mcp doctor --ping-origin
./scripts/start.ps1
```

根目录 `.mcp.json` 仅使用 `uv`、相对路径和环境变量名。若客户端不从插件根目录解析 `cwd: "."`，在本机客户端覆盖工作目录即可，不应修改并提交个人绝对路径。

## 工具 profiles

| Profile | 适用场景 | 权限建议 |
|---|---|---|
| `compact` | 诊断、知识、工作表检查、图形推荐和常见高层流程 | 默认 |
| `data` | 集中处理导入、工作表、矩阵和变换 | 按任务启用 |
| `plot` | 绘图、模板、样式、图层与导出 | 按任务启用 |
| `analysis` | 拟合、统计、信号处理、峰分析 | 核对输入与许可后启用 |
| `standard` | 多阶段常规工作流 | 需要更大的工具上下文 |
| `full` / `expert` / `all` | 全部包装器；可能注册 raw LabTalk | 仅受审查的专家会话 |

具体工具与 profile 映射见 [docs/tools.md](docs/tools.md)。未知 profile 会安全回退到 `compact`。

## 权限与风险

- **项目状态：** 写工具会修改当前 Origin 项目；重要任务应先保存版本化副本。
- **文件边界：** 允许根目录不得设置为用户主目录、桌面总目录或磁盘根目录。
- **长任务：** MCP 超时不等于 Origin 侧失败；先查询桥接任务状态，避免重复提交分析。
- **原始脚本：** LabTalk 具有广泛能力，应优先使用类型化工具；确需启用时逐条审核并单次确认。
- **本机桥接：** 仅监听本机，令牌和握手文件不得上传或写入 Issue。
- **自托管 CI：** 真实 Origin 工作流只能手动触发到隔离的专用 runner，不对外部 PR 自动运行。

安全报告和部署要求见 [SECURITY.md](SECURITY.md)。

## 测试与发布验证

无需 Origin 的离线检查：

```powershell
uv run --frozen python scripts/publication_check.py
uv run --frozen python scripts/check_release_consistency.py
uv run --frozen python -m pytest -q
uv run --frozen python -m ruff check .
uv run --frozen python -m mypy
```

真实 Origin 健康检查与烟雾测试必须在用户明确启动桥接、指定临时允许根目录后运行。构建 App 或改动 `addon.py` 后，应按 `AGENTS.md` 重新安装 App，不能复用旧安装验证新代码。

CI 采用只读仓库权限；常规 CI 使用 mock 隔离 Origin 依赖，安全 CI执行隐私边界检查和依赖审计。发布包不包含虚拟环境、构建缓存、Origin 项目、握手/状态文件、日志、密钥或个人目录。

## 贡献与维护

贡献前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。新增工具应优先复用类型化模型、错误码、任务队列与恢复建议；新增文件操作必须覆盖越界测试；变更 profile 时需更新工具注册测试和文档。

## 许可证和第三方说明

本项目依据 MIT License 分发。上游作者、固定提交及内置色板来源见 [NOTICE.md](NOTICE.md)。Origin 和 OriginPro 是 OriginLab Corporation 的商标；本项目不是 OriginLab 官方产品，也不提供 Origin 许可证。