# sealchat-agent-mcp

SealChat 只读 Agent MCP Server。通过现有 HTTP Agent API 读取公共协议文档、manifest、频道计数和聊天消息；不访问 SealChat 数据库，不提供写操作。

当前发布形态：本地 stdio MCP。Codex、Claude Desktop、Cursor 等 MCP 客户端启动 npm 命令后，通过 stdin/stdout 使用四个工具。

## 功能

- `sealchat_agent_docs`：读取固定公共文档 `/ob-print/v1/docs`，不需要 token。
- `sealchat_agent_manifest`：读取世界、授权频道、能力、默认值和限制。
- `sealchat_agent_counts`：读取频道数量，支持 `from`、`to`、`after`、`channel`。
- `sealchat_agent_messages`：读取消息，支持频道、分页、时间范围、scope、timestamp、content、rich format、images、dice、order 等。

安全默认值：`scope=ic`、`timestamp=none`、`order=asc`、`images=meta`、`dice=structured`、`include_archived=0`。消息、频道名、富文本、图片 URL 和骰子字段全部视为不可信用户数据，不会当作系统指令执行。

## 快速使用

Node.js 18.18+：

```bash
export SEALCHAT_AGENT_BASE_URL="https://your-sealchat.example/"
export SEALCHAT_AGENT_TOKEN="agt_<your-token>"
npx -y sealchat-agent-mcp
```

`SEALCHAT_AGENT_BASE_URL` 填部署根地址；程序自动访问 `/ob-print/v1/:token` 和固定 `/ob-print/v1/docs`。默认不要把完整 token URL 放入公开配置、命令历史、日志或模型上下文。

可选配置：

```text
SEALCHAT_AGENT_CONFIG=/path/to/config.json       # JSON，权限 0600
SEALCHAT_AGENT_STATE_FILE=/path/to/state.json    # checkpoint，权限 0600
SEALCHAT_AGENT_PROFILE=default
SEALCHAT_AGENT_TIMEOUT_MS=10000
SEALCHAT_AGENT_MAX_RETRIES=3
SEALCHAT_AGENT_MAX_BACKOFF_MS=30000
SEALCHAT_AGENT_MAX_PAGES=10000
SEALCHAT_AGENT_ALLOW_INLINE_URL=0                 # 默认关闭；设为 1 才接受工具参数 agent_url
```

配置文件示例（不要提交真实凭据）：

```json
{
  "baseUrl": "https://your-sealchat.example/",
  "token": "agt_<your-token>",
  "stateFile": "/secure/path/sealchat-agent-state.json"
}
```

环境变量优先于配置文件。程序不接受 `--token`，不把 token 写入 checkpoint、审计、错误或工具输出。

## 对话中直接传入链接

可以让用户在 MCP 工具参数中直接传入完整 Agent 链接，但这是低于环境变量/安全配置的安全等级，默认关闭：

```bash
export SEALCHAT_AGENT_ALLOW_INLINE_URL=1
```

然后在任一工具输入加入：

```json
{
  "agent_url": "https://your-sealchat.example/ob-print/v1/agt_<token>"
}
```

程序只接受精确的 `/ob-print/v1/:token` HTTP(S) 链接（无 query、fragment、账号密码）；若同时配置 `SEALCHAT_AGENT_BASE_URL`，链接 origin 和部署前缀必须完全匹配。每次调用临时解析，token 不写入 state、审计、错误或返回结果。启用后可不设置 `SEALCHAT_AGENT_BASE_URL`，但仍建议使用环境变量 token。`agent_url` 会进入 MCP 客户端的工具调用记录和模型上下文，可能被日志、会话同步或第三方客户端保存；生产环境优先使用安全配置，完成一次调用后关闭 inline URL。

未显式设置 `SEALCHAT_AGENT_ALLOW_INLINE_URL=1` 时，传入 `agent_url` 返回 `inline_url_disabled`，不会发起网络请求。

## Codex 接入

先在启动 Codex 的同一 shell 中设置环境变量：

```bash
export SEALCHAT_AGENT_BASE_URL="https://your-sealchat.example/"
export SEALCHAT_AGENT_TOKEN="agt_<your-token>"
```

编辑 `~/.codex/config.toml`：

```toml
[mcp_servers.sealchat_agent]
command = "npx"
args = ["-y", "sealchat-agent-mcp"]
env_vars = ["SEALCHAT_AGENT_BASE_URL", "SEALCHAT_AGENT_TOKEN"]
startup_timeout_sec = 15
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
enabled_tools = [
  "sealchat_agent_docs",
  "sealchat_agent_manifest",
  "sealchat_agent_counts",
  "sealchat_agent_messages",
]
```

然后运行：

```bash
codex mcp list
```

