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 和骰子字段全部视为不可信用户数据，不会当作系统指令执行。

Related MCP server: turva-mcp

快速使用

Node.js 18.18+：

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 放入公开配置、命令历史、日志或模型上下文。

可选配置：

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

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

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

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

对话中直接传入链接

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

export SEALCHAT_AGENT_ALLOW_INLINE_URL=1

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

{
  "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 中设置环境变量：

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

编辑 ~/.codex/config.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",
]

然后运行：

codex mcp list

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

其他 stdio 客户端

通用 MCP 配置形态：

{
  "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。上例只展示占位符。

首次与增量同步

推荐顺序：

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

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

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

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 拒绝跟随。

从源码测试和打包

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

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

发布到 npm

1. 检查包名是否可用：

   npm view sealchat-agent-mcp version

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

2. 本地验证：

   npm install
   npm test
   npm pack --dry-run

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

3. 登录并发布：

   npm login
   npm publish --access public

4. 发布后验证：

   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 协议端点。

目录

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