内容
# Polygon MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
一个模型上下文协议（MCP）服务器，提供与 Polygon 区块链网络的无缝集成。该服务器使 AI 助手能够通过标准化接口与 Polygon 交互，提供用于钱包操作、智能合约部署、L2 桥接、DeFi 交互和交易模拟的综合工具。
## 目录
- [简介](#introduction)
- [快速开始](#quick-start)
- [特性](#features)
- [架构](#architecture)
- [API 参考](#api-reference)
- [高级用法](#advanced-usage)
- [故障排除](#troubleshooting)
- [贡献](#contributing)
- [安全注意事项](#security-considerations)
- [许可证](#license)
## 简介
Polygon 是以太坊的 Layer 2 扩展解决方案，可在保持以太坊安全性的同时提供更快、更便宜的交易。此 MCP 服务器允许 AI 助手与 Polygon 网络交互，通过简单、标准化的接口实现各种区块链操作。
该服务器充当 AI 系统和 Polygon 区块链之间的桥梁，处理区块链交互的复杂性，并为常见操作提供简洁、易于使用的 API。
```
┌─────────────┐ ┌───────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ AI System ├─────┤ Polygon MCP ├─────┤ Polygon Chain │
│ │ │ Server │ │ │
└─────────────┘ └───────────────┘ └─────────────────┘
```
## 快速开始
### 前提条件
- Node.js (v18 或更高版本)
- npm 或 yarn
- Polygon 钱包私钥（用于签署交易）
- Polygon Mainnet 和 Amoy Testnet 的 RPC 端点
### 安装
1. 克隆存储库或下载源代码
2. 安装依赖项：
```bash
cd polygonmcp
npm install
```
3. 创建一个包含以下变量的 `.env` 文件：
```env
# Network RPC endpoints
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 for Amoy's L1
# API Keys
POLYGONSCAN_API_KEY=YOUR_EXPLORER_API_KEY # Use OKLink API key for Amoy
# Wallet (IMPORTANT: Use secure key management in production)
PRIVATE_KEY=your_private_key_here
DEFAULT_NETWORK=amoy # Use 'amoy' for testnet
# DeFi Configuration (Optional)
DEFAULT_SLIPPAGE=0.5
DEFAULT_DEADLINE_MINUTES=20
```
### 运行服务器
启动服务器：
```bash
npm start
```
对于具有自动重启功能的开发：
```bash
npm run dev
```
### 初始步骤
1. **检查您的钱包余额**：
```javascript
import { PolygonMCPServer } from './polygon-mcp.js';
const server = new PolygonMCPServer();
async function checkBalance() {
// Wallet is connected automatically on server start if PRIVATE_KEY is in .env
// await server.connectWallet(process.env.PRIVATE_KEY);
const balances = await server.listBalances();
console.log('Wallet balances:', balances);
}
checkBalance().catch(console.error);
```
2. **获取 testnet POL**（仅限 Amoy testnet）：
```javascript
async function getTestPol() {
// Wallet is connected automatically on server start if PRIVATE_KEY is in .env
// await server.connectWallet(process.env.PRIVATE_KEY);
const result = await server.getTestnetPol();
console.log('Faucet result:', result);
}
```
3. **模拟交易**：
```javascript
// Wallet is connected automatically on server start if PRIVATE_KEY is in .env
async function simulateTransaction() {
const result = await server.simulateTransaction({
to: '0x1234...', // Recipient address
value: '0.01', // Amount in MATIC (or native token)
});
console.log('Simulation result:', result);
}
```
## 特性
### 钱包操作
| Tool | Description | Example |
|------|-------------|---------|
| `get-address` | 检索当前钱包地址 | `const address = await server.getAddress()` |
| `get-testnet-pol` | 从 faucet 请求 testnet POL（仅限 Amoy testnet） | `await server.getTestnetPol()` |
| `list-balances` | 列出连接钱包的 token 余额 | `const balances = await server.listBalances()` |
| `transfer-funds` | 将 POL 或 ERC20 token 转移到另一个地址 | `await server.transferFunds('0x1234...', '0.1', 'MATIC')` |
钱包管理器提供：
- 增强的钱包连接验证
- 支持多个网络
- 改进的错误处理和详细消息
- 安全的私钥管理
### 智能合约操作
| Tool | Description | Example |
|------|-------------|---------|
| `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 tokens
- ERC721 NFT 集合
- ERC1155 multi-tokens
- Staking 合约
- Multisig 钱包
### L2 桥接操作
| Tool | Description | Example |
|------|-------------|---------|
| `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 token 桥接。
- 在 `bridge-operations.js` 中封装了 `MaticPOSClient` 的使用。
- 增强了桥接操作的错误处理。
- 检查点感知（`MaticPOSClient` 中固有）。
**注意：** 由于 ESM 兼容性问题，当前实现使用 MaticPOSClient 的模拟版本。在创建适当的 ESM 兼容实现之前，桥接操作可能无法正常运行。
### DeFi 交互
#### QuickSwap DEX
| Tool | Description | Example |
|------|-------------|---------|
| `swap-tokens` | 使用 QuickSwap 交换 token | `await server.swapTokens('MATIC', 'USDC', '10')` |
| `get-swap-quote` | 获取 token 交换的价格报价 | `const quote = await server.getSwapQuote('MATIC', 'USDC', '10')` |
| `add-liquidity` | 向 QuickSwap 池添加流动性 | `await server.addLiquidity('MATIC', 'USDC', '10', '20')` |
#### Uniswap V3
| Tool | Description | Example |
|------|-------------|---------|
| `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 预测市场
| Tool | Description | Example |
|------|-------------|---------|
| `getPolymarketInfo` | 获取市场信息 | `const info = await server.getPolymarketInfo(marketId)` |
| `placePolymarketBet` | 通过购买仓位 token 下注 | `await server.placePolymarketBet(marketId, outcome, amount)` |
| `getPolymarketPositions` | 获取用户在市场中的仓位 | `const positions = await server.getPolymarketPositions(marketId)` |
### 交易模拟
| Tool | Description | Example |
|------|-------------|---------|
| `simulate-transaction` | 模拟交易以预览其效果 | `const result = await server.simulateTransaction(txParams)` |
| `estimate-gas` | 估算交易的 gas | `const gas = await server.estimateGas(txParams)` |
功能：
- 支持 EIP-1559 的 gas 估算
- Token 转移检测和分析
- 合约交互模拟
- 增强的 BigInt 处理
- 改进的错误上下文
### 网络工具
| Tool | Description | Example |
|------|-------------|---------|
| `get-gas-price` | 获取 Polygon 上的当前 gas 价格 | `const price = await server.getGasPrice()` |
| `switch-network` | 在 Polygon Mainnet 和 Amoy Testnet 之间切换 | `await server.switchNetwork('mainnet')` |
## 架构
Polygon MCP Server 采用模块化架构构建，该架构分离关注点并提高可维护性：
```mermaid
flowchart TD
MCPServer["Polygon MCP Server (polygon-mcp.js)"]
subgraph Modules
BridgeOps["Bridge Operations (bridge-operations.js)"]
ContractOps["Contract Templates (contract-templates.js)"]
DeFiOps["DeFi Interactions (defi-interactions.js)"]
SimOps["Transaction Simulator (transaction-simulation.js)"]
end
subgraph Common ["Common Utilities (common/)"]
WalletManager["Wallet Manager (Singleton)"]
ConfigManager["Configuration Manager"]
Utils["Utility Functions (utils.js)"]
Constants["Constants"]
Logger["Logger (logger.js)"]
Errors["Error Handling (errors.js)"]
Validation["Validation (validation.js)"]
end
MCPServer -- instantiates/uses --> Modules
MCPServer -- uses --> Common
Modules -- use --> Common
```
### 主要组件
1. **Polygon MCP Server (`polygon-mcp.js`)**：主入口点，处理 MCP 通信，实例化模块，注册工具，委派调用。
2. **通用实用程序 (`common/`)**：
* **钱包管理器**：用于集中式钱包状态和访问的单例。
* **配置管理器**：用于集中式配置加载的单例 (`getConfig`)。
* **实用程序函数**：共享助手，如 `resolveTokenAddress`。
* **常量**：共享 ABI，地址。
* **Logger、Errors、Validation**：支持组件。
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`
列出连接钱包（或指定地址）的本机和已知 token 余额。
**参数（可选）：**
- `address` (string)：要检查的地址（默认为连接的钱包）
**返回：** JSON 字符串 `{ "address": "...", "nativeBalance": "...", "tokens": { "USDC": "...", ... } }`
#### `transfer-funds`
将本机 token (POL) 或 ERC20 token 转移到另一个地址。
**参数：**
- `to` (string)：接收者地址
- `amount` (string)：要转移的金额
- `token` (string, optional)：Token 符号或地址（本机 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`
从 Polygon 提取本机 token (POL) 到以太坊。注意：Polygon 已在主网和测试网上将 MATIC 品牌重塑为 POL。
**参数：**
- `amount` (string)：要提取的本机 token (POL) 金额
**返回：** JSON 字符串 `{ "txHash": "0x...", "status": "pending" }`
#### `deposit-token`
将 ERC20 token 从以太坊存入 Polygon。
**参数：**
- `token` (string)：Token 符号或地址
- `amount` (string)：要存入的金额
**返回：** JSON 字符串 `{ "txHash": "0x...", "status": "pending" }`
#### `withdraw-token`
将 ERC20 token 从 Polygon 提取到以太坊。
**参数：**
- `token` (string)：Token 符号或地址
- `amount` (string)：要提取的金额
**返回：** JSON 字符串 `{ "txHash": "0x...", "status": "pending" }`
*（注意：`check-bridge-status` 在 `PolygonBridge` 中实现，但尚未作为 MCP 工具公开）*
## 高级用法
### 组合多个操作
```javascript
// 示例：交换 token，然后桥接到以太坊（使用 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); // 等待交换 tx
// 将 USDC 桥接到以太坊
const bridgeResult = await server.mcpServer.callTool('withdraw-token', { token: 'USDC', amount: '10' });
console.log('Bridge result:', bridgeResult);
}
```
### 自定义合约部署
```javascript
// 使用模板部署自定义 ERC20 token（使用 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]
);
```
### 用于安全性的交易模拟
```javascript
// 在执行交易之前模拟交易（使用 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 兼容实现之前，桥接操作（存款/取款）可能无法正常运行。
### 常见问题
#### “钱包未连接”错误
确保在 `.env` 文件或 MCP 服务器配置中正确设置了 `PRIVATE_KEY`，因为如果提供了密钥，钱包会在服务器启动时自动连接。手动 `connectWallet` 调用不再是主要机制。
#### RPC连接问题
如果您遇到RPC连接问题，请尝试：
1. 检查您的互联网连接
2. 验证您的 `.env` 文件中的RPC端点URLs
3. 使用不同的RPC提供商
#### 资金不足
对于需要gas费用的操作，请确保您的钱包有足够的原生代币 (POL)：
```javascript
const balances = await server.listBalances();
// Check native token balance (POL)
// 检查原生代币余额 (POL)
const nativeToken = 'POL';
console.log(`${nativeToken} balance:`, balances.nativeBalance);
```
#### 交易失败
在发送之前，使用交易模拟器诊断问题：
```javascript
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：
```json
{
"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` - 共享ABIs，地址。
- `wallet-manager.js` - 单例钱包管理器。
- `utils.js` - 集中式实用程序函数（例如，`resolveTokenAddress`）。
## 许可证
该项目已获得MIT许可证的许可 - 有关详细信息，请参阅LICENSE文件。
