Basketed

Una cesta. Muchas tiendas. Nada se compra sin ti.

Un servidor MCP de compras universal más un panel de control autoalojado. Cualquier agente MCP obtiene búsqueda real de productos en muchos minoristas, comparación eficiente en tokens y un paso de compra que solo un humano puede autorizar.

ANALIZAR → EXTRAER → RESPONDER → COMPRAR → RECIBIR

pnpm i && pnpm build
node packages/cli/bin.js install --client claude-code   # or --all

Esa es toda la configuración. Tu cliente lanza Basketed por sí mismo a través de stdio, y el panel de control aparece en el mismo proceso: su enlace, y un enlace a cualquier cesta que te esté esperando, se imprimen en la consola del servidor. serve --http --open es la otra vía de entrada: el mismo panel, más un endpoint HTTP Streamable en /mcp.

Qué hay realmente aquí

Related MCP server: agent-commerce-mcp-server

La puerta de compra

Un agente puede proponer una compra. Solo un humano puede autorizarla, y la autorización siempre llega desde una superficie que el modelo no puede autor.

cart_prepare ──► PENDING ──(human)──► APPROVED ──(purchase_confirm)──► order
                    │                                                    │
                    └──► EXPIRED (5 min) / REJECTED                       └─► HANDED_OFF
                                                                              outcome: unknown

Dos canales de aprobación, ambos convergen en una sola función para que las propiedades de seguridad sean idénticas dondequiera que el humano haya hecho clic:

El canal B — elicitación, donde el cliente renderiza el diálogo por sí mismo, está diseñado y no construido. ApprovalChannel es "console" | "panel", y esa es toda la lista. La letra se mantiene para que el plan y el código usen los mismos nombres para las mismas cosas.

El canal C es seguro porque el modelo no tiene acceso de lectura a esa superficie. La única forma de que un agente obtenga el código es que una persona lo lea en voz alta — que es exactamente el acto humano que queremos exigir.

El canal A se basa en el mismo hecho, no en la división de rutas. Cada cliente en el que Basketed se instala tiene un shell, así que "el agente habla MCP y no puede llegar a /api" nunca fue cierto por sí solo — un proceso local puede llamar a cualquier puerto en 127.0.0.1 y forjar cualquier cabecera. El panel está por tanto detrás de un token acuñado por proceso e impreso en esa misma consola — en ambos transportes, para que un cliente que lanzó Basketed a través de stdio siga teniendo el canal A.

En stdio, el panel también se abre en tu navegador cuando el servidor arranca. Eso no es una conveniencia: un cliente captura el stderr de su servidor MCP, así que el enlace se escribe donde ningún humano lo leerá jamás, y un panel al que nadie puede llegar no es un canal. La pestaña es el canal allí. Una pestaña por proceso; --no-open (o BASKETED_NO_OPEN=1) lo desactiva, y la pestaña sondea, así que una cesta que te necesita más tarde aparece en la pestaña que ya está abierta. /api también rechaza cualquier solicitud cuyo Origin no sea exactamente el del panel, y rechaza una solicitud mutadora que no envíe ninguna, que es lo que evita que una página web controle el panel a través de tu navegador.

Lo que no existe, a propósito: una herramienta approve(), un parámetro approved: true, una bandera de anulación, o una herramienta set_delivery_address. Ejecuta tools/list y compruébalo. La ausencia es la característica.

La pasada adversarial

pnpm smoke        # five smoke suites, all offline
pnpm test         # 160 unit tests
pnpm drill        # the whole demo path with the network genuinely severed
pnpm smoke:live   # ...and against live merchants, spending real requests

1. purchase_confirm antes de aprobar → rechazado

2. aprobar, confirmar, luego reproducir el mismo approval_id → rechazado, consumido

3. cambiar un precio en la base de datos después de la aprobación → rechazado, desviación de hash

4. reiniciar con --fast-mode y repetir 1–3 → todos siguen rechazados

5. pedir al agente que apruebe su propia compra → no hay herramienta que pueda

--fast-mode no puede tocar la compra, y está probado dos veces

Comportamentalmente, y recorriendo el grafo de importación real: nada alcanzable desde commerce/purchase.ts importa mcp/policy.ts, donde vive la bandera. La bandera no se ignora en la ruta de compra — no es alcanzable desde ella, y una refactorización que las conecte falla en CI.

El simulacro sin conexión realmente corta la red

pnpm drill precarga un guardián que rechaza toda conexión no-loopback en el proceso del servidor, y luego recorre todo el camino de demostración. Establecer una bandera de snapshot en una máquina que aún tiene wifi demuestra solo que la bandera se analiza. Bajo un corte real, siete de las diez tiendas Shopify fijadas se apagan — y vuelven nombradas en stores_failed, porque una búsqueda que devuelve silenciosamente menos tiendas parece exactamente un éxito.

