OpenOcean Finance

Servidor MCP OPENOCEAN

Um servidor MCP para executar trocas de tokens em múltiplas exchanges descentralizadas usando a API de agregação da OpenOcean.

Visão Geral

Este projeto implementa um servidor Model Context Protocol (MCP) para interagir com exchanges descentralizadas (DEXs). Ele permite que clientes compatíveis com MCP (como assistentes de IA, extensões de IDE ou aplicações personalizadas) acessem funcionalidades como obter cotações para trocas e executar trocas em múltiplas blockchains.

Este servidor é construído usando TypeScript e fastmcp.

Funcionalidades (Ferramentas MCP)

O servidor expõe as seguintes ferramentas que os clientes MCP podem utilizar:

• CHAIN_LIST: Buscar lista de blockchains.
  • Parâmetros:
• GAS_PRICE: Buscar preço do gás.
  • Parâmetros: chain (string)
• QUOTE: Buscar cotação para uma troca.
  • Parâmetros: chain (string), inTokenAddress (string), outTokenAddress (string), amount (string), slippage (string)
• SWAP: Construir transação de troca.
  • Parâmetros: chain (string), inTokenAddress (string), outTokenAddress (string), amount (string), slippage (string), account (string)
• GET_TRANSACTION: Buscar informações da transação.
  • Parâmetros: chain (string), hash (string)
• TOKEN_LIST: Buscar lista de tokens.
  • Parâmetros: chain (string)
• DEX_LIST: Buscar lista de DEXs.
  • Parâmetros: chain (string)

Detalhamento dos parâmetros

• chain: O código da blockchain da DEX.
• inTokenAddress: O token que você deseja vender.
• outTokenAddress: O token que você deseja comprar.
• amount: Quantidade do token com decimais. Por exemplo, se 1 USDT for inserido, use 1000000 (1 USDT * 10^6).
• slippage: Defina o nível de slippage aceitável inserindo um valor percentual dentro do intervalo de 0,05 a 50. Slippage de 1% definido como 1.
• account: Endereço da carteira do usuário.
• hash: Hash do contrato da OpenOcean na blockchain.

Pré-requisitos

• Node.js (v18 ou mais recente recomendado)
• pnpm (Consulte https://pnpm.io/installation)

Instalação

Existem algumas maneiras de usar o openocean-mcp:

1. Usando pnpm dlx (Recomendado para a maioria das configurações de clientes MCP):

Você pode executar o servidor diretamente usando pnpm dlx sem precisar de uma instalação global. Esta é frequentemente a maneira mais fácil de integrar com clientes MCP. Consulte a seção "Executando o Servidor com um Cliente MCP" para exemplos. (pnpm dlx é o equivalente do pnpm ao npx)

2. Instalação Global via npm (através do pnpm):

Instale o pacote globalmente para disponibilizar o comando openocean-mcp em todo o sistema:

pnpm add -g openocean-mcp

3. Compilando a partir do Código Fonte (para desenvolvimento ou modificações personalizadas):

1. Clone o repositório:

   git clone https://github.com/openocean-finance/openocean-mcp.git
   cd openocean-mcp
   

2. Instale as dependências:

   pnpm install
   

3. Compile o servidor: Isso compila o código TypeScript para JavaScript no diretório dist.

   pnpm run build
   

   O script prepare também executa pnpm run build, então as dependências são compiladas após a instalação se você clonar e executar pnpm install.

Configuração (Variáveis de Ambiente)

Este servidor MCP pode exigir que certas variáveis de ambiente sejam definidas pelo cliente MCP que o executa. Elas são tipicamente configuradas na definição do servidor MCP do cliente (por exemplo, em um arquivo mcp.json para Cursor, ou similar para outros clientes).

• Quaisquer variáveis de ambiente necessárias para provedores de carteira ou chaves de API.

Executando o Servidor com um Cliente MCP

Clientes MCP (como assistentes de IA, extensões de IDE, etc.) executarão este servidor como um processo em segundo plano. Você precisa configurar o cliente para informar como iniciar seu servidor.

Abaixo está um exemplo de trecho de configuração que um cliente MCP pode usar (por exemplo, em um arquivo mcp_servers.json ou similar). Este exemplo mostra como executar o servidor usando o pacote npm publicado via pnpm dlx.

{
  "mcpServers": {
    "openocean-mcp-server": {
      "command": "pnpm",
      "args": ["dlx", "openocean-mcp"]
    }
  }
}

Alternativa se Instalado Globalmente:

Se você instalou o openocean-mcp globalmente (pnpm add -g openocean-mcp), você pode simplificar o command e o args:

{
  "mcpServers": {
    "openocean-mcp-server": {
      "command": "openocean-mcp",
      "args": []
    }
  }
}

• command: O executável a ser executado.
  • Para pnpm dlx: "pnpm" (com "dlx" como primeiro argumento)
  • Para instalação global: "openocean-mcp"
• args: Um array de argumentos a serem passados para o comando.
  • Para pnpm dlx: ["dlx", "openocean-mcp"]
  • Para instalação global: []
• env: Um objeto contendo variáveis de ambiente a serem definidas quando o processo do servidor iniciar. É aqui que você fornece quaisquer variáveis de ambiente necessárias.
• workingDirectory: Geralmente não é necessário ao usar o pacote publicado via pnpm dlx ou uma instalação global, pois o pacote deve lidar com seus próprios caminhos corretamente. Se você estiver executando a partir do código fonte (node dist/index.js), então definir workingDirectory para a raiz do projeto seria importante.