Polygon MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Polygon 区块链网络的无缝集成。该服务器使 AI 助手能够通过标准化接口与 Polygon 交互，提供用于钱包操作、智能合约部署、L2 桥接、DeFi 交互和交易模拟的综合工具。

目录

• 简介
• 快速开始
• 特性
• 架构
• API 参考
• 高级用法
• 故障排除
• 贡献
• 安全注意事项
• 许可证

简介

Polygon 是以太坊的 Layer 2 扩展解决方案，可在保持以太坊安全性的同时提供更快、更便宜的交易。此 MCP 服务器允许 AI 助手与 Polygon 网络交互，从而通过简单、标准化的接口实现各种区块链操作。

该服务器充当 AI 系统和 Polygon 区块链之间的桥梁，处理区块链交互的复杂性，并为常见操作提供简洁、易于使用的 API。

┌─────────────┐     ┌───────────────┐     ┌─────────────────┐
│             │     │               │     │                 │
│  AI 系统  ├─────┤  Polygon MCP  ├─────┤  Polygon 链  │
│             │     │    服务器     │     │                 │
└─────────────┘     └───────────────┘     └─────────────────┘

快速开始

前提条件

• Node.js (v18 或更高版本)
• npm 或 yarn
• Polygon 钱包私钥（用于签署交易）
• Polygon Mainnet 和 Amoy 测试网的 RPC 端点

安装

1. 克隆存储库或下载源代码
2. 安装依赖项：

cd polygonmcp
npm install

3. 创建一个包含以下变量的 .env 文件：

# 网络 RPC 端点
POLYGON_MAINNET_RPC=https://polygon-rpc.com
POLYGON_AMOY_RPC=https://rpc-amoy.polygon.technology
ETHEREUM_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY  # Sepolia 用于 Amoy 的 L1

# API 密钥
POLYGONSCAN_API_KEY=YOUR_EXPLORER_API_KEY  # 使用 OKLink API 密钥用于 Amoy

# 钱包（重要提示：在生产环境中使用安全的密钥管理）
PRIVATE_KEY=your_private_key_here
DEFAULT_NETWORK=amoy  # 使用 'amoy' 用于测试网

# DeFi 配置（可选）
DEFAULT_SLIPPAGE=0.5
DEFAULT_DEADLINE_MINUTES=20

运行服务器

启动服务器：

npm start

用于自动重启的开发：

npm run dev

第一步

1. 检查您的钱包余额：

   import { PolygonMCPServer } from './polygon-mcp.js';
   const server = new PolygonMCPServer();
   
   async function checkBalance() {
     // 如果 PRIVATE_KEY 在 .env 中，钱包会在服务器启动时自动连接
     // await server.connectWallet(process.env.PRIVATE_KEY);
     const balances = await server.listBalances();
     console.log('Wallet balances:', balances);
   }
   
   checkBalance().catch(console.error);
   

2. 获取测试网 POL（仅限 Amoy 测试网）：

   async function getTestPol() {
     // 如果 PRIVATE_KEY 在 .env 中，钱包会在服务器启动时自动连接
     // await server.connectWallet(process.env.PRIVATE_KEY);
     const result = await server.getTestnetPol();
     console.log('Faucet result:', result);
   }
   

3. 模拟交易：

   // 如果 PRIVATE_KEY 在 .env 中，钱包会在服务器启动时自动连接
   
   async function simulateTransaction() {
     const result = await server.simulateTransaction({
       to: '0x1234...', // 接收者地址
       value: '0.01',    // MATIC（或原生代币）金额
     });
     console.log('Simulation result:', result);
   }
   

特性

钱包操作

工具	描述	示例
get-address	检索当前钱包地址	const address = await server.getAddress()
get-testnet-pol	从水龙头请求测试网 POL（仅限 Amoy 测试网）	await server.getTestnetPol()
list-balances	列出连接钱包的代币余额	const balances = await server.listBalances()
transfer-funds	将 POL 或 ERC20 代币转移到另一个地址	await server.transferFunds('0x1234...', '0.1', 'MATIC')

