cookie-mcp

Um servidor MCP que dá aos agentes de IA acesso onchain completo ao Cookie Chain — trade, launch, LP, stake e bridge para Solana.

GitHub
4
Experimente este MCPPatrocinado

Documentação

cookie-mcp

npm version npm downloads MCP Registry MCP Servers CI node license

Um servidor Model Context Protocol (MCP) que dá a qualquer agente de IA ferramentas onchain para a blockchain Cookie Chain — leia o mercado, faça swap, lance tokens, gerencie liquidez, faça staking, negocie NFTs e faça bridge para Solana.

Ele roda localmente via stdio e assina com sua chave na sua máquina, portanto é não-custodial por design. Para aplicativos hospedados (um chat web, um bot atrás de um site) ele roda em modo assinante externo: o servidor não guarda chave, toda ação para na etapa de assinatura com uma transação verificada, e a carteira do próprio usuário no navegador assina — mesmas ferramentas, mesmas proteções (detalhes). É um projeto comunitário para todo o ecossistema Cookie Chain.

An AI agent using cookie-mcp: checking chain health, bridging COOK from Solana, buying COOKHOUSE, staking for bCOOK, and bridging back to Solana

Conteúdo

O que ele faz

  • Leia o mercado — saúde da chain, pools, informações de tokens, busca de tokens, cotações de swap e saldos de carteira. Nenhuma chave necessária.
  • Swap de qualquer par de tokens da Cookie Chain através de qualquer um dos agregadores — a Cookiebox Swap API ou Candy Shop — ambos roteando por toda a liquidez DEX da Cookie Chain. Agentes escolhem por chamada com o parâmetro aggregator e podem cotar ambos para comparar. chain: "solana" compra/vende o COOK com bridge na mainnet da Solana via Jupiter em vez disso.
  • Transferência de COOK ou qualquer token SPL / Token-2022.
  • Ordens de limite e stop no escrow de ordens limitadas da Cookiebox — take-profit a um preço ou melhor, ou um stop-loss que vende a mercado assim que a taxa cai para um gatilho — preenchidas por um keeper em todos os mercados roteáveis da Cookie Chain.
  • Lançamento de tokens no MomoSwap launchpad — crie um token em uma curva de bonding de COOK, compre / venda a curva, reivindique após a graduação e recolha suas taxas de criador.
  • Gerencie liquidez — crie pools, adicione / remova liquidez, reivindique taxas e bloqueie permanentemente posições em Cookiebox DAMM v2, Cookiebox CLMM e CookieSwap BAMM (venue auto-detectada).
  • Liquid-staking de COOK para bCOOK e resgate instantâneo.
  • Negocie NFTs no Baked Bazaar — pesquise, navegue, compre, liste e faça / aceite ofertas (o marketplace Metaplex Auction House da Cookie Chain).
  • Bridge de COOK, SOL — e qualquer token adicionado ao bridge depois — 1:1 entre Cookie Chain e mainnet da Solana via Hyperlane.
  • Tenha um nome — registre, transfira e resolva nomes .cook no serviço de nomes CookOven, e use-os em qualquer lugar onde um endereço seja esperado (transfer to: "bot.cook").

Seguro por padrão: somente leitura até você adicionar uma chave, e toda ação que movimenta dinheiro é simulada antes de ser enviada.

Instalação

Requer Node ≥ 22. Não há nada para instalar ou compilar — npx busca o pacote publicado no primeiro uso. Escolha seu cliente abaixo. Todos os três usam o mesmo servidor; a única diferença é onde a configuração fica.

Claude Code

A maneira mais rápida — um comando, disponível em todos os projetos:

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

Isso registra o servidor somente leitura (sem chave). Veja Ativar negociação para adicionar uma carteira.

Escopos — claude mcp add grava em um de três lugares; escolha com --scope:

--scopeDisponível emArmazenado em
usertodos os seus projetos~/.claude.json
(omitido) localo diretório do projeto atual~/.claude.json (por pasta)
projectqualquer um que clone um repositório.mcp.json na raiz do repositório

Use --scope project somente quando quiser o servidor commitado em um repositório específico — ele grava um .mcp.json que colegas de equipe devem aprovar no primeiro uso. Para uma ferramenta de propósito geral como esta, --scope user é o padrão correto.

Verifique se registrou:

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

Claude Desktop

Edite o arquivo de configuração (crie se estiver faltando) e reinicie o Claude Desktop:

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

Adicione o bloco do servidor abaixo em mcpServers.

Cursor

Edite ~/.cursor/mcp.json (aplica em todos os lugares) ou .cursor/mcp.json em um projeto (o projeto vence se ambos existirem) e adicione o bloco do servidor.

Bloco do servidor

Claude Desktop, Cursor e um .mcp.json do Claude Code usam todos a mesma 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": ""
      }
    }
  }
}

Ativar negociação (adicionar uma chave)

Leituras funcionam sem chave. Para deixar o agente fazer swap, transferir, lançar, fazer staking, LP, comprar NFTs ou bridge, forneça uma carteira via COOKIE_PRIVATE_KEY — um segredo base58, um solana-keygen JSON como array de bytes, ou um caminho para um arquivo de par de chaves.

  • Clientes com arquivo de configuração (Desktop / Cursor / .mcp.json): coloque no bloco env acima.

  • Claude Code: execute novamente o add com --env (nota: isso é salvo em ~/.claude.json; evite deixar o segredo bruto no seu histórico do 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

Sua chave nunca sai da sua máquina, é usada apenas para assinar localmente e é redigida de toda saída. Toda ação que movimenta dinheiro é simulada antes de ser enviada.

Experimente

Depois de registrado, basta conversar com seu agente naturalmente:

  • "Qual é a saúde da Cookie Chain agora?" → chain_health
  • "Encontre o token cookhouse e mostre-me seu preço e liquidez." → search_tokens → get_token_info
  • "Cote a troca de 10 COOK por bCOOK." → get_quote
  • "Troque 10 COOK por bCOOK." → get_quote → trade (precisa de chave; simulado primeiro)
  • Tokens Token-2022 com transfer-hook (código do emissor roda em toda transferência e pode rejeitá-la): get_quote sempre retorna warnings[] e trade retorna routeWarnings[] — uma entrada por mint com hook, com reviewed, title, detail. Leia detail antes de negociar. transfer lida com mints com hook; add_liquidity/create_pool no Cookiebox CLMM dividem a transação de open+deposit quando um mint com hook a estouraria, e create_pool recusa antecipadamente quando o mint ainda precisa de um Cookiebox TokenBadge.
  • "Quais NFTs COOKHOUSE estão listados, e compre o mais barato abaixo de 50 COOK." → search_nfts → buy_nft
  • "De qual carteira você está prestes a negociar?" → get_wallet

O agente resolve nomes para endereços de mint com search_tokens / search_nfts, e então age no mint — ele nunca transforma um nome diretamente em uma negociação.

Configuração

VariávelPadrãoPropósito
COOKIE_RPC_URLhttps://rpc.cookiescan.ioRPC da Cookie Chain.
COOKIE_PRIVATE_KEY—Chave da carteira para ferramentas que movimentam dinheiro. Somente leitura se não definida.
COOKIE_SIGNERlocalexternal = sem chave no processo; ferramentas retornam needs_signature para a carteira do usuário assinar.
COOKIE_WALLET_ADDRESS—Modo externo: carteira padrão quando uma requisição não traz cabeçalho x-cookie-wallet.
COOKIE_MCP_HTTP_PORT / _HOST / _PATH— / 127.0.0.1 / /mcpServir Streamable HTTP em vez de stdio (mesmo que --http [port]).
COOKIE_MCP_CORS_ORIGIN*Origem de navegador permitida para o servidor HTTP.
COOKIE_SLIPPAGE_BPS500Slippage padrão (bps).
COOKIE_REFERRERmcp treasuryCarteira de referência (somente MomoSwap).
SOLANA_RPC_URLhttps://api.mainnet-beta.solana.comRPC da Solana.
JUPITER_API_KEY—Opcional; senão Jupiter sem chave a 0,5 req/s.

Ferramentas

Leituras (sem chave): chain_health, get_pools, get_token_info, search_tokens (resolve um nome/ticker de token para seu mint), get_quote, get_wallet (com qual chave este servidor assina, e o RPC que ele usa — sem chamada RPC, então funciona quando a chain está fora), get_balance, stake_info (taxa de liquid-staking de bCOOK / TVL / APY / taxas), leituras do launchpad get_launchpad_pools / get_launchpad_token / get_launchpad_positions, e leituras de NFT get_nft_listings, search_nfts (resolve um nome de NFT/coleção para um mint listado), get_nft, get_wallet_nfts, get_nft_offers, get_nft_market_stats, e leituras de nomes .cook resolve_domain / get_owned_domains / get_domain_listings, e get_bridge_tokens (o que o bridge pode mover).

Dinheiro (precisa de COOKIE_PRIVATE_KEY): trade (swap via Cookiebox ou Cookiescan), transfer (COOK ou qualquer token, com um memo opcional escrito através do programa SPL Memo — a maneira de pagar uma fatura ou solicitação de pagamento que corresponde transferências por memo), stake / unstake (liquid-staking de COOK ⇄ bCOOK).

Ordens limitadas (Cookiebox escrow de ordens limitadas, programa L1M1tk…): get_limit_orders lista as ordens em repouso de uma carteira sem chave (a sua, ou qualquer endereço / nome .cook); place_limit_order e cancel_limit_order precisam de COOKIE_PRIVATE_KEY. Uma ordem trava a entrada em uma reserva de propriedade do programa; um keeper a preenche através do mesmo roteador que trade usa, então qualquer par com rota pode descansar como ordem, e paga a conta de saída fixada (preenchimentos parciais possíveis). Dois tipos:

  • limit (padrão) é um take-profit: preenche ao preço ou melhor. O preço deve estar acima da taxa atual.
  • stop é um stop-loss, stop-market: price é o gatilho, que deve estar abaixo da taxa atual; uma vez que a taxa executável cai para ele, o keeper vende a mercado e repassa os rendimentos. Um piso onchain oculto (50% abaixo do gatilho, floorPrice para sobrescrever) apenas limita o que uma chave de keeper comprometida poderia pagar — não é o que você recebe. A única taxa é a taxa do maker do programa, 10 bps no lançamento, deduzida de cada preenchimento e lida ao vivo da chain (fees em get_limit_orders). As ordens têm como padrão um prazo de uma semana (expiresInSeconds, 0 = boa até cancelar, máximo de um ano); uma ordem expirada ainda mantém seu insumo até ser cancelada. COOK nativo é envolvido dentro da colocação e reembolsado como COOK no cancelamento.

As ordens de curva do MomoSwap colocadas em cookiebox.app também aparecem em get_limit_orders: um curve-buy é uma ordem de custódia comum cujo preenchimento chega como cotas de curva (cancele-a aqui como qualquer outra); um curve-sell é uma autorização de venda de launchpad, não uma custódia — escrowed: false, as cotas permanecem utilizáveis e createdAt é nulo. cancel_limit_order a revoga: o agregador não tem cancel-tx para ela, então este servidor constrói o revoke_position_sale do launchpad por conta própria após ler a autorização da chain (de propriedade do launchpad, discriminador correto, sua carteira como proprietário), seguido pelo settle_curve_sell(close) do programa de ordens limitadas quando a ordem paga um cofre de venda de curva que ainda existe. O resultado diz revoked: true; nada é reembolsado porque nada foi retido.

place_limit_order também coloca ordens de curva, para o par COOK direto de um token ainda em sua curva (detectado a partir dos mints; limit apenas, sem stops). COOK → token torna-se um curve-buy: uma ordem de custódia comum cujo pagamento é sua posição de launchpad, preenchida pelo buy_for do keeper; a opção gratuita única de enable_buy_for é adicionada à primeira ordem quando sua carteira não a possui, e o minBuy da pool / limite por carteira são verificados para que uma ordem não preenchível seja recusada de antemão. Token → COOK torna-se um curve-sell: um approve_position_sale para o keeper do Cookiebox no seu piso, um por pool, pagando seu cofre de venda de curva — a conta wCOOK do programa de ordens limitadas para esta pool e carteira, criada na mesma transação. Cada preenchimento paga o cofre e o settle_curve_sell do programa o repassa para sua carteira como COOK nativo menos a taxa do maker de ordens limitadas (makerFeeBps, lida ao vivo; netAfterFee é o que você recebe no piso; payoutNative: true, nenhuma conta de token necessária). O piso é o próprio preço: precificado em P, a ordem preenche assim que a curva paga P e você recebe P menos a taxa, como uma ordem comum. O keeper recusa uma autorização que pague qualquer coisa além do cofre, então não há formato sem taxa para colocar. cancel_limit_order revoga a autorização e, enquanto o cofre ainda existir, também liquida e fecha-o, devolvendo ambos os aluguéis. Seu prazo é limitado ao próprio fim da venda: o launchpad limita uma autorização a 30 dias e nunca lê a pool, mas nenhum preenchimento é possível uma vez que o lançamento fecha, e um lançamento dura no máximo 7 dias — então expiresAt nunca está além de saleEndsAt, e o padrão de uma semana criaria uma ordem que mostra um prazo futuro e nunca pode preencher. Este servidor monta ambos os formatos por conta própria (o agregador os construiu desde 2026-09-22, mas uma construção local mantém os bytes assinados derivados do que lemos); a compra é então executada pelo mesmo verificador em nível de instrução que uma construção do agregador, e ambos são simulados antes da assinatura.

⚠️ O agregador constrói a transação; este servidor a verifica antes de assinar. Cada instrução é decodificada contra o IDL do programa e verificada — pagador de taxa, maker, valores, tipo, prazo, as contas fixadas de reembolso / pagamento, o PDA da ordem, e que apenas os cinco programas esperados são tocados (custódia, orçamento de computação, sistema, token, token associado). Uma construção que discorda da solicitação é recusada sem nada assinado. place_limit_order também recusa uma ordem que preencheria ou dispararia imediatamente contra a taxa atual do roteador (use trade), e um par sem rota alguma, a menos que skipMarketCheck: true. Os preços vão para a API como strings decimais; um número que imprimiria em forma exponencial é recusado em vez de arredondado.

Agendas DCA (Cookiebox custódia DCA, programa DCAkvX8… — um programa separado do de ordens limitadas, preenchido pelo mesmo keeper): get_dca_schedules lista as agendas em execução de uma carteira sem chave (a sua, ou qualquer endereço / nome .cook); open_dca e close_dca precisam de COOKIE_PRIVATE_KEY. Um DCA é uma ordem stop-market que dispara em um relógio em vez de um preço, N vezes: o orçamento inteiro é custodiado na abertura, e a cada ciclo o keeper pode liberar no máximo uma fatia de amountPerCycle, trocá-la pelo mesmo roteador que trade usa, e pagar os rendimentos na conta fixada na abertura. O programa — não o keeper — é dono da agenda, então uma chave de keeper roubada não pode acelerá-la.

  • Divida o orçamento com ou cycles ou amountPerCycle. A fatia é arredondada para cima, então a contagem que o programa deriva (ceil(amount / slice), máximo 1024) pode ser uma menor do que a que você pediu; todo resultado relata o número derivado, nunca o digitado.
  • cycleSeconds é 60 … 31.536.000 (um minuto a um ano). startAt (unix segundos) atrasa o primeiro ciclo; um timestamp passado é recusado em vez de limitado, porque o max(now) do programa o dispararia imediatamente.
  • minPrice / maxPrice são uma opcional faixa por ciclo na saída, cotada por fatia completa. minPrice é o protetor; maxPrice protege contra um preenchimento implausivelmente bom em uma pool manipulada. Um ciclo fora da faixa — ou sem rota — é pulado, nunca recuperado, então a faixa é verificada contra a taxa executável do roteador para uma fatia antes de abrir e uma insatisfazível é recusada a menos que skipMarketCheck: true. Uma faixa cotada a partir de um preço médio é uma faixa que o keeper nunca pode satisfazer.
  • A única taxa é a taxa do maker do próprio programa DCA (10 bps, 3 em um par estável), deduzida dos rendimentos de cada ciclo e lida ao vivo de seu singleton Fee. O insumo COOK nativo é envolvido dentro da abertura e reembolsado como COOK por close_dca.
  • get_dca_schedules relata averagePrice — o que a agenda realmente comprou até agora, o único número que uma lista de preenchimentos individuais nunca dá — e sinaliza status: "overdue", o que significa que um ciclo foi perdido: o programa o descarta em vez de recuperar, então é uma perda real, não um atraso.
  • Não suportado: mints Token-2022 (o keeper assina cada ciclo com o programa de token clássico) e tokens MomoSwap ainda em sua curva de ligação (um ciclo preenche pelo roteador, que não tem perna de curva buy_for, ao contrário de uma ordem de curva limitada). Ambos são recusados antes que qualquer coisa seja custodiada.
  • close_dca retorna o restante não gasto; o que a agenda já comprou já está na carteira. Uma agenda que gasta todo seu orçamento fecha-se e para de ser listada.

As transações de abertura/fechamento são construídas pelo agregador e verificadas aqui exatamente como as de ordens limitadas — usuário, valores, frequência, a faixa, o tempo de início, o PDA da agenda contra o base de assinatura, as contas fixadas de reembolso/pagamento, os cinco programas permitidos — e simuladas antes da assinatura.

Launchpad (precisa de COOKIE_PRIVATE_KEY, MomoSwap): deploy_token lança um token em uma curva de ligação COOK (um logotipo é obrigatório — passe imageBase64 e ele é fixado no IPFS, ou defina noLogo: true para lançar sem um; os metadados são imutáveis, então um logotipo não pode ser adicionado depois. Custa a taxa de criação do launchpad, lida de sua configuração no momento da chamada, mais qualquer devBuyCook), launchpad_buy / launchpad_sell negociam essa curva, claim_launchpad liquida uma posição (o token SPL real após a graduação, um reembolso em modo Fair, ou um pagamento Jackpot/Survivor), e claim_creator_fees varre a parte do criador das taxas de negociação de um lançamento que você criou.

⚠️ Antes da graduação, as participações são cotas de curva rastreadas pelo programa, não tokens SPL — elas não aparecem em get_balance e trade não pode roteá-las. Saia com launchpad_sell, ou reivindique o token real com claim_launchpad uma vez que a pool se gradue; a partir daí, ele negocia como qualquer outro token.

Como essas cotas são invisíveis para get_balance, get_launchpad_positions é a visão de portfólio: cada lançamento em que uma carteira tem posição, quanto vale em uma curva ao vivo, e o que não foi reivindicado (tokens após a graduação, um reembolso em modo Fair, um pagamento de liquidação, taxas do criador ou vesting). Ele lê as contas UserPosition diretamente da chain em lotes, então custa cerca de uma viagem de ida e volta RPC por 100 lançamentos. Passe owner para qualquer carteira, ou omita para a sua própria.

Um token pré-graduação também não tem pool DEX alguma, então get_quote / trade apenas relatariam "sem rota". Eles agora reconhecem esse caso e apontam para as ferramentas do launchpad em vez disso, e get_token_info adiciona um campo launchpad quando um mint não mostra preço ou liquidez porque ainda está em uma curva.

Liquidez (precisa de COOKIE_PRIVATE_KEY): create_pool, add_liquidity, remove_liquidity, claim_fees (Cookiebox DAMM v2, Cookiebox CLMM e CookieSwap BAMM, local detectado automaticamente), lock_liquidity (Cookiebox DAMM v2 e Cookiebox CLMM, permanente e irreversível — CLMM bloqueia a posição inteira; as taxas permanecem reivindicáveis de qualquer forma). Locais de liquidez concentrada (CLMM / BAMM) abrem uma posição de faixa completa por padrão.

Mercado NFT (precisa de COOKIE_PRIVATE_KEY, Baked Bazaar): buy_nft, list_nft, cancel_listing, make_offer, accept_offer, cancel_offer. Construído na Cookie Chain Metaplex Auction House (taxa de mercado de 1% + royalties do criador); cada ação é construída e assinada localmente.

Ponte (precisa de COOKIE_PRIVATE_KEY): bridge move um token 1:1 entre Cookie Chain e Solana mainnet pelas rotas de warp Hyperlane (token = um símbolo ou mint, padrão COOK; direction = cookie-to-solana | solana-to-cookie). Hoje isso é COOK (COOK nativo em Cookie ⇄ um SPL COOK Token-2022 de 6 decimais em Solana) e SOL (SOL nativo em Solana ⇄ um token SOL sintético em Cookie, mint 6tL24Fn75uCMrBSZAvohAq57LSv6KrY6ceEq1wonvucb). Os valores estão nas unidades próprias do token de qualquer forma. Uma assinatura da chain de origem despacha a transferência; um relayer entrega no lado distante em alguns minutos — verifique com bridge_status (uma leitura, pelo id da mensagem Hyperlane).

Novos tokens funcionam sem atualização. get_bridge_tokens e bridge não carregam uma lista de tokens: eles encontram cada programa de warp em Cookie Chain de propriedade da autoridade de atualização da ponte, leem a conta de token Hyperlane de cada um (tipo de rota, mint, decimais, IGP, roteador Solana inscrito), e aceitam uma rota apenas quando o programa Solana que ela nomeia está na mailbox Solana e roteia de volta para ela. Um token que a equipe da ponte adiciona é ponteável assim que sua rota é inscrita; um programa que qualquer outra pessoa implanta nunca é listado. A descoberta é armazenada em cache por 10 minutos. Se o RPC Cookie alguma vez recusar a listagem do programa, as rotas COOK e SOL embutidas ainda são verificadas e get_bridge_tokens diz isso em warnings.

Simula primeiro, e pré-verifica o destino antes de assinar, porque a simulação da chain de origem não pode ver o lado distante:

  • Garantia (Colateral). Uma rota que libera no lado distante (moeda nativa ou um escrow) só pode pagar o que essa conta possui; uma transferência maior levaria seus fundos para trás de uma mensagem não entregável. bridge recusa e reporta o que está lá como destinationCollateral (null quando o destino cunha o token, como SOL na Cookie).
  • Um pagamento nativo para uma carteira vazia deve atingir o mínimo isento de aluguel, ou a entrega é rejeitada em cada tentativa após seus fundos desaparecerem. bridge recusa qualquer valor menor.
  • A conta de token do destinatário. Uma entrega de token credita uma conta de token associada; se o destinatário não tiver uma, bridge a cria a partir da sua carteira primeiro (uma transação extra no destino, um pouco da moeda nativa dessa cadeia em aluguel, reembolsável ao fechar a conta) e confirma antes de despachar — então uma falha lá não custa nada. A rota warp pode criá-la sozinha, mas paga de um PDA financiado uma vez no deploy; quando isso seca, a entrega do relayer falha em simulação, nunca chega à cadeia, e a transferência fica pendurada sem erro em lugar nenhum (isso aconteceu em 2026-08-26). Passe createRecipientAccount: false para confiar nesse PDA — então bridge recusa quando ele está comprovadamente seco. O resultado reporta a conta como recipientTokenAccount.

O site da ponte adiciona uma taxa fixa às suas próprias transferências (0,01 SOL / 15.000 COOK para o relayer). Essa taxa é aplicada pelo site, não pelos programas warp, e bridge não a adiciona. get_balance com chain: "solana" mostra o lado Solana antes de você fazer a ponte — o SPL COOK da carteira (o que solana-to-cookie gasta), seu SOL (a taxa e o gás interchain, e o que uma ponte SOL gasta), e bridgeTokens: todos os outros tokens que a ponte pode mover para fora da Solana, descobertos on-chain como as rotas. Não enumera tokens Solana não relacionados. Em um RPC que recusa getTokenAccountsByOwner (o plano gratuito da Shyft faz), lê a conta padrão de cada token e adiciona um aviso de que tokens mantidos em outro lugar não são contados. Swap na Solana (get_quote / trade com chain: "solana"): roteia liquidez da mainnet da Solana através do Jupiter em vez da Cookie Chain — como você compra ou vende o SPL COOK transferido (36ZrtQoab5MhhySaP1YSTwUahSk6GRVUTtZ6cuVfm9e1) uma vez que está no lado distante. Mesma forma não-custodial de qualquer outro swap: Jupiter cotiza e constrói, nós simulamos no seu RPC Solana, assinamos localmente, enviamos, confirmamos. Taxas são pagas em SOL, e o mesmo COOKIE_PRIVATE_KEY assina em ambas as cadeias — execute get_wallet primeiro. Duas coisas para saber:

  • Escopado para COOK de propósito. Uma perna deve ser a cunhagem SPL COOK, então SOL → COOK e COOK → USDC funcionam enquanto um par não relacionado como SOL → USDC é recusado. Jupiter rotearia; este servidor é para a Cookie Chain, e cada par extra é superfície que pode mover fundos.
  • So1111…112 é COOK na Cookie Chain mas wSOL na Solana — a mesma string de cunhagem, um ativo diferente. Metadados de token são resolvidos por cadeia, e o parâmetro aggregator (somente Cookie Chain) é rejeitado em vez de ignorado quando chain: "solana".
  • trade recusa o endpoint público da Solana. Cotações não precisam de RPC, mas um swap precisa, e api.mainnet-beta.solana.com limita a taxa de sendTransaction mais severamente — um envio que chega tarde contra seu limite de slippage falha. Aponte SOLANA_RPC_URL para um RPC dedicado (uma chave gratuita Helius/Triton/QuickNode é suficiente).

A ponte funciona pronta para uso na mainnet. Para um deploy diferente, sobrescreva as mailboxes (COOKIE_MAILBOX / SOLANA_MAILBOX), a autoridade de upgrade que a descoberta confia (BRIDGE_COOKIE_UPGRADE_AUTHORITY; "" desliga a descoberta), e adicione um programa warp Cookie para sempre verificar com COOKIE_WARP_PROGRAM_ID. O lado Solana e o IGP são lidos das próprias rotas.

Nomes .cook (CookOven): resolve_domain procura um nome — proprietário, data de registro, ponteiros de resolver/metadados — ou reporta como disponível com o preço ao vivo; get_owned_domains lista cada nome que uma carteira possui e qual é o primário. Escritas precisam de COOKIE_PRIVATE_KEY: register_domain, set_primary_domain (ou clear: true para desdefinir), transfer_domain, update_domain. Tudo é lido e construído direto do registro on-chain — sem API, sem indexador. O sufixo é opcional em todo lugar: chef e chef.cook são o mesmo nome.

Uma vez que você possui um nome, pode usá-lo em vez de um endereço: transfer, get_balance, get_wallet_nfts, get_nft_offers, get_launchpad_positions e transfer_domain todos aceitam um nome .cook onde quer que aceitem uma carteira Cookie Chain. Um endereço base58 simples não custa lookup extra.

Marketplace de domínio .cook (CookOven Marketplace): o mercado secundário para nomes já registrados — frequentemente mais barato que o registro de 15.000–35.000 COOK, e a única maneira de obter um nome que outra pessoa já possui. get_domain_listings navega sem chave (filtre por name, seller, maxPriceCook ou maxLength; ordene por preço, comprimento ou recência) e reporta a taxa de mercado ao vivo, que o vendedor paga do preço de venda. Escritas precisam de COOKIE_PRIVATE_KEY: list_domain (preço pedido em COOK), buy_domain, cancel_domain_listing. Lido e construído direto do programa — sem API, sem indexador.

⚠️ Listar coloca o nome em escrow. list_domain entrega o domínio à conta de escrow do marketplace na mesma instrução, então enquanto listado o registro reporta o escrow como proprietário: o vendedor não pode transfer_domain, update_domain ou set_primary_domain nele, e ele para de resolver para um endereço pagável. Essas ferramentas dizem isso explicitamente em vez de reportar um estranho como proprietário, e passar um nome listado onde um endereço é esperado é recusado — o escrow é uma conta de programa, então pagá-lo deixaria os fundos presos. cancel_domain_listing reverte uma listagem a qualquer momento e reembolsa seu aluguel. Não há instrução de re-preço: cancele, então liste novamente.

buy_domain requer maxPriceCook pela mesma razão que register_domain — a instrução não carrega argumento de preço, então esse limite é a única proteção. Sem ele você recebe o preço pedido de volta e nada é gasto.

Use a cunhagem COOK / nativa So11111111111111111111111111111111111111112 para COOK. Cada ferramenta retorna JSON; falhas retornam { error, hint } — nunca um stack trace, nunca sua chave.

Modo hospedado / assinado pela carteira

A configuração padrão assume que você é tanto o operador quanto o usuário. Um produto hospedado — um chat web, um bot Telegram, um agente compartilhado — não pode segurar chaves de usuários e não deve pedi-las. Para isso, cookie-mcp roda sem nenhuma chave e deixa a carteira do próprio usuário assinar:

COOKIE_SIGNER=external npx cookie-mcp --http 3000 --host 0.0.0.0

  • Cada requisição nomeia a carteira para a qual age com um cabeçalho x-cookie-wallet: <base58> (ou defina COOKIE_WALLET_ADDRESS para um deploy de carteira única). Leituras funcionam como antes.

  • Cada ferramenta que move dinheiro executa todas as suas verificações — decodificação de instrução, recusas de gasto, a simulação — e então, em vez de assinar, retorna um resultado normal (não-erro):

    {
  "status": "needs_signature",
  "tool": "transfer",
  "kind": "transaction",
  "what": "transfer",
  "signer": "FFWf…4wq2",
  "transactionBase64": "AQAAAA…",
  "version": "legacy",
  "blockhash": "6FdF…TSvT",
  "lastValidBlockHeight": 24638662,
  "submit": { "via": "cookie-rpc" },
  "step": "final",
  "summary": { "to": "…", "symbol": "COOK", "amount": "0.001" },
  "next": "sign transactionBase64 with wallet … then call submit_signed_tx …"
}

    Seu aplicativo entrega transactionBase64 à carteira do navegador inalterado (já está co-assinado por quaisquer signatários efêmeros ou do lado da API), então chama submit_signed_tx com os bytes assinados e os mesmos campos submit / blockhash / lastValidBlockHeight / what. Ele envia na rota nomeada (Cookie RPC, Solana RPC ou Candy Shop) e confirma. Recusa bytes que ainda não têm assinatura e nunca constrói transações sozinho.

  • step: "intermediate" marca um pré-requisito (envolver COOK para uma compra dev, criar uma conta de token Solana antes de uma ponte, init de tick-array CLMM). Após confirmar, chame a mesma ferramenta novamente com os mesmos argumentos para continuar.

  • kind: "message" (somente deploy_token, para o login do launchpad) pede à carteira para signMessage o texto exato; chame deploy_token novamente com loginSignature: { message, signature }.

  • Blockhashes expiram em cerca de um minuto. Se o prompt da carteira for lento, submit_signed_tx reporta o timeout com a assinatura e uma dica "não tente novamente às cegas"; re-execute a ferramenta para bytes frescos.

  • O servidor HTTP é stateless (um servidor novo por POST), responde /healthz, e envia cabeçalhos CORS permissivos para que um front-end de navegador possa chamá-lo diretamente. Ele recusa iniciar com um COOKIE_PRIVATE_KEY local a menos que COOKIE_HTTP_ALLOW_LOCAL_KEY=1, porque qualquer um alcançando a porta poderia gastar dessa chave.

Como biblioteca. Os mesmos fluxos são importáveis sem MCP:

import {
  ExternalSigner,
  transfer,
  submitSignedTransaction,
  runWithRequestContext,
} from "cookie-mcp";
import { createServer } from "cookie-mcp/server"; // embed the MCP server in your own process

Funções de dinheiro resolvem seu signatário de COOKIE_SIGNER + o contexto da requisição (runWithRequestContext({ wallet }, () => transfer({...}))) e lançam SignatureRequired com o mesmo payload que a ferramenta retorna. Agentes locais (COOKIE_PRIVATE_KEY, stdio) não são afetados por nada disso.

Segurança

Não-custodial: sem armazenamento remoto de chaves. Com uma chave local, ela fica em COOKIE_PRIVATE_KEY, assina localmente, e é redigida de toda saída. No modo hospedado, o processo não segura nenhuma chave e a carteira do usuário assina. Somente leitura até um signatário ser configurado; toda ação que move dinheiro é simulada antes de ser enviada (ou entregue para assinatura).

Desenvolvimento

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/ (CLI, `cookie-mcp/server` factory, `cookie-mcp` library)

Para apontar um agente a um checkout local em vez do pacote publicado, defina o comando para npx tsx /ABS/PATH/cookie-mcp/src/mcp/server.ts. --http [port] serve Streamable HTTP em vez disso.

Release

Um release é um publish npm mais um re-publish da mesma versão para o MCP Registry; diretórios de terceiros (mcpservers.org e amigos) espelham a entrada do registro, então o passo do registro é o que realmente os atualiza. Mantenha o npm latest atual com main — os diretórios raspam o GitHub, e um npm atrasado dá às pessoas um README que promete ferramentas que o servidor instalado não tem.

  1. Atualize a versão em três lugares, todos para a mesma string: package.json version e server.json tanto no nível superior version quanto em packages[0].version. O registro rejeita uma incompatibilidade, e mcpName em package.json deve permanecer io.github.cookiechain/cookie-mcp (o registro verifica o tarball publicado para isso).
  2. CHANGELOG: renomeie o cabeçalho [Unreleased] para # [X.Y.Z](https://github.com/cookiechain/cookie-mcp/releases/tag/vX.Y.Z) com uma linha datada abaixo dele, depois abra um novo # [Unreleased] acima dele para o próximo ciclo.
  3. Gate: yarn test — a mesma execução de lint / format / typecheck / unit / smoke do CI. Cada nova ferramenta deve estar listada em EXPECTED_TOOLS em scripts/smoke.ts (o smoke apenas reporta nomes ausentes, então uma ferramenta que você esqueceu de adicionar lá passa silenciosamente) e na lista Tools acima.
  4. Verifique o tarball: npm pack --dry-run. Ele deve conter apenas dist/**, README.md, LICENSE e package.json — sem src/, .env, material de chave ou caminhos absolutos. prepublishOnly executa yarn build (tsup), então dist/ é sempre reconstruído a partir do código-fonte marcado.
  5. Commit, tag, release: faça commit como Release X.Y.Z, crie a tag vX.Y.Z, git push --tags e crie o release no GitHub a partir da tag com a seção do CHANGELOG como corpo (os links do CHANGELOG apontam para essa página de release).
  6. Publique no npm: npm publish, depois verifique com npm view cookie-mcp version e uma inicialização fixada a partir de um diretório limpo: npx -y cookie-mcp@X.Y.Z deve iniciar e registrar todas as ferramentas.

    Um E404 … PUT …/cookie-mcp … could not be found or you do not have permission de npm publish quase nunca é um pacote ausente — o npm relata uma publicação não autenticada como 404. Execute npm whoami; se falhar, npm login e publique novamente.

  7. Publique no MCP Registry: brew install mcp-publisher, depois a partir da raiz do repositório mcp-publisher login github && mcp-publisher publish. O namespace io.github.cookiechain/* exige que você seja um owner da organização no GitHub. Se o login por device-flow ainda cair para seu namespace pessoal com um 403, a organização restringe aplicativos OAuth — faça login com um PAT clássico que tenha read:org em vez disso: MCP_GITHUB_TOKEN=<pat> mcp-publisher login github.

Licença

Este projeto está licenciado sob os termos da licença MIT. Consulte o arquivo LICENSE.