内容
MCPBasket
MCPBasket 是一个的本地优先的预购工作空间。它记录每次研究响应作为的产品列表，让用户可以选择性地将产品添加到一个持久的主篮子中，跨搜索，并批准的结账做准备集成处理。
它永远不会创建订单。
## 代理能获得- 每个研究响应保存一次搜索，包括创建时间戳和完整的快照。
- 持久化搜索细化请求，保留照并创建链接的新研究响应。
- 验证的产品来源和图片，当代理可以观察到它们时。
- 一个持久的主篮子，可以从任何保存的搜索中收集选定的产品。
- 一个本地查看器，包含研究（/）、保存的搜索（/searches）、主篮子（/basket）和验证源查看。
- 仅占位符 checkout。checkout 提供商必须单独连接。
## 软件包
| 路径 | 责任 |
| --- | --- |
| `packages/mcp-basket` | 领域模型、应用程序服务、MCP 适配器、本地 HTTP API、JSON 存储和本地查看器。 |
| `skills/mcpbasket` | 研究和记录产品候代理工作流。 |
## 系统设计
篮子状态保留在运行代理的机器上。本地 MCP 进程和本地查看器相同的应用程序服务和持久存储。
```text
代理 + MCP 适配器 -> 篮子服务 -> JSON 仓库 ^ |
| v
本地查看器 共享篮子状态
```
核心故意独立于传输和商家特定的结账。阅读 [`docs/ARCHITECTURE.md`](docsECTURE.md) 以获取边界和扩展点。用于移动受信任购买授权的公共服务已设计但未实现；议的形状在 [`docs/REMOTE-SERVICE.md`](docsERVICE.md) 中。
## 为代理安装
### 1. 安装软件包
```bash
git clone https://github.com-labs/mcpbasket.git
cd mcpbasket
npmnpm run verify
```
使用 Node.js 20 或更高版本。保持仓库在稳定位置：下面的 MCP 配置使用绝对构建路径。
### 2. 选择一个持久的本地存储
查看器和必须使用 **相同的绝对** `MCPBASKET_STORE_PATH`。这使得研究历史和主篮子在进程重启后存活并在查看器中可见。
复制 `.env.example` 到 `.env` 并设置绝对路径：
```bash
cp .env.example .env
# 编辑 .env 以将 MCPB_STORE_PATH 设置上的绝对路径。
# 不要在此处使用 $HOME 或 ~；.env 值不会被 shell 扩展。
```
`.env` 文件是可选的。当 MCP 服务器由代理主机（Hermes、Claude 等）启动时，主机已经通过其 MCP 服务器 `MCPBASKET_STORE_PATH` - `.env` 仅在开发过程中直接运行查看器时方便使用。
### 3. 启动本地查看器
```bash
npm run viewer
```
查看器从环境中读取 `MCPBASKET_STORE_PATH`。如果未设置，则回退到存储库根目录中的 `.env`，然后回退到 `$CWD/.mcpbasket/basket.json`。
打开 `http://127.0.0.4377/health` 并期望 `{ "ok": true } 可选： 将查看器细化路由回 Hermes
始终在调度任何内容之前保存输入的细化提示和完整的源搜索快照。要使本地查看器自动启动 Hermes 单次运行，请使用绝对 Hermes 命令配置 **查看器进程**：
```bash
export MCPBASKET_REFINEMENT_HERMES_COMMAND="$(command -v hermes)"
```
使用此选择性设置，细化在后台启动 `hermes --oneshot`。启动的代理仅接收细化 ID，然后通过 MCP 加载存储的用户和不可变源快照，然后创建链接的新搜索。取消设置变量以保持请求队列，以便代理使用 `basket-list-refinement-requests恢复。
### 4. 将 MCP 服务器注册到代理
使用内置入口点并重复相同的环境值，特别是 `MCPBASKET_STORE_PATH`：
```json
{
"mcpServers": {
"mcpbasket": {
"command": "node",
"args": ["/absolute/path/to/mcpbasket/packages/mcp-basket/build/index.js"],
"env": {
"MCPBASKET_STORE_PATH": "/absolute/path/to/basket.json",
"MCPBASKET_PORT": "4377",
"MCPBASKET_BIND_HOST": "127.0.0.1",
"MCPBASKET_VIEWER_URL": "http://127.0.0.1:4377"
}
}
}
}
```
JSON 是一个标准的 MCP 示例。替换两个绝对路径。对于 Hermes，请使用 [docs/HERMES.md](docs/HERMES.md) 中的现成 YAML。
### OpenClaw 安装
OpenClaw 在其自己的注册表中存储出站 MCP 服务器，并将本地技能安装到活动代理工作空间中。首先构建 MCPBasket，然后使用绝对路径注册内置 stdio 服务器：
```bash
npm run build
openclaw mcp set mcpbasket '{
"command": "node",
"args": ["/absolute/path/to/mcpbasket/packages/mcp-basket/build/index.js"],
"env": {
"MCPBASKET_STORE_PATH": "/absolute/path/to/basket.json",
"MCPBASKET_PORT": "4377",
"MCPBASKET_BIND_HOST": "127.0.0.1",
"MCPBASKET_VIEWER_URL": "http://127.0.0.1:4377"
}
}'
```
为活动 OpenClaw 代理安装本地技能，然后验证两个注册：
```bash
openclaw skills install "$(pwd)/skills/mcpbasket" --as mcpbasket
openclaw mcp list
openclaw skills info mcpbasket
openclaw skills check
```
从预期的代理工作空间运行技能命令，或添加 OpenClaw 的 `--agent <id>` 选项以定位特定代理。查看器仍然是一个单独的本地进程：在 `.env` 中配置相同的绝对 `MCPBASKET_STORE_PATH`，然后运行 `npm run viewer`。参见 [OpenClaw MCP 参考](https://docs.openclaw.ai/cli/mcp) 和 [技能参考](https://docs.openclaw.ai/cli/skills获取注册和工作空间行为。
### 5. 安装代理技能
将完整的 [`skills/mcpbasket`](skills/mcpbasket) 目录安装或符号链接到主机代理的技能目录中，然后重启代理。对于本地技能目录，命令通常是：
```bash
mkdir -p /path/to/agent/skills
ln -s "$(pwd)/skills/mcpbasket" /path/to/agent/skills/mcpbasket
```
代理必须加载此 `SKILL.md`；MCP 工具本身并不能告诉它何时创建搜索、验证来源或将产品添加到主篮子中。安装后，使用代理的技能列表命令确认 `mcpbasket` 已启用。
技能要求代理：
1. 调用 `basket-set-context` 并设置 `startNewSearch: true`每个新的研究响应。
2. 在将产品存储在 `product.urls.product` 之前，验证直接产品页面。
3. 仅在图像加载并属于该产品时保存图像。
4. 将失败的链接保留为证据，并标记候选者 `needs_review` 而不是暴露损坏的来源。
5. 仅在用户明确选择后才添加到主篮子中。
6. 在处理细化时，首先加载其持久化请求，然后创建链接的新搜索，而不是修改原始搜索。
### 6. 烟雾测试
使用 MCP 主机的连接测试，然后要求代理研究产品。确认：
- 搜索出现在 `/searches，带有其时间戳和候选计数。
- 验证在查看器中打开。
- 添加产品出现在 `/basket，并在查看器重启活。
- 兼容的代理可以在不修改原始快照的情况下处理队列细化请求。
默认情况下，查看器仅限于环回。它是一个 MVP 检查表面，而不是公共共享服务。私有网络设置可以将绑定到私有接口并设置匹配的 `MCPBASKET_VIEWER_URL`；、公共共享和不在范围内。
## 集成
- [MCP 服务器包](packages/masket/README.md)
- [Hermes 安装](docs/HERMES.md)
- [HTTP API 合同](docs/HTTP-API.md)
- [计划的远程服务](docs/ERVICE.md)
- [代理技能](skills/mcpbasket/SKILL.md)
- [代理的提示构造](skills/mcpbasket/references/prompting.md)
- [贡献](.md)
## 质量门
```bash
build
npm run test
npm run verify
```