钱包管理器提供：

• 增强的钱包连接验证
• 支持多个网络
• 改进的错误处理和详细消息
• 安全的私钥管理

智能合约操作

工具	描述	示例
deploy-contract	将智能合约部署到 Polygon	await server.deployContract(name, code, args)
verify-contract	在 Polygonscan 上验证已部署的合约	await server.verifyContract(address, name, code, args)
list-contract-templates	列出可用的合约模板	const templates = await server.listContractTemplates()

支持的合约类型：

• ERC20 代币
• ERC721 NFT 集合
• ERC1155 多代币
• 质押合约
• 多重签名钱包

L2 桥接操作

工具	描述	示例
deposit-eth	将 ETH 从以太坊存入 Polygon	await server.mcpServer.callTool('deposit-eth', { amount: '0.1' })
withdraw-eth	将 ETH/POL 从 Polygon 提取到以太坊	await server.mcpServer.callTool('withdraw-eth', { amount: '0.1' })
deposit-token	将 ERC20 从以太坊存入 Polygon	await server.mcpServer.callTool('deposit-token', { token: 'USDC', amount: '100' })
withdraw-token	将 ERC20 从 Polygon 提取到以太坊	await server.mcpServer.callTool('withdraw-token', { token: 'USDC', amount: '100' })
check-bridge-status	检查桥接交易的状态（尚未作为工具实现）	N/A

特性：

• 支持通过 PolygonBridge 类桥接 ETH 和 ERC20 代币。
• 在 bridge-operations.js 中封装了 MaticPOSClient 的使用。
• 增强了桥接操作的错误处理。
• 检查点感知（MaticPOSClient 中固有）。

注意： 由于 ESM 兼容性问题，当前实现使用 MaticPOSClient 的模拟版本。在创建适当的 ESM 兼容实现之前，桥接操作可能无法正常工作。

DeFi 交互

QuickSwap DEX

工具	描述	示例
swap-tokens	使用 QuickSwap 交换代币	await server.swapTokens('MATIC', 'USDC', '10')
get-swap-quote	获取代币交换的价格报价	const quote = await server.getSwapQuote('MATIC', 'USDC', '10')
add-liquidity	向 QuickSwap 池添加流动性	await server.addLiquidity('MATIC', 'USDC', '10', '20')

Uniswap V3

工具	描述	示例
uniswapV3SwapSingle	执行单跳交换	await server.uniswapV3SwapSingle(tokenIn, tokenOut, amount, fee)
uniswapV3SwapMulti	执行多跳交换	await server.uniswapV3SwapMulti(path, amounts)
getUniswapV3QuoteSingle	获取单跳交换的报价	const quote = await server.getUniswapV3QuoteSingle(tokenIn, tokenOut, amount, fee)
getUniswapV3QuoteMulti	获取多跳交换的报价	const quote = await server.getUniswapV3QuoteMulti(path, amount)

Polymarket 预测市场

工具	描述	示例
getPolymarketInfo	获取市场信息	const info = await server.getPolymarketInfo(marketId)
placePolymarketBet	通过购买仓位代币下注	await server.placePolymarketBet(marketId, outcome, amount)
getPolymarketPositions	获取用户在市场中的仓位	const positions = await server.getPolymarketPositions(marketId)

交易模拟

工具	描述	示例
simulate-transaction	模拟交易以预览其效果	const result = await server.simulateTransaction(txParams)
estimate-gas	估算交易的 gas 费用	const gas = await server.estimateGas(txParams)

特性：

• 支持 EIP-1559 的 gas 费用估算
• 代币转移检测和分析
• 合约交互模拟
• 增强的 BigInt 处理
• 改进的错误上下文

网络工具

工具	描述	示例
get-gas-price	获取 Polygon 上的当前 gas 价格	const price = await server.getGasPrice()
switch-network	在 Polygon Mainnet 和 Amoy 测试网之间切换	await server.switchNetwork('mainnet')

架构

