内容
# Polygon MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
一个模型上下文协议(Model Context Protocol,MCP)服务器,提供与Polygon区块链网络的无缝集成。该服务器使AI助手能够通过标准化接口与Polygon进行交互,提供全面的工具用于钱包操作、智能合约部署、L2桥接、DeFi交互和交易模拟。
## 目录
- [介绍](#介绍)
- [快速开始](#快速开始)
- [功能](#功能)
- [架构](#架构)
- [API 参考](#api-参考)
- [高级用法](#高级用法)
- [故障排除](#故障排除)
- [贡献](#贡献)
- [安全考虑](#安全考虑)
- [许可证](#许可证)
## 介绍
Polygon 是一种以太坊的第二层扩展解决方案,提供更快和更便宜的交易,同时保持以太坊的安全性。这个 MCP 服务器允许 AI 助手与 Polygon 网络进行交互,通过一个简单、标准化的接口实现广泛的区块链操作。
该服务器充当 AI 系统与 Polygon 区块链之间的桥梁,处理区块链交互的复杂性,并为常见操作提供一个干净、易于使用的 API。
```
┌─────────────┐ ┌───────────────┐ ┌─────────────────┐
│ │ │ │ │ │
│ AI System ├─────┤ Polygon MCP ├─────┤ Polygon Chain │
│ │ │ Server │ │ │
└─────────────┘ └───────────────┘ └─────────────────┘
```
## 快速开始
### 前提条件
- Node.js (v14 或更高版本)
- npm 或 yarn
- 一个 Polygon 钱包的私钥(用于签署交易)
- Polygon 主网和孟买测试网的 RPC 端点
### 安装
1. 克隆代码库或下载源代码
2. 安装依赖:
```bash
cd polygonmcp
npm install
```
3. 创建一个 `.env` 文件,并添加以下变量:
```
# 网络 RPC 端点
POLYGON_MAINNET_RPC=https://polygon-rpc.com
POLYGON_MUMBAI_RPC=https://rpc-mumbai.maticvigil.com
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
# API 密钥
POLYGONSCAN_API_KEY=YOUR_POLYGONSCAN_API_KEY
# 钱包(重要提示:在生产环境中使用安全的密钥管理)
PRIVATE_KEY=your_private_key_here
DEFAULT_NETWORK=mumbai
# DeFi 配置(可选)
DEFAULT_SLIPPAGE=0.5
DEFAULT_DEADLINE_MINUTES=20
```
### 启动服务器
启动服务器:
```bash
npm start
```
用于自动重启的开发模式:
```bash
npm run dev
```
### 第一步骤
1. **检查你的钱包余额**:
```javascript
const { PolygonMCPServer } = require('./polygon-mcp.js');
const server = new PolygonMCPServer();
async function checkBalance() {
server.connectWallet(process.env.PRIVATE_KEY);
const balances = await server.listBalances();
console.log('钱包余额:', balances);
}
checkBalance().catch(console.error);
```
2. **获取测试网 MATIC**(仅限 Mumbai 测试网):
```javascript
async function getTestMatic() {
server.connectWallet(process.env.PRIVATE_KEY);
const result = await server.getTestnetMatic();
console.log('水龙头结果:', result);
}
```
3. **模拟交易**:
```javascript
// 假设在服务器启动时钱包已连接
// server.connectWallet(process.env.PRIVATE_KEY); // 连接在中央处理
async function simulateTransaction() {
const result = await server.simulateTransaction({
to: '0x1234...', // 收件人地址
value: '0.01', // MATIC(或本地代币)中的金额
});
console.log('模拟结果:', result);
}
```
## 特性
### 钱包操作
| 工具 | 描述 | 示例 |
|------|-------------|---------|
| `get-address` | 检索当前钱包地址 | `const address = await server.getAddress()` |
| `get-testnet-matic` | 从水龙头请求测试网POL(仅限Mumbai测试网) | `await server.getTestnetMatic()` |
| `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 多代币
- Staking 合约
- 多签钱包
### L2 桥接操作
| 工具 | 描述 | 示例 |
|------|-------------|---------|
| `deposit-eth` | 从以太坊向Polygon存入ETH | `await server.mcpServer.callTool('deposit-eth', { amount: '0.1' })` |
| `withdraw-eth` | 从Polygon向以太坊提取ETH/POL | `await server.mcpServer.callTool('withdraw-eth', { amount: '0.1' })` |
| `deposit-token` | 从以太坊向Polygon存入ERC20 | `await server.mcpServer.callTool('deposit-token', { token: 'USDC', amount: '100' })` |
| `withdraw-token` | 从Polygon向以太坊提取ERC20 | `await server.mcpServer.callTool('withdraw-token', { token: 'USDC', amount: '100' })` |
| `check-bridge-status` | 检查桥接交易的状态(尚未作为工具实现) | `N/A` |
功能:
- 通过 `PolygonBridge` 类支持ETH和ERC20代币的桥接。
- 在 `bridge-operations.js` 中封装了 `MaticPOSClient` 的使用。
- 增强了桥接操作的错误处理。
- 支持检查点意识(在 `MaticPOSClient` 中固有)。
### 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` | 估算交易的燃气费用 | `const gas = await server.estimateGas(txParams)` |
功能:
- 支持 EIP-1559 的燃气估算
- 代币转移检测与分析
- 合约交互模拟
- 增强的 BigInt 处理
- 改进的错误上下文
### 网络工具
| 工具 | 描述 | 示例 |
|------|-------------|---------|
| `get-gas-price` | 获取Polygon上的当前燃气价格 | `const price = await server.getGasPrice()` |
| `switch-network` | 在Polygon主网和Mumbai测试网之间切换 | `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和地址。
* **日志记录、错误、验证**: 支持组件。
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 Tools)
#### `get-address`
获取连接钱包的地址。
**返回:** JSON 字符串 `{ "address": "0x..." }`
#### `list-balances`
列出连接的钱包(或指定地址)的原生和已知代币余额。
**参数(可选):**
- `address` (string): 要检查的地址(默认为连接的钱包)
**返回:** JSON 字符串 `{ "address": "...", "nativeBalance": "...", "tokens": { "USDC": "...", ... } }`
#### `transfer-funds`
将原生代币 (POL) 或 ERC20 代币转移到另一个地址。
**参数:**
- `to` (string): 收件人地址
- `amount` (string): 转账金额
- `token` (string, 可选): 代币符号或地址(如果是原生 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, 可选): 合约构造函数的参数
**返回:** JSON字符串 `{ "address": "0x...", "transactionHash": "0x...", ... }`
#### `verify-contract`(当前未作为MCP工具公开)
在Polygonscan上验证合约。
**参数:**
- `address`(字符串):合约地址
- `name`(字符串):合约名称
- `code`(字符串):合约源代码
- `constructorArgs`(数组):构造函数参数
**返回:** 对象 - 验证结果(如果作为工具实现)
### 桥接操作(通过 MCP 工具)
#### `deposit-eth`
将ETH从Ethereum存入Polygon。
**参数:**
- `amount` (string): 要存入的ETH数量
**返回:** JSON字符串 `{ "txHash": "0x...", "status": "pending" }`
#### `withdraw-eth`
从Polygon提取ETH/POL到Ethereum。
**参数:**
- `token` (字符串): 代币符号或地址
- `amount` (字符串): 要桥接的数量
**返回:** JSON字符串 `{ "txHash": "0x...", "status": "pending" }`
#### `deposit-token`
将ERC20代币从以太坊存入Polygon。
**参数:**
- `token` (string): 代币符号或地址
- `amount` (string): 存入的金额
**返回:** JSON字符串 `{ "txHash": "0x...", "status": "pending" }`
#### `withdraw-token`
从Polygon提取ERC20代币到Ethereum。
**参数:**
- `token` (string): 代币符号或地址
- `amount` (string): 提取的数量
**返回:** JSON字符串 `{ "txHash": "0x...", "status": "pending" }`
*(注意:`check-bridge-status` 在 `PolygonBridge` 中实现,但尚未作为MCP工具公开)*
## 高级用法
### 组合多个操作
```javascript
// 示例:交换代币然后桥接到以太坊(使用MCP工具的概念性示例)
async function swapAndBridge() {
// 假设服务器正在运行,钱包通过环境/配置连接
// 将MATIC交换为USDC(使用一个假设的交换工具 - 需要实现)
// const swapResult = await server.mcpServer.callTool('swap-tokens', { fromToken: 'MATIC', toToken: 'USDC', amount: '10' });
// console.log('交换结果:', 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('桥接结果:', bridgeResult);
}
```
### 自定义合约部署
```javascript
// 使用模板部署自定义 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('合约部署在:', 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() {
// 假设服务器正在运行,钱包通过环境/配置连接
const txParams = {
to: '0x1234...',
value: '1000000000000000000', // 1 POL以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('交易将失败:', simulation.errorMessage);
return;
}
// 检查燃气费用
console.log('预计燃气费用:', simulation.gasCost.ether, 'MATIC');
// 如果模拟成功则执行(使用transfer-funds工具)
const transferResult = await server.mcpServer.callTool('transfer-funds', {
to: txParams.to,
amount: '1.0' // 工具中的金额以POL为单位
});
console.log('交易已发送:', transferResult);
}
```
## 故障排除
### 常见问题
#### "钱包未连接" 错误
确保在 `.env` 文件或 MCP 服务器配置中正确设置了 `PRIVATE_KEY`,因为如果提供了密钥,钱包将在服务器启动时自动连接。手动调用 `connectWallet` 不再是主要机制。
#### RPC连接问题
如果您遇到RPC连接问题,请尝试以下方法:
1. 检查您的互联网连接
2. 验证`.env`文件中的RPC端点URL
3. 使用不同的RPC提供商
#### 资金不足
对于需要支付燃气费用的操作,请确保您的钱包中有足够的 MATIC:
```javascript
const balances = await server.listBalances();
console.log('MATIC balance:', balances.MATIC);
```
#### 交易失败
使用交易模拟器在发送之前诊断问题:
```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. 提交一个拉取请求
### 开发环境设置
1. 克隆代码库
2. 安装依赖:`npm install`
3. 创建一个 `.env.test` 文件并添加测试凭据
4. 运行测试:`npm test`
5. 运行代码检查:`npm run lint`
## 安全考虑
该服务器处理私钥和敏感的区块链操作。对于生产环境的使用:
1. 永远不要将私钥存储在代码或环境变量中
2. 使用安全的密钥管理系统或硬件钱包集成
3. 实施适当的身份验证和授权
4. 添加速率限制以防止滥用
5. 添加全面的日志记录和监控
6. 验证所有输入参数
7. 实施适当的错误处理
8. 使用安全的配置管理
## MCP 集成
### 添加到 MCP 设置
要将此服务器与 Claude 或其他兼容 MCP 的系统一起使用,请将其添加到您的 MCP 设置配置文件中:
对于 Cursor/Claude 开发:
```json
{
"mcpServers": {
"polygon": {
"command": "node",
"args": ["path/to/polygon-mcp.js"],
"env": {
"POLYGON_MAINNET_RPC": "https://polygon-rpc.com",
"POLYGON_MUMBAI_RPC": "https://rpc-mumbai.maticvigil.com",
"ETHEREUM_RPC_URL": "https://eth-mainnet.alchemyapi.io/v2/YOUR_ALCHEMY_KEY",
"POLYGONSCAN_API_KEY": "YOUR_POLYGONSCAN_API_KEY",
"PRIVATE_KEY": "your_private_key_here",
"DEFAULT_NETWORK": "mumbai",
"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 文件。
连接信息
猜你喜欢
暂无推荐服务器