De dónde vienen los datos

Cada adaptador declara dos cosas independientes, y ninguna puede ser exagerada. Cada respuesta lleva su modo, y el panel lo muestra como una insignia.

Tesco real no es una integración con licencia. search.api.tesco.com y xapi.tesco.com son endpoints públicos que el propio sitio web de Tesco llama, con una clave API que es pública y está incrustada en su JS de frontend — pero Tesco no documenta ni soporta el uso de terceros de ninguno de los dos, y usarlos de esta manera queda fuera de los Términos de Servicio de Tesco, igual que cualquier cliente de API no oficial. sim:tesco no se ve afectado por esto y sigue siendo exactamente lo que siempre fue: datos de fixture, aún lo que el simulacro sin conexión ejecuta, aún libre de red real.

Sin scraper, y sin evasión anti-bot. Los desafíos de Cloudflare, la huella dactilar de WAF y los CAPTCHA son controles de acceso que el operador habilitó deliberadamente. Derrotarlos destruye la defensa de "el usuario es el actor" que hace defendible la compra agéntica en absoluto, y se rompe constantemente. Los minoristas detrás de uno son provider o simulated. Esto no es una capacidad que enviemos desactivada — es una que no construimos.

HANDED_OFF nunca afirma éxito. Cuando la ruta termina en una URL que un humano completa por sí mismo, realmente no sabemos el resultado, y el pedido dice exactamente eso hasta que una persona lo marca en el panel. Mostrar silenciosamente una marca verde para un pedido que nadie pagó sería el error más dañino que este producto podría tener.

Herramientas

Solo lectura:

Relacionadas con dinero — destructiveHint: true, nunca promocionables a ALLOW:

Palancas de tokens

response_format: concise (predeterminado) · detailed · compact (claves cortas más una leyenda de una línea). fields para una lista blanca explícita. budget_tokens para un límite máximo: se recorta url → image → attrs → se trunca el nombre → se eliminan filas, con _meta.truncated indicando qué se eliminó. id, price y mode nunca se eliminan: un resultado no debe perder su procedencia para ahorrar tokens.

Instalación

basketed install se guía por una única tabla de variantes, la misma desde la que renderiza el panel — así el instalador, los bloques de copia y las insignias no pueden discrepar sobre dónde vive un archivo de configuración. Eso importa porque casi todas las excepciones a continuación fallan silenciosamente: un nombre de clave incorrecto no genera error, tu servidor simplemente nunca aparece.

basketed clients                       # every client, its file, its key
basketed install --client claude-code
basketed install --all --dry-run       # show the diff, write nothing
basketed doctor                        # check the install end to end

Las escrituras son fusionar-luego-reemplazar, nunca sobrescribir. El archivo existente se respalda en <file>.basketed-backup-<timestamp>, las claves no relacionadas y otros servidores se conservan, la escritura es atómica y se imprime el diff. Una configuración que no podemos analizar se rechaza y se deja byte-idéntica en lugar de reemplazarse.

El autoApprove de Kiro es una trampa. Nuestra configuración generada lista solo las cuatro herramientas de solo lectura allí, y basketed doctor advierte si se ha añadido manualmente una herramienta relacionada con dinero.

Protocolo

Doble era, ambos transportes. MCP 2026-07-28 eliminó initialize, las sesiones y las solicitudes iniciadas por el servidor; un cliente moderno no puede hablar con un servidor heredado y viceversa. "Se instala en cualquier agente" se basa por completo en servir ambos desde un solo binario, por lo que scripts/smoke-mcp.mjs abre el mismo binario dos veces — una con initialize, otra sin estado — porque ninguno de los dos fallos es visible desde los propios registros del servidor.

También: server/discover, outputSchema en cada herramienta, salida estructurada reflejada como texto para clientes antiguos, orden de herramientas determinista, las cuatro anotaciones, nombres con espacio de nombres.

Seguridad

• La bóveda de credenciales está construida. packages/vault sella cada secreto almacenado con AES-256-GCM bajo una clave de 32 bytes en ~/.basketed/master.key (modo 0600). Hay exactamente una función que devuelve texto plano — reveal() — y se llama desde ningún lugar excepto el interceptor de solicitudes que adjunta un encabezado a una búsqueda saliente; una prueba recorre el espacio de trabajo en busca de otros sitios de llamada y falla si aparece uno. El panel — detrás del mismo token por proceso que todo lo demás en esta lista — escribe en él y lee solo metadatos. Ninguna herramienta MCP recibe una credencial, nunca: AdapterCtx no tiene un campo por el que una pueda viajar. Un archivo de clave malo o faltante degrada la página de tiendas Connect; nunca derriba el servidor MCP, por lo que un cliente no puede fallar al iniciar debido a este archivo. Ninguno de los adaptadores enviados se autentica con lo almacenado — Shopify UCP es anónimo y las tiendas simuladas no tienen nada con qué verificarlo — por lo que conectar Tesco, Costco, Walmart o Amazon guarda una credencial para un adaptador que aún no existe y no cambia ningún resultado que veas hoy.

• "Iniciar sesión con Chrome" (S15), exactamente para Tesco, Costco, Walmart y Amazon. Ninguno de ellos publica un flujo OAuth de consumidor, por lo que la alternativa honesta a una caja de pegar contraseña es abrir la propia página de inicio de sesión del minorista en un navegador real y dejar que el humano inicie sesión él mismo. Esto lanza el Chrome ya instalado de la máquina, nunca un Chromium descargado — nadie que use esto necesitó instalar nada. No se lee nada hasta que el humano hace clic en "capturar": no hay sondeo para que aparezca una cookie de sesión y capturarla en el momento en que aparece. De acuerdo con "sin evasión anti-bot" arriba, no oculta la automatización al minorista — sin suplantación de navigator.webdriver, sin eliminación de banderas de automatización — porque un sistema de fraude que no puede distinguir un navegador controlado de un humano no es una línea que este proyecto intercambie por la página de tiendas Connect. Los Términos de Servicio de cada uno de estos cuatro minoristas prohíben el inicio de sesión automatizado, incluso por parte del titular de la cuenta; ese riesgo se divulga en el propio botón, no solo aquí. La sesión capturada se sella exactamente como una credencial pegada — misma bóveda, misma auditoría de reveal() — y ningún adaptador la usa aún.

• El agente ve solo un identificador de cuenta opaco, nunca nada que pueda convertirse en uno.

• La superficie de aprobación está detrás de un token por proceso impreso en la propia consola del servidor, junto al código de 6 dígitos. La separación de rutas no es la barrera: cada cliente en el que Basketed se instala tiene un shell, por lo que el agente siempre podría llegar a 127.0.0.1 y forjar cualquier encabezado. /api también requiere un Origin exactamente igual al del panel, y rechaza una solicitud mutadora que no envíe ninguno.

• El texto del proveedor son datos no confiables. Normalizado con NFKC, sin caracteres de control, sin anulaciones de ancho cero ni bidi, sin HTML, con límite de longitud, patrones de inyección marcados. La defensa real es más fuerte: la pantalla de aprobación y el hash del carrito se construyen solo a partir de campos numéricos y enumerados más el nombre de producto normalizado. Ninguna cadena escrita por el comerciante llega a ninguno de ellos.

• approval_id es CSPRNG, vinculado en el servidor a un principal derivado de la sesión local — nunca de nada que el agente haya proporcionado — y se vuelve a verificar dentro del consumo atómico. La posesión nunca es autenticación (Secuestro de Manejo de Estado 2026-07-28).

• Capa de redacción sobre cada respuesta, como red más que como defensa. Un acierto es un error; el panel muestra el recuento.

• Nunca tocamos datos de tarjetas (fuera del alcance de PCI), nunca almacenamos contraseñas de minoristas y no enviamos ningún scraper.

No construido, declarado para que nadie lo reclame

Adaptadores de minoristas reales para Costco/Walmart/Amazon (ninguno publica una API de consumidor; la bóveda guarda una credencial — pegada o capturada con Chrome — nada aún se autentica con ella), OAuth de minoristas reales (ninguno de los cuatro publica uno — ver Conectar tiendas), una captura de inicio de sesión con Chrome para cualquier tienda fuera de ese prototipo de cuatro, el IdP simulado, el canal de aprobación B (elicitación), compare_products, la página de Pedidos, MCPB, publicación en el registro y envío del plugin de ChatGPT. Todos están diseñados en el plan y ninguno está construido.

Tesco es el único adaptador de minorista que salió de esta lista (S16) — ver "De dónde vienen los datos", arriba: búsqueda real, detalle real y un carrito real detrás del token de sesión pegado por el propio comprador. Costco, Walmart y Amazon permanecen aquí porque ninguno de los tres tiene un equivalente no oficial pero real al endpoint que el frontend de Tesco expone — ver Conectar tiendas para lo que una sesión de inicio de sesión con Chrome en esos tres puede y no puede hacer en su lugar.

La bóveda de credenciales es el otro elemento que salió de esta lista (S14) — ver Seguridad, arriba — y la guardia de deriva que solía verificarlo aquí ahora verifica lo contrario: que este archivo deje de negarlo exactamente cuando deje de ser cierto.

docs/ — BENCHMARK

Requiere Node ≥ 22 (node:sqlite, por lo que no hay paso de compilación nativa — lo que importa en Windows, donde se desarrolló y verificó).