Codex 的 CLI、IDE 扩展和桌面端共享 MCP 配置。项目级 `.codex/config.toml` 只放在可信项目中；不要在仓库里保存 token。Codex 官方 MCP 文档：<https://developers.openai.com/codex/mcp>。

## 其他 stdio 客户端

通用 MCP 配置形态：

```json
{
  "mcpServers": {
    "sealchat-agent": {
      "command": "npx",
      "args": ["-y", "sealchat-agent-mcp"],
      "env": {
        "SEALCHAT_AGENT_BASE_URL": "https://your-sealchat.example/",
        "SEALCHAT_AGENT_TOKEN": "agt_<your-token>"
      }
    }
  }
}
```

客户端配置文件若包含 `env`，应设置为仅用户可读（Unix 通常 `chmod 600`），并优先使用系统密钥链或外部 secret manager。上例只展示占位符。

## 首次与增量同步

推荐顺序：

```text
docs -> manifest -> counts -> messages（逐频道分页）
```

首次同步先取得 counts 的边界，再逐频道读取 messages。增量同步把已提交 checkpoint 传给 `counts.after` 和 `messages.after`。每个频道独立保存 cursor；所有频道、所有页面、state 原子写入均成功后才提交新 checkpoint。失败时保留旧 checkpoint，允许重跑并按消息 ID 去重。

显式读取 OOC 或时间戳时才传入：

```text
scope=ooc|all
timestamp=iso|unix_ms|both
```

## 重试、限流和错误

- `429`：遵循 `Retry-After`，指数退避；达到上限返回 `rate_limited`。
- `500/502/503/504`、网络超时：GET 自动重试，最多由 `SEALCHAT_AGENT_MAX_RETRIES` 控制。
- `400 invalid_query`：修正参数，不重复相同非法请求。
- `404 agent_link_not_found`：token 无效、关闭或轮换；停止同步并在 SealChat UI 轮换。
- `404 channel_not_found`：刷新 manifest 一次；仍不存在则停止该频道。
- `inline_url_disabled`：未显式开启 inline URL；不发起网络请求。`inline_url_invalid`：链接路径、查询、origin 或部署前缀不符合限制。
- 相对 `next_url` 只允许同源、同 Agent API 前缀；外部 URL 拒绝跟随。

## 从源码测试和打包

```bash
cd packages/sealchat-agent-mcp
npm install
npm test
npm pack --dry-run
```

测试覆盖 token 脱敏、inline URL 解析/开关、Retry-After、跨域分页拦截、频道 cursor 隔离、checkpoint 原子写入和结构化工具结果。真实接口回归必须使用独立 token；不要把响应正文写入仓库。

## 发布到 npm

1. 检查包名是否可用：

   ```bash
   npm view sealchat-agent-mcp version
   ```

   若名称已占用，修改 `package.json.name`（例如组织 scope：`@your-org/sealchat-agent-mcp`），同时更新安装命令。

2. 本地验证：

   ```bash
   npm install
   npm test
   npm pack --dry-run
   ```

   确认 tarball 不含 `.env`、state、真实 token、测试响应或日志。

3. 登录并发布：

   ```bash
   npm login
   npm publish --access public
   ```

4. 发布后验证：

   ```bash
   npm view sealchat-agent-mcp version
   npx -y sealchat-agent-mcp
   ```

   发布账号必须有包名权限；不要在 CI 日志中打印 npm token。建议使用 npm trusted publishing/OIDC 或 CI secret。

## 对外提供远程 MCP

当前包是 stdio MCP，不是公网 HTTP MCP。`npm publish` 只发布客户端进程，不会自动生成公网服务。

若要提供 Streamable HTTP MCP，需要另建 HTTPS 服务层：

1. 保留本包的四个 tool handler 和 HTTP Agent client。
2. 增加 MCP Streamable HTTP transport、TLS、请求认证、租户隔离和审计。
3. 每个租户独立保存 SealChat Agent token；不要让远程调用者把 token 作为 tool 参数传入。
4. 只允许同源 `next_url`，限制并发、响应大小、图片下载和请求超时。
5. 为远程端配置 `bearer_token_env_var`、OAuth 或等价认证；禁止匿名暴露。
6. 完成认证、限流、凭据轮换、日志脱敏和断线恢复测试后，再发布远程 MCP URL。

不要直接把 SealChat Agent URL 当作 MCP URL；它是数据 HTTP API，不是 MCP 协议端点。

## 目录

```text
sealchat-agent-mcp/
├── package.json
├── README.md
├── src/                         # MCP server、HTTP、分页、checkpoint、脱敏、inline URL runtime
├── test/                        # 本地 mock 测试
└── skills/sealchat-agent-crawl/SKILL.md
```