# 橙岛经营底座 MCP

一个本地优先、可审计的经营状态 MCP Server。它把橙岛 Skill 产生的知识、证据、决策、任务、执行回执和复盘结果保存到同一个 SQLite 数据库，让不同会话能够继续同一个项目。

## 它解决什么问题

Skill 负责分析和方法，但单独使用 Skill 容易出现三个问题：

1. 下一次对话不知道上一次已经确认了什么。
2. “生成方案”“人工批准”“已经执行”“拿到回执”“产生业务结果”容易被混在一起。
3. 知识、证据、任务和结果散落在聊天记录里，无法审计。

这个 MCP 把上述状态保存为结构化记录。它不会发布内容、发送邮件、改价、投放、退款、采购，也不会连接外部店铺。

## 当前版本

- 版本：0.1.0
- 传输：本地 stdio
- 存储：SQLite
- MCP SDK：官方 TypeScript SDK v2
- 工具：20 个
- 资源：系统说明、项目概览
- Prompt：项目每日复盘

## 20 个工具

| 分组 | 工具 | 用途 |
|---|---|---|
| 项目 | `project_create` | 创建经营项目 |
| 项目 | `project_list` | 查看项目列表 |
| 项目 | `project_get` | 读取项目目标、阶段和记录数量 |
| 知识 | `knowledge_ingest` | 写入带来源、隐私、版本和哈希的知识 |
| 知识 | `knowledge_search` | 在指定项目内检索知识 |
| 证据 | `evidence_add` | 保存报表、截图、客户反馈或平台回执 |
| 证据 | `evidence_list` | 查看项目证据 |
| 决策 | `decision_create` | 创建有证据依据的决策提案 |
| 决策 | `decision_review` | 由明确审核人批准或拒绝决策 |
| 决策 | `decision_list` | 查看决策与审批状态 |
| 任务 | `task_create` | 把批准后的决策转为任务 |
| 任务 | `task_update` | 更新任务状态和执行结果 |
| 任务 | `task_list` | 查看任务 |
| 回执 | `receipt_attach` | 保存外部系统已经返回的执行凭证 |
| 回执 | `receipt_list` | 查看执行回执 |
| 缺口 | `open_question_add` | 登记缺失数据或授权 |
| 缺口 | `open_question_update` | 补充回答或关闭问题 |
| 缺口 | `open_questions_list` | 查看待补信息 |
| 快照 | `project_snapshot` | 保存不可变的项目阶段快照 |
| 复盘 | `review_run` | 判断未执行、缺回执或可人工复盘 |

## 人工审批门禁

当 `decision_create` 的 `execution_mode` 为 `human_approval_required`：

1. 决策初始状态为 `proposed`。
2. 必须调用 `decision_review`，记录审核人、批准/拒绝和说明。
3. 未批准前，`task_create` 会拒绝从该决策创建任务。
4. MCP 只创建本地任务，不执行外部动作。
5. 外部动作完成后，使用 `receipt_attach` 保存真实回执。
6. `review_run` 不会把回执自动判定为业务有效。

## 本地运行

要求 Node.js 22.13 或更高版本。

```bash
npm ci
npm run build
npm run check
node dist/index.js
```

服务器使用 stdio，直接运行后没有网页界面，也不会在终端输出普通日志。

默认数据库：

```text
data/orange-island-core.sqlite
```

可通过环境变量覆盖：

```bash
OI_CORE_DB_PATH=/absolute/path/orange-island-core.sqlite node dist/index.js
```

## 安装到 Codex

```bash
codex mcp add orange_island_core -- \
  /usr/local/bin/node \
  /Users/borytan/Documents/Codex/proj_017_mcp_橙岛经营底座/dist/index.js
```

安装后重新打开一个 Codex 任务，使新 MCP 工具进入工具列表。

检查配置：

```bash
codex mcp list
```

## 自然语言调用示例

```text
请用橙岛经营底座创建一个“外贸 B 端获客”项目，负责人是阿宝，当前阶段是内容获客试点。
```

```text
把这份产品资料写入刚才的项目知识库，来源标记为用户事实，隐私级别 internal。
```

```text
根据项目证据创建一个需要人工批准的决策提案。先不要生成任务。
```

```text
我批准这个决策，审核人写阿宝，说明是“先做七天小样本测试”。然后创建任务。
```

```text
检查这个项目是只生成了方案、已经执行、拿到回执，还是已经具备业务复盘条件。
```

## 数据边界

- 只写入用户指定或 MCP 调用中明确提供的数据。
- 不扫描电脑其他目录。
- 不连接外部平台。
- 不保存店铺 Token、API 密钥或登录凭证。
- 缺失数据使用待补问题记录，不由 AI 编造。
- 删除项目和不可逆写操作尚未开放。

## 验证

`npm run check` 同时执行：

- TypeScript 编译
- SQLite 经营规则测试
- 官方 MCP Client stdio 握手
- 工具列表验证
- 项目 → 知识 → 证据 → 决策 → 人工审批 → 任务 → 回执 → 复盘闭环