Polygon MCP 服务器采用模块化架构构建，该架构分离关注点并提高可维护性：

flowchart TD
    MCPServer["Polygon MCP 服务器 (polygon-mcp.js)"]

    subgraph Modules
        BridgeOps["桥接操作 (bridge-operations.js)"]
        ContractOps["合约模板 (contract-templates.js)"]
        DeFiOps["DeFi 交互 (defi-interactions.js)"]
        SimOps["交易模拟器 (transaction-simulation.js)"]
    end

    subgraph Common ["通用实用程序 (common/)"]
        WalletManager["钱包管理器 (Singleton)"]
        ConfigManager["配置管理器"]
        Utils["实用函数 (utils.js)"]
        Constants["常量"]
        Logger["日志记录器 (logger.js)"]
        Errors["错误处理 (errors.js)"]
        Validation["验证 (validation.js)"]
    end

    MCPServer -- 实例化/使用 --> Modules
    MCPServer -- 使用 --> Common
    Modules -- 使用 --> Common

主要组件

1. Polygon MCP 服务器 (polygon-mcp.js): 主要入口点，处理 MCP 通信，实例化模块，注册工具，委托调用。
2. 通用实用程序 (common/):
   • 钱包管理器: 用于集中式钱包状态和访问的单例。
   • 配置管理器: 用于集中式配置加载的单例 (getConfig)。
   • 实用函数: 共享助手，如 resolveTokenAddress。
   • 常量: 共享 ABI，地址。
   • 日志记录器、错误、验证: 支持组件。
3. 功能模块:
   • 桥接操作 (bridge-operations.js): 封装 MaticPOSClient 和桥接逻辑。
   • 合约模板 (contract-templates.js): 处理合约编译，从模板部署。
   • DeFi 交互 (defi-interactions.js): 与 DEX（QuickSwap、Uniswap）、Polymarket 交互。
   • 交易模拟器 (transaction-simulation.js): 使用 eth_call 模拟交易。

数据流

1. 客户端请求由 MCP 服务器接收
2. 验证请求并检查参数
3. 相应的模块处理请求
4. 通过 ethers.js 执行区块链交互
5. 格式化结果并返回给客户端

API 参考

钱包操作（通过 MCP 工具）

get-address

获取连接钱包的地址。

返回： JSON 字符串 { "address": "0x..." }

list-balances

列出连接钱包（或指定地址）的本机和已知代币余额。

参数（可选）：

• address (string): 要检查的地址（默认为连接的钱包）

返回： JSON 字符串 { "address": "...", "nativeBalance": "...", "tokens": { "USDC": "...", ... } }

transfer-funds

将本机代币 (POL) 或 ERC20 代币转移到另一个地址。

参数：

• to (string): 接收者地址
• amount (string): 要转移的金额
• token (string, optional): 代币符号或地址（省略表示本机 POL）

返回： JSON 字符串 { "success": true, "txHash": "0x...", ... }

合约操作（通过 MCP 工具）

list-contract-templates

列出可用的合约模板。

返回： JSON 字符串 [{ "id": "erc20", "name": "...", ... }, ...]

deploy-contract

从模板部署合约。

参数：

• templateId (string): 模板的 ID（例如，'erc20'，'nft'）
• params (object): 模板特定的参数（例如，{ "name": "MyToken", ... }）
• constructorArgs (Array, optional): 合约构造函数的参数

返回： JSON 字符串 { "address": "0x...", "transactionHash": "0x...", ... }

verify-contract（当前未作为 MCP 工具公开）

在 Polygonscan 上验证合约。

参数：

• address (string): 合约地址
• name (string): 合约名称
• code (string): 合约源代码
• constructorArgs (Array): 构造函数参数

返回： 对象 - 验证结果（如果作为工具实现）

桥接操作（通过 MCP 工具）

deposit-eth

将 ETH 从以太坊存入 Polygon。

参数：

• amount (string): 要存入的 ETH 金额

返回： JSON 字符串 { "txHash": "0x...", "status": "pending" }

withdraw-eth

将本机代币 (POL) 从 Polygon 提取到以太坊。注意：Polygon 已将主网和测试网上的 MATIC 品牌重塑为 POL。

参数：

• amount (string): 要提取的本机代币 (POL) 金额

返回： JSON 字符串 { "txHash": "0x...", "status": "pending" }

deposit-token

将 ERC20 代币从以太坊存入 Polygon。

参数：

• token (string): 代币符号或地址
• amount (string): 要存入的金额

返回： JSON 字符串 { "txHash": "0x...", "status": "pending" }

withdraw-token

将 ERC20 代币从 Polygon 提取到以太坊。

参数：

• token (string): 代币符号或地址
• amount (string): 要提取的金额

返回： JSON 字符串 { "txHash": "0x...", "status": "pending" }

(注意：check-bridge-status 在 PolygonBridge 中实现，但尚未作为 MCP 工具公开)

高级用法

组合多个操作

// 示例：交换代币，然后桥接到以太坊（使用 MCP 工具的概念）
async function swapAndBridge() {
  // 假设服务器正在运行，并且钱包已通过 env/config 连接

  // 将 MATIC 交换为 USDC（使用假设的交换工具 - 需要实现）
  // const swapResult = await server.mcpServer.callTool('swap-tokens', { fromToken: 'MATIC', toToken: 'USDC', amount: '10' });
  // console.log('Swap result:', swapResult);
  // await server.provider.waitForTransaction(swapResult.content[0].text.txHash); // 等待交换交易

  // 将 USDC 桥接到以太坊
  const bridgeResult = await server.mcpServer.callTool('withdraw-token', { token: 'USDC', amount: '10' });
  console.log('Bridge result:', bridgeResult);
}

自定义合约部署

// 使用模板部署自定义 ERC20 代币（使用 MCP 工具的概念）
async function deployCustomToken() {
  // 假设服务器正在运行，并且钱包已通过 env/config 连接

  // 获取 ERC20 模板信息（可选步骤）
  // const templates = await server.mcpServer.callTool('list-contract-templates', {});
  // console.log(templates);

  // 定义参数
  const templateId = 'erc20';
  const params = { name: 'MyCustomToken' }; // 名称用于模板处理
  const constructorArgs = ['MyCustomToken', 'MCT', '1000000000000000000000000']; // 名称、符号、初始供应量（以 wei 为单位）

  // 部署合约
  const deployResult = await server.mcpServer.callTool('deploy-contract', {
    templateId,
    params,
    constructorArgs
  });
  const deployData = JSON.parse(deployResult.content[0].text);
  console.log('Contract deployed at:', deployData.address);

  // 验证需要源代码，deploy-contract 不会直接返回源代码
  // 验证可能需要单独的工具或手动过程。
}
  const customizedCode = erc20Template.code
    .replace('{{name}}', 'MyCustomToken')
    .replace('initialSupply * 10 ** decimals()', '1000000 * 10 ** 18');

  // 部署合约
  const result = await server.deployContract(
    'MyCustomToken',
    customizedCode,
    ['MyCustomToken', 'MCT', 1000000]
  );

用于安全性的交易模拟

// 在执行交易之前模拟交易（使用 MCP 工具的概念）
async function safeTransfer() {
  // 假设服务器正在运行，并且钱包已通过 env/config 连接

  const txParams = {
    to: '0x1234...',
    value: '1000000000000000000', // 1 POL in wei
    // data: '0x' // 可选数据
  };

  // 首先模拟
  const simResult = await server.mcpServer.callTool('simulate-transaction', { transaction: txParams });
  const simulation = JSON.parse(simResult.content[0].text);

  // 检查问题
  if (!simulation.success) {
    console.error('Transaction would fail:', simulation.errorMessage);
    return;
  }

  // 检查 gas 费用
  console.log('Estimated gas cost:', simulation.gasCost.ether, 'MATIC');
  // 如果模拟成功，则执行（使用 transfer-funds 工具）
  const transferResult = await server.mcpServer.callTool('transfer-funds', {
    to: txParams.to,
    amount: '1.0' // 工具的 POL 金额
  });
  console.log('Transaction sent:', transferResult);
}

故障排除

当前状态和已知问题

重要提示： 由于 ESM 兼容性问题，当前实现使用 MaticPOSClient 的模拟版本。在创建适当的 ESM 兼容实现之前，桥接操作（存款/取款）可能无法正常工作。

常见问题

“钱包未连接”错误

确保 PRIVATE_KEY 在 .env 文件或 MCP 服务器配置中正确设置，因为如果提供了密钥，钱包会在服务器启动时自动连接。手动 connectWallet 调用不再是主要机制。

RPC 连接问题

如果您遇到 RPC 连接问题，请尝试：

1. 检查您的互联网连接
2. 验证 .env 文件中的 RPC 端点 URL
3. 使用不同的 RPC 提供商

资金不足

对于需要 gas 费用的操作，请确保您的钱包有足够的本机代币 (POL)：

const balances = await server.listBalances();
// 检查本机代币余额 (POL)
const nativeToken = 'POL';
console.log(`${nativeToken} balance:`, balances.nativeBalance);

交易失败

在发送之前，使用交易模拟器诊断问题：

const simulation = await server.simulateTransaction(tx);
if (!simulation.success) {
  console.error('Transaction would fail:', simulation.errorMessage);
}

调试

通过设置环境变量启用调试日志记录：

DEBUG=polygon-mcp:*

贡献

欢迎贡献！以下是如何贡献：

1. Fork 存储库
2. 创建一个功能分支：git checkout -b feature/my-feature
3. 提交您的更改：git commit -am 'Add my feature'
4. 推送到分支：git push origin feature/my-feature
5. 提交 pull request

开发设置

1. 克隆存储库
2. 安装依赖项：npm install
3. 使用测试凭据创建一个 .env.test 文件
4. 运行测试：npm test
5. 运行 linting：npm run lint

安全注意事项

此服务器处理私钥和敏感的区块链操作。对于生产用途：

1. 永远不要将私钥存储在代码或环境变量中
2. 使用安全的密钥管理系统或硬件钱包集成
3. 实施适当的身份验证和授权
4. 添加速率限制以防止滥用
5. 添加全面的日志记录和监控
6. 验证所有输入参数
7. 实施适当的错误处理
8. 使用安全配置管理

MCP 集成

添加到 MCP 设置

要将此服务器与 Claude 或其他 MCP 兼容系统一起使用，请将其添加到您的 MCP 设置配置文件中：

对于 Cursor/Claude Dev：

{
  "mcpServers": {
    "polygon": {
      "command": "node",
      "args": ["path/to/polygon-mcp.js"],
      "env": {
        "POLYGON_MAINNET_RPC": "https://polygon-rpc.com",
        "POLYGON_AMOY_RPC": "https://rpc-amoy.polygon.technology",
        "ETHEREUM_RPC_URL": "https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY",
        "POLYGONSCAN_API_KEY": "YOUR_EXPLORER_API_KEY",
        "PRIVATE_KEY": "your_private_key_here",
        "DEFAULT_NETWORK": "amoy",
        "DEFAULT_SLIPPAGE": "0.5",
        "DEFAULT_DEADLINE_MINUTES": "20"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

项目结构

• polygon-mcp.js - 主要服务器实现
• bridge-operations.js - L2 桥接操作
• contract-templates.js - 合约部署模板
• defi-interactions.js - DeFi 协议交互
• transaction-simulation.js - 交易模拟逻辑。
• logger.js - 结构化日志记录实用程序。
• errors.js - 自定义错误类和助手。
• validation.js - 输入验证助手（可能未充分利用）。
• common/ - 共享实用程序和常量：
  • config-manager.js - 集中式配置加载 (getConfig)。
  • constants.js - 共享 ABI，地址。
  • wallet-manager.js - 单例钱包管理器。
  • utils.js - 集中式实用函数（例如，resolveTokenAddress）。

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。