MCPBasket

MCPBasket is a local-first pre-purchase workspace for agents. It records each research response as a durable product list, lets a user selectively add products to one persistent Main basket across searches, and prepares candidates before a human-approved checkout handled by another integration.

It never creates an order.

What An Agent Gets

• One saved search per research response, including its creation time and complete candidate snapshot.

• Persisted search-refinement requests that preserve the original snapshot and create a linked new research response.

• A verified product source and optional product image when the agent can observe them.

• A persistent Main basket that can collect selected products from any saved search.

• A local viewer with Research (/), saved Searches (/searches), Main basket (/basket), and verified-source viewing.

• A checkout placeholder only. A checkout provider must be connected separately.

Related MCP server: GoDaddy Orders MCP Server

Packages

System Design

The basket state remains on the machine running the agent. The local MCP process and local viewer/API use the same application service and persistent store.

Agent + skill -> MCP adapter -> BasketService -> JSON repository
                                      ^                |
                                      |                v
                              Local viewer/API <- shared basket state

The core is deliberately independent from transport and merchant-specific checkout. Read docs/ARCHITECTURE.md for boundaries and extension points. A public service for mobile viewing and trusted purchase authorization is designed but not implemented; its proposed shape is in docs/REMOTE-SERVICE.md.

Install For An Agent

1. Install the package

git clone https://github.com/gordo-labs/mcpbasket.git
cd mcpbasket
npm install
npm run verify

Use Node.js 20 or newer. Keep the repository in a stable location: the MCP configuration below uses an absolute build path.

2. Choose one persistent local store

The viewer and the MCP server must use the same absolute MCPBASKET_STORE_PATH. This is what makes research history and the Main basket survive process restarts and remain visible in the viewer.

Copy .env.example to .env and set an absolute path:

cp .env.example .env
# Edit .env to set MCPBASKET_STORE_PATH to an absolute path on your machine.
# Do not use $HOME or ~ here; .env values are not shell-expanded.

The .env file is optional. When the MCP server is launched by an agent host (Hermes, Claude, etc.), the host already injects MCPBASKET_STORE_PATH via its MCP server configuration — the .env is only a convenience for running the viewer directly during development.

3. Start the local viewer

npm run viewer

The viewer reads MCPBASKET_STORE_PATH from the environment. If not set, it falls back to .env in the repo root, then to $CWD/.mcpbasket/basket.json.

Open http://127.0.0.1:4377/health and expect { "ok": true }.

Optional: route viewer refinements back to Hermes

The viewer always persists the entered refinement prompt and the full source-search snapshot before dispatching anything. To make the local viewer launch a Hermes one-shot run automatically, configure the viewer process with the absolute Hermes command:

export MCPBASKET_REFINEMENT_HERMES_COMMAND="$(command -v hermes)"

With that opt-in setting, a refinement starts hermes --oneshot in the background. The spawned agent receives only a refinement id, then loads the stored user prompt and immutable source snapshot through MCP before it creates a linked new search. Leave the variable unset to keep requests queued for an agent to recover with basket-list-refinement-requests.

4. Register the MCP server with the agent

Use the built entrypoint and repeat the same environment values, especially MCPBASKET_STORE_PATH:

{
  "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"
      }
    }
  }
}

The JSON is a standard MCP example. Replace both absolute paths. For Hermes, use the ready-to-copy YAML in docs/HERMES.md.

OpenClaw installation

OpenClaw stores outbound MCP servers in its own registry and installs local skills into the active agent workspace. Build MCPBasket first, then register the built stdio server with absolute paths:

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"
  }
}'

Install the local skill for the active OpenClaw agent, then verify both registrations:

openclaw skills install "$(pwd)/skills/mcpbasket" --as mcpbasket
openclaw mcp list
openclaw skills info mcpbasket
openclaw skills check

Run the skill command from the intended agent workspace, or add OpenClaw's --agent <id> option to target a specific agent. The viewer remains a separate local process: configure the same absolute MCPBASKET_STORE_PATH in .env, then run npm run viewer. See the OpenClaw MCP reference and skills reference for registry and workspace behavior.

5. Install the agent skill

Install or symlink the complete skills/mcpbasket directory into the host agent's skill directory, then restart the agent. For a local skill directory, the command is typically:

mkdir -p /path/to/agent/skills
ln -s "$(pwd)/skills/mcpbasket" /path/to/agent/skills/mcpbasket

The agent must load this SKILL.md; the MCP tools alone do not tell it when to create a search, verify a source, or add a product to the Main basket. After installing, use the agent's skill-list command to confirm mcpbasket is enabled.

The skill requires the agent to:

1. Call basket-set-context with startNewSearch: true for each new research response.

2. Verify the direct product page before storing it in product.urls.product.

3. Save the image only when it loads and belongs to that product.

4. Keep failed links as evidence and mark the candidate needs_review rather than exposing a broken source.

5. Add to the Main basket only after an explicit user choice.

6. When processing a refinement, load its persisted request first and create a linked new search instead of modifying the original search.

6. Smoke test

Use the MCP host's connection test, then ask the agent to research a product. Confirm that:

• A search appears in /searches with its timestamp and candidate count.

• A verified product source opens in the viewer.

• Adding a product appears in /basket and survives a viewer restart.

• A compatible agent can process a queued refinement request without altering the original snapshot.

The viewer is loopback-only by default. It is an MVP inspection surface, not a public sharing service. A private-network setup can bind to a private interface and set a matching MCPBASKET_VIEWER_URL; authentication, public sharing, and payments remain out of scope.

Integrations

• MCP server package

• Hermes installation

• HTTP API contract

• Planned remote service

• Agent skill

• Prompt construction for agents

• Contributing

Quality Gates

npm run build
npm run test
npm run verify