# MCPBasket

MCPBasket is a local-first product research workspace for agents. Every research response becomes a durable search with product snapshots and verified sources. Users can compare searches and add selected products to one persistent Main Basket without purchasing anything.

The public core is provider-neutral. It does not store payment credentials, authenticate to merchants, or place orders.

## Install

MCPBasket ships as an npm package and as an [Agent Plugin 1.0](https://agent-plugins.org/) bundle containing both the skill and MCP configuration.

```bash
npx -y --package mcpbasket@0.2.0 mcpbasket-setup --host codex
```

Replace `codex` with `vscode`, `cursor`, `claude`, `hermes`, `openclaw`, or `generic`. The setup command:

- installs the correct skill or agent rule for the selected host;
- registers the stdio MCP server when the host exposes a supported CLI or config file;
- creates private persistent storage under `~/.mcpbasket`;
- starts the local viewer automatically whenever the MCP server starts.

Restart the agent host after setup. The viewer is available at [http://127.0.0.1:4377](http://127.0.0.1:4377) after the host starts MCPBasket.

See [installation by host](docs/INSTALLATION.md) for VS Code, Cursor, Codex, Claude, Hermes, OpenClaw, servers, containers, and Tailscale.

## Agent Workflow

1. The skill routes product research and comparison requests to MCPBasket.
2. The agent creates a saved search and records structured product candidates.
3. Direct product links and images are validated before being exposed as verified sources.
4. The user reviews searches in the local viewer.
5. Explicit selections are copied to the persistent Main Basket.
6. Approved items can be exported as neutral checkout line items for a separately installed integration.

The MCP tools never authorize or execute a purchase.

## Surfaces

| Surface | Purpose |
|---------|---------|
| `/` | Current research and product candidates |
| `/searches` | Durable search history |
| `/basket` | Main Basket across all searches |
| MCP stdio server | Agent tools and persistent state |
| Agent skill | Routing, data quality, and approval rules |

## Configuration

```bash
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
MCPBASKET_START_VIEWER=true
```

The store path must be absolute. The MCP server starts the viewer by default; set `MCPBASKET_START_VIEWER=false` only when running `mcpbasket-viewer` separately.

For private access from another device, keep the viewer bound to localhost and proxy it with Tailscale Serve. Do not expose the unauthenticated local HTTP API to the public internet.

## Development

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

The verification suite builds the MCP server, runs deterministic tests, packs the exact npm artifact, installs it into a temporary clean project, and validates the bundled skill and plugin manifests.

## Documentation

- [Installation by host](docs/INSTALLATION.md)
- [Architecture](docs/ARCHITECTURE.md)
- [HTTP API](docs/HTTP-API.md)
- [Product model](skills/mcpbasket/references/product-model.md)
- [Agent prompting](skills/mcpbasket/references/prompting.md)
- [Remote service research](docs/REMOTE-SERVICE-RESEARCH.md)
- [Remote service boundary](docs/REMOTE-SERVICE.md)

## License

MIT