# MindRelay

一个通过对话把想法转成可追踪行动的在线 MCP App。它支持状态、优先级、日期和自然
时间提示，并保留原始上下文作为私人在线笔记。服务部署在 Vercel，通过 Streamable
HTTP 提供 MCP 工具，使用 Neon PostgreSQL 保存数据，并通过 OAuth 2.1 与 Supabase
Google 登录隔离每位用户的数据。

行动项会结构化保存到 PostgreSQL 的 `memo_actions` 表；事项、状态、优先级、日期和
时间提示均可直接查询及建立索引。`memo_notes` 只保留用户原始上下文，行动读写不依赖
Markdown，也不会解析旧版 Markdown 行动记录。

## 工具

| 工具 | 作用 | 数据变更 |
| --- | --- | --- |
| `open_memo_manager` | 打开行动与原始记录管理面板 | 否 |
| `create_note` | 创建笔记 | 是 |
| `list_notes` | 按关键词或标签列出笔记 | 否 |
| `capture_thought` | 保存想法并整理下一步行动 | 是 |
| `create_action` | 从面板手动创建结构化行动 | 是 |
| `list_actions` | 按状态、优先级和时间查看行动项 | 否 |
| `get_note` | 通过 ID 读取完整笔记 | 否 |
| `delete_action` | 经用户确认后按 ID 永久删除单项行动 | 是 |
| `delete_note` | 经用户确认后删除原始记录及其全部关联行动 | 是 |
| `update_action` | 通过对话更新行动项状态、优先级、日期、时间提示或备注 | 是 |
| `update_action_by_id` | 从面板按 ID 精确修改结构化行动 | 是 |
| `update_note` | 修改标题、正文或标签 | 是 |

可视化面板默认进入“行动”视图，直接对应 `memo_actions` 的事项、状态、优先级、日期、
时间提示、备注、标签和字段来源；可手动新增、筛选、编辑和删除。“原始记录”视图对应
`memo_notes`，用于查看或维护用户输入的原始上下文。列表项在鼠标移入时显示删除按钮，
执行前必须再次确认；删除原始记录会同时删除面板明确提示数量的关联行动。

线上 MCP 地址：

```text
https://memo-mcp.vercel.app/api/mcp
```

健康检查：

```text
https://memo-mcp.vercel.app/api/health
```

## 客户端配置

所有客户端共用 [`config/mcp-servers.json`](config/mcp-servers.json) 作为配置源。
生成文件不包含凭据，OAuth Token 由客户端在用户登录后保存。

```bash
npm run config:generate
npm run config:check
npm run config:install
```

生成结果包括：

- 根目录 `.mcp.json`：供 Claude Code 使用；
- `plugins/mindrelay/.mcp.json`：由 Codex 和 Claude 插件共用；
- `plugins/mindrelay/skills/mindrelay/SKILL.md`：由 Codex 和 Claude 插件共用。

## 开发与验证

环境要求：Node.js 20 或更高版本。

```bash
npm install
npm run typecheck
npm test
npm run config:generate
npm run config:check
```

本地调试 Vercel HTTP 服务：

```bash
vercel login
vercel link
vercel env pull .env.local
npm run dev
```

线上健康检查：

```bash
npm run smoke
```

如果终端需要代理才能访问 Vercel：

```bash
MEMO_HEALTH_PROXY=http://127.0.0.1:7890 npm run smoke
```

生产 OAuth 端到端验收需要设置 `MEMO_PUBLIC_BASE_URL` 和
`MEMO_OAUTH_ADMIN_PASSWORD`：

```bash
npm run oauth:smoke
```

## 部署

Vercel Production 至少需要：

- `DATABASE_URL`
- `MEMO_OAUTH_SIGNING_KEY`
- `MEMO_PUBLIC_BASE_URL`
- `SUPABASE_URL`
- `SUPABASE_PUBLISHABLE_KEY`

部署命令：

```bash
vercel deploy
vercel deploy --prod
```

完整配置见 [`docs/vercel-deployment.md`](docs/vercel-deployment.md)，团队接入见
[`docs/team-onboarding.md`](docs/team-onboarding.md)。

## Codex 插件发布

`codex mcp add` 只安装 MCP Server 连接，不会安装插件清单与 Skill，因此 MindRelay 不会
出现在 Codex 的“插件”菜单中。要显示完整的 MindRelay 插件入口，必须从 Marketplace
安装仓库中的插件。

其他人克隆本仓库后，在仓库目录执行：

```bash
codex plugin marketplace add .
codex plugin add mindrelay@mindrelay-marketplace
```

随后完全重启 Codex 并新建任务。可用下面的命令确认安装结果：

```bash
codex plugin list
```

输出中应出现 `mindrelay@mindrelay-marketplace`，状态为 `installed, enabled`。此时插件菜单
会显示 `MindRelay`，并同时加载 Skill 与线上 MCP Server。

仓库只保留 `mindrelay` 插件。开发者在本机同步、校验并重新安装：

```bash
npm run config:install
npm run plugin:release
```

完整发布链路：

```bash
npm run release:online
```

发布后完全重启 Codex，并新建任务，使客户端加载新的 Skill 和 MCP 工具定义。

如果希望不克隆仓库的普通用户也能直接在 Codex 插件目录中搜索并安装 MindRelay，需要
完成 OpenAI Plugin Submission Portal 的审核并发布。仅分享 MCP URL 不会创建插件目录
条目。

## Claude 插件

Claude 和 Codex 共用同一套 MindRelay Skill 与线上 MCP 配置，只分别保留各平台要求的
轻量清单文件：

- Codex：`plugins/mindrelay/.codex-plugin/plugin.json`
- Claude：`plugins/mindrelay/.claude-plugin/plugin.json`

Claude Code 可以从仓库市场安装：

```bash
claude plugin marketplace add /path/to/Codex-Claude-Plugin
claude plugin install mindrelay@mindrelay-marketplace
```

Claude Chat / 桌面端使用 **Customize → Plugins → Upload plugin** 上传
`dist/mindrelay-claude-plugin-0.4.0.zip`。安装后应显示 `1 skill` 和 `1 connector`，无需再单独添加同名 Connector。

公开发布到 Claude Plugin Directory 或 Connectors Directory 时，按照
[`docs/claude-plugin-publishing-guide.md`](docs/claude-plugin-publishing-guide.md) 执行。