cookie-mcp

cookie-mcp

Un servidor de Model Context Protocol (MCP) que brinda a cualquier agente de IA herramientas onchain para la cadena de bloques Cookie Chain: leer el mercado, intercambiar, lanzar tokens, gestionar liquidez, hacer staking, comerciar NFTs y hacer puente a Solana.

Se ejecuta localmente a través de stdio y firma con tu clave en tu máquina, por lo que no es de custodia por diseño. Es un proyecto comunitario para todo el ecosistema de Cookie Chain.

Contenido

• Qué puede hacer
• Instalación — Claude Code · Claude Desktop · Cursor
• Habilitar trading (añadir una clave)
• Pruébalo
• Configuración
• Herramientas
• Seguridad
• Desarrollo

Qué puede hacer

• Leer el mercado — salud de la cadena, pools, información de tokens, búsqueda de tokens, cotizaciones de swap y saldos de carteras. No se necesita clave.
• Intercambiar cualquier par de tokens de Cookie Chain a través del agregador Candy Shop, que enruta a través de toda la liquidez DEX de Cookie Chain para obtener el mejor precio.
• Transferir COOK o cualquier token SPL / Token-2022.
• Lanzar tokens en el launchpad MomoSwap — crear un token en una curva de vinculación de COOK, comprar/vender la curva, reclamar después de la graduación y recoger tus comisiones de creador.
• Gestionar liquidez — crear pools, añadir/eliminar liquidez, reclamar comisiones y bloquear posiciones permanentemente en Cookiebox DAMM v2, Cookiebox CLMM y CookieSwap SAMM (lugar auto-detectado).
• Staking líquido de COOK por bCOOK y canjearlo al instante.
• Comerciar NFTs en Baked Bazaar — buscar, explorar, comprar, listar y hacer/aceptar ofertas (el mercado de Metaplex Auction House de Cookie Chain).
• Puente de COOK 1:1 entre Cookie Chain y Solana mainnet a través de Hyperlane.
• Poseer un nombre — registrar, transferir y resolver nombres .cook en el servicio de nombres CookOven, y usarlos en cualquier lugar donde se espere una dirección (transfer to: "bot.cook").

Seguro por defecto: solo lectura hasta que añadas una clave, y cada acción que mueve dinero se simula antes de enviarse.

Instalación

Requiere Node ≥ 22. No hay nada que instalar o compilar — npx obtiene el paquete publicado en la primera ejecución. Elige tu cliente a continuación. Los tres usan el mismo servidor; la única diferencia es dónde vive la configuración.

Claude Code

La forma más rápida — un comando, disponible en todos los proyectos:

claude mcp add --scope user --transport stdio cookie-mcp -- npx -y cookie-mcp

Esto registra el servidor en modo solo lectura (sin clave). Consulta Habilitar trading para añadir una cartera.

Ámbitos — claude mcp add escribe en uno de tres lugares; elige con --scope:

--scope	Disponible en	Almacenado en
user	todos tus proyectos	~/.claude.json
(omitido) local	el directorio del proyecto actual	~/.claude.json (por carpeta)
project	cualquiera que clone un repositorio	.mcp.json en la raíz del repositorio

Usa --scope project solo cuando quieras que el servidor se comprometa en un repositorio específico — escribe un .mcp.json que los compañeros deben aprobar en el primer uso. Para una herramienta de propósito general como esta, --scope user es el valor predeterminado correcto.

Verifica que se registró:

claude mcp list          # all servers
claude mcp get cookie-mcp # this one's details
# or run /mcp inside a Claude Code session

Claude Desktop

Edita el archivo de configuración (créalo si falta), luego reinicia Claude Desktop:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Añade el bloque de servidor a continuación bajo mcpServers.

Cursor

Edita ~/.cursor/mcp.json (aplica en todas partes) o .cursor/mcp.json en un proyecto (el proyecto gana si ambos existen), luego añade el bloque de servidor.

Bloque de servidor

Claude Desktop, Cursor y un .mcp.json de Claude Code usan la misma forma idéntica:

{
  "mcpServers": {
    "cookie-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cookie-mcp"],
      "env": {
        "COOKIE_RPC_URL": "https://rpc.cookiescan.io",
        "COOKIE_PRIVATE_KEY": ""
      }
    }
  }
}

Habilitar trading (añadir una clave)

Las lecturas funcionan sin clave. Para permitir que el agente intercambie, transfiera, lance, haga staking, LP, compre NFTs o haga puente, proporciona una cartera a través de COOKIE_PRIVATE_KEY — un secreto base58, un solana-keygen JSON de bytes, o una ruta a un archivo de par de claves.

• Clientes con archivo de configuración (Desktop / Cursor / .mcp.json): colócalo en el bloque env anterior.

• Claude Code: vuelve a ejecutar el comando con --env (nota: esto se guarda en ~/.claude.json; evita dejar el secreto en bruto en tu historial de shell):

  claude mcp add --scope user --transport stdio cookie-mcp \
    --env COOKIE_RPC_URL=https://rpc.cookiescan.io \
    --env COOKIE_PRIVATE_KEY=<your-key-or-path> \
    -- npx -y cookie-mcp
  

Tu clave nunca sale de tu máquina, se usa solo para firmar localmente y se redacta de todas las salidas. Cada acción que mueve dinero se simula antes de enviarse.

Pruébalo

Una vez registrado, simplemente habla con tu agente de forma natural:

• "¿Cuál es la salud de Cookie Chain ahora mismo?" → chain_health
• "Encuentra el token cookhouse y muéstrame su precio y liquidez." → search_tokens → get_token_info
• "Cotiza el intercambio de 10 COOK por bCOOK." → get_quote
• "Intercambia 10 COOK por bCOOK." → get_quote → trade (necesita una clave; simulado primero)
• "¿Qué NFTs de COOKHOUSE están listados, y compra el más barato por menos de 50 COOK?" → search_nfts → buy_nft
• "¿Desde qué cartera estás a punto de operar?" → get_wallet

El agente resuelve nombres a direcciones de mint con search_tokens / search_nfts, y luego actúa sobre el mint — nunca convierte un nombre directamente en una operación.

Configuración

Variable	Predeterminado	Propósito
COOKIE_RPC_URL	https://rpc.cookiescan.io	RPC de Cookie Chain.
COOKIE_PRIVATE_KEY	—	Clave de cartera para herramientas que mueven dinero. Solo lectura si no se establece.
COOKIE_SLIPPAGE_BPS	500	Slippage predeterminado (bps).
SOLANA_RPC_URL	https://api.mainnet-beta.solana.com	RPC de Solana mainnet (solo puente).
COOKIE_REFERRER	mcp treasury	Cartera de referencia (solo MomoSwap).

Herramientas

Lecturas (sin clave): chain_health, get_pools, get_token_info, search_tokens (resolver un nombre/ticker de token a su mint), get_quote, get_wallet (qué clave firma este servidor y el RPC que usa — sin llamada RPC, por lo que funciona cuando la cadena está caída), get_balance, stake_info (tasa de staking líquido bCOOK / TVL / APY / comisiones), lecturas del launchpad get_launchpad_pools / get_launchpad_token / get_launchpad_positions, y lecturas de NFT get_nft_listings, search_nfts (resolver un nombre de NFT/colección a un mint listado), get_nft, get_wallet_nfts, get_nft_offers, get_nft_market_stats, y lecturas de nombres .cook resolve_domain / get_owned_domains / get_domain_listings.

Dinero (necesita COOKIE_PRIVATE_KEY): trade (swap a través de Candy Shop), transfer (COOK o cualquier token), stake / unstake (staking líquido COOK ⇄ bCOOK).

Launchpad (necesita COOKIE_PRIVATE_KEY, MomoSwap): deploy_token lanza un token en una curva de vinculación de COOK (un logo es obligatorio — pasa imageBase64 y se fija a IPFS, o establece noLogo: true para lanzar sin uno; los metadatos son inmutables, por lo que no se puede añadir un logo más tarde. Cuesta la tarifa de creación del launchpad, leída de su configuración en el momento de la llamada, más cualquier devBuyCook), launchpad_buy / launchpad_sell operan esa curva, claim_launchpad liquida una posición (el token SPL real después de la graduación, un reembolso en modo Fair, o un pago de Jackpot/Survivor), y claim_creator_fees recoge la parte del creador de las comisiones de trading de un lanzamiento que creaste.

⚠️ Antes de la graduación, las tenencias son participaciones de curva rastreadas por programa, no tokens SPL — no aparecen en get_balance y trade no puede enrutarlas. Sal con launchpad_sell, o reclama el token real con claim_launchpad una vez que el pool se gradúe; a partir de entonces se negocia como cualquier otro token.

Debido a que esas participaciones son invisibles para get_balance, get_launchpad_positions es la vista de cartera: cada lanzamiento en el que una cartera tiene una posición, cuánto vale en una curva en vivo y qué no se ha reclamado (tokens después de la graduación, un reembolso en modo Fair, un pago de liquidación, comisiones de creador o vesting). Lee las cuentas UserPosition directamente de la cadena en lotes, por lo que cuesta aproximadamente un viaje de ida y vuelta RPC por cada 100 lanzamientos. Pasa owner para cualquier cartera, u omítelo para la tuya.

Un token pre-graduación tampoco tiene ningún pool DEX, por lo que get_quote / trade simplemente informarían "sin ruta". Ahora reconocen ese caso y apuntan a las herramientas del launchpad en su lugar, y get_token_info añade un campo launchpad cuando un mint no muestra precio o liquidez porque todavía está en una curva.

Liquidez (necesita COOKIE_PRIVATE_KEY): create_pool, add_liquidity, remove_liquidity, claim_fees (Cookiebox DAMM v2, Cookiebox CLMM y CookieSwap SAMM, lugar auto-detectado), lock_liquidity (Cookiebox DAMM v2 y Cookiebox CLMM, permanente e irreversible — CLMM bloquea toda la posición; las comisiones siguen siendo reclamables de cualquier manera). Los lugares de liquidez concentrada (CLMM / SAMM) abren una posición de rango completo por defecto.

Mercado de NFT (necesita COOKIE_PRIVATE_KEY, Baked Bazaar): buy_nft, list_nft, cancel_listing, make_offer, accept_offer, cancel_offer. Construido sobre el Metaplex Auction House de Cookie Chain (1% de tarifa de mercado + regalías de creador); cada acción se construye y firma localmente.

Puente (necesita COOKIE_PRIVATE_KEY): bridge mueve COOK 1:1 entre Cookie Chain y Solana mainnet a través de la ruta warp de Hyperlane (direction = cookie-to-solana | solana-to-cookie). Una firma de la cadena de origen envía la transferencia; un relayer la entrega en el lado lejano en unos minutos — verifica con bridge_status (una lectura, por id de mensaje de Hyperlane). El COOK nativo de Cookie tiene 9 decimales; el COOK de Solana es un mint Token-2022 de 6 decimales — las cantidades están en COOK de cualquier manera. Simula primero. Los ids de programa de la ruta warp de mainnet se envían como predeterminados, por lo que bridge funciona de fábrica — anula COOKIE_WARP_PROGRAM_ID / SOLANA_WARP_PROGRAM_ID solo para un despliegue diferente.

Nombres .cook (CookOven): resolve_domain busca un nombre — propietario, fecha de registro, punteros de resolver/metadatos — o lo informa como disponible con el precio en vivo; get_owned_domains lista cada nombre que una cartera posee y cuál es su principal. Las escrituras necesitan COOKIE_PRIVATE_KEY: register_domain, set_primary_domain (o clear: true para desactivar), transfer_domain, update_domain. Todo se lee y construye directamente del registro en cadena — sin API, sin indexador. El sufijo es opcional en todas partes: chef y chef.cook son el mismo nombre.

Una vez que posees un nombre, puedes usarlo en lugar de una dirección: transfer, get_balance, get_wallet_nfts, get_nft_offers, get_launchpad_positions y transfer_domain aceptan un nombre .cook en cualquier lugar donde tomen una cartera de Cookie Chain. Una dirección base58 simple no cuesta una búsqueda adicional. .cook mercado de dominios (CookOven Marketplace): el mercado secundario para nombres que ya están registrados — a menudo más barato que el registro de 15,000–35,000 COOK, y la única forma de obtener un nombre que alguien más ya posee. get_domain_listings lo navega sin clave (filtrar por name, seller, maxPriceCook o maxLength; ordenar por precio, longitud o antigüedad) y reporta la tarifa del mercado en vivo, que el vendedor paga del precio de venta. Las escrituras necesitan COOKIE_PRIVATE_KEY: list_domain (precio de venta en COOK), buy_domain, cancel_domain_listing. Lectura y construcción directa desde el programa — sin API, sin indexador.

⚠️ El listado pone el nombre en custodia. list_domain entrega el dominio a la cuenta de custodia del mercado en la misma instrucción, por lo que mientras está listado, el registro reporta la custodia como su propietario: el vendedor no puede transfer_domain, update_domain ni set_primary_domain sobre él, y deja de resolverse a una dirección de pago. Esas herramientas lo dicen explícitamente en lugar de reportar a un extraño como propietario, y pasar un nombre listado donde se espera una dirección es rechazado — la custodia es una cuenta de programa, por lo que pagarle dejaría los fondos varados. cancel_domain_listing revierte un listado en cualquier momento y reembolsa su alquiler. No hay instrucción de re-precio: cancela y luego lista de nuevo.

buy_domain requiere maxPriceCook por la misma razón que register_domain — la instrucción no lleva argumento de precio, por lo que ese límite es la única protección. Sin él, obtienes el precio de venta citado de vuelta y no se gasta nada.

Usa el mint nativo COOK / So11111111111111111111111111111111111111112 para COOK. Cada herramienta devuelve JSON; los fallos devuelven { error, hint } — nunca un stack trace, nunca tu clave.

Seguridad

No custodial y local: sin servidor alojado, sin almacenamiento remoto de claves. La clave permanece en COOKIE_PRIVATE_KEY, firma localmente y se redacta de toda salida. Solo lectura hasta que se establezca una clave; cada acción que mueve dinero se simula antes de enviarse.

Desarrollo

yarn install
yarn test    # lint + format + typecheck + unit tests + boot smoke
yarn mcp     # run the server on stdio from source (tsx)
yarn build   # bundle to dist/mcp/server.js (what gets published)

Para apuntar un agente a un checkout local en lugar del paquete publicado, establece el comando a npx tsx /ABS/PATH/cookie-mcp/src/mcp/server.ts.

Licencia

Este proyecto está licenciado bajo los términos de la licencia MIT. Consulta el archivo LICENSE.