MCPBasket

MCPBasket is a local-first pre-purchase workspace for agents. It gives an agent a neutral basket in which to collect, compare, review, and prepare product candidates before a human-approved checkout handled by another integration.

It never creates an order.

Packages

Path	Responsibility
packages/mcp-basket	Domain model, application service, MCP adapter, local HTTP API, JSON store, and local viewer.
skills/mcpbasket	Agent workflow for researching and recording product candidates.

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.

Quick Start

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

Start the local viewer/API:

npm run viewer

Run the MCP server:

npm run mcp

The local viewer command prints the loopback URL for the machine running the agent. It is the MVP inspection surface; it is not a public sharing mechanism.

Integrations

• MCP server package
• Hermes installation
• HTTP API contract
• Planned remote service
• Agent skill
• Contributing

Quality Gates

npm run build
npm run lint
npm run test
npm run verify