x402拍卖MCP服务器
A. 简单, 清洁 MCP服务器，使AI代理能够参与x402拍卖。
🎯 采用KISS和SOLID原则构建| 343行代码| 4个API端点
为什么是这个项目？
✅ 保持简单 -简单易读的代码，没有不必要的复杂性\ ✅ SOLID -单一责任的清洁架构\ ✅ 类型安全 -带有正确类型的完整TypeScript\ ✅ 有据可查 -清晰的示例和架构文档\ ✅ 生产准备就绪 -正确的错误处理和验证
特性
- 获取拍卖信息：检查当前拍卖状态、价格、总筹集额和可用供应量
- 创建出价：在拍卖中出价（每个钱包1-100TON）
- 检查投标状态：监控您的出价支付状态和估计的代币分配
- 查看最近出价：查看最新完成的投标详情
安装
npm install构建
npm run build用法
运行服务器
npm start或者用于自动重建的开发：
npm run dev故障排除
如果您遇到多个实例或卡住流程的问题：
# Clean up any running instances
npm run cleanup这将安全地终止任何现有的x402拍卖mcp进程。
使用Claude Desktop进行配置
将此添加到您的Claude Desktop配置文件中：
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
选项1：使用npm包（如果已发布，建议使用）
{
"mcpServers": {
"x402-auction": {
"command": "x402-auction-mcp"
}
}
}方案2：地方发展
{
"mcpServers": {
"x402-auction": {
"command": "node",
"args": ["/path/to/x402-auction-mcp/build/index.js"]
}
}
}确保更新路径以匹配您的实际安装位置。
选项3：使用npm链接（用于开发）
# In the x402-auction-mcp directory
npm link
# Then in Claude Desktop config:{ "mcpServers": { "x402-auction": { "command": "x402-auction-mcp" } } }
## 可用工具
### 1. `get_auction_info`
获取当前拍卖状态和参数。
**参数**：无
**示例响应**:
{ "status": "active", "current_price": 0.5, "total_raised": 1500.0, "available_supply": 100000 }
### 2. `create_auction_bid`
在拍卖中创建出价。返回支付指令（HTTP 402）。
**参数**:
- `ton_amount` （数量，必填）：投标金额（1-100吨）
- `wallet` （string，必填）：您的TON钱包地址
**重要提示**:
- 每个钱包一次出价
- 付款将在180秒后到期
- 付款后不退款
**示例响应**:
{ "bid_id": "abc123", "payment_address": "EQD...", "amount": 5, "expires_at": "2025-10-28T12:03:00Z", "message": "Send 5 TON to address with bid_id as comment" }
### 3. `get_my_bid`
检查您的出价状态。
**参数**:
- `wallet` （string，必填）：您的TON钱包地址
**示例响应**:
{ "bid_id": "abc123", "wallet": "UQBlen...", "ton_amount": 5, "payment_status": "confirmed", "estimated_tokens": 10000, "price": 0.5, "timestamp": "2025-10-28T12:00:00Z" }
### 4. `get_recent_bids`
获取最近完成的出价列表。
**参数**:
- `limit` （数字，可选）：要返回的出价数量（默认值：20，最大值：100）
**示例响应**:
{ "bids": [ { "bidder": "UQBlen...", "amount": 5, "price": 0.5, "timestamp": "2025-10-28T12:00:00Z" } ], "total": 150 }
## API终点
此MCP服务器与以下x402拍卖API端点接口：
- `GET /api/auction/info` -拍卖状态
- `GET /api/auction/bid` -创建出价（返回402）
- `GET /api/auction/my-bid` -检查出价状态
- `GET /api/auction/bids` -最近出价列表
## 响应代码
- `200 OK` -成功
- `402 Payment Required` -已创建投标，需要付款
- `409 Conflict` -此钱包已存在出价
- `410 Gone` -拍卖已结束
- `422 Invalid Amount` -投标金额无效
## 发展
项目结构：
x402agent/ ├── src/ │ ├── index.ts # MCP server (routing) │ ├── handlers.ts # Business logic & validation │ ├── api.ts # HTTP client │ ├── types.ts # TypeScript types │ └── constants.ts # Configuration ├── build/ # Compiled JavaScript ├── docs/ # Documentation └── package.json
**固态架构** -每个文件都有一个明确的责任。
## 错误处理
该服务器包括全面的错误处理功能，用于：
- 投标金额无效
- 钱包地址无效
- API错误（冲突、消失、无效数量）
- 网络错误
- 付款超时
错误以结构化格式返回，其中包含错误代码和消息。
## 许可证
麻省理工学院
## API 参考
基本URL: `https://x402.palette.finance/api/auction`
有关x402拍卖的更多信息，请访问 [调色板金融](https://x402.palette.finance).
## 安装
### 面向最终用户
**选项1：从npm安装（发布时）**
npm install -g x402-auction-mcp
**选项2：从GitHub安装**
git clone https://github.com/ilyaqznetsow/x402-auction-mcp.git cd x402-auction-mcp npm install npm run build
______________________________________________________________________
## 在不同环境中的使用
### 1.克劳德桌面
**配置文件位置：**
- macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
- 窗户： `%APPDATA%\Claude\claude_desktop_config.json`
**如果通过npm全局安装：**
{ "mcpServers": { "x402-auction": { "command": "x402-auction-mcp" } } }
**如果本地安装：**
{ "mcpServers": { "x402-auction": { "command": "node", "args": ["/absolute/path/to/x402-auction-mcp/build/index.js"] } } }
然后重新启动Claude Desktop。
______________________________________________________________________
### 2.光标IDE
Cursor支持MCP服务器！在Cursor的设置中配置：
**设置→ MCP服务器** 或创建/编辑配置文件：
- macOS： `~/Library/Application Support/Cursor/mcp_config.json`
- 窗户： `%APPDATA%\Cursor\mcp_config.json`
- Linux： `~/.config/Cursor/mcp_config.json`
{ "mcpServers": { "x402-auction": { "command": "npx", "args": ["x402-auction-mcp"] } } }
或者本地安装：
{ "mcpServers": { "x402-auction": { "command": "node", "args": ["/absolute/path/to/x402-auction-mcp/build/index.js"] } } }
重新启动Cursor，然后在AI聊天中使用MCP工具！
______________________________________________________________________
### 3.Cline（VS代码扩展）
Cline通过以下设置支持MCP服务器：
1. 打开VS代码设置（Cmd/Ctrl+，）
1. 搜索“临床MCP”
1. 添加MCP服务器配置：
{ "cline.mcpServers": { "x402-auction": { "command": "x402-auction-mcp" } } }
或编辑 `.vscode/settings.json` 在您的工作空间中。
______________________________________________________________________
### 4.程序化使用（Node.js）
您还可以在自己的应用程序中以编程方式使用MCP服务器：
import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
// Connect to the MCP server const transport = new StdioClientTransport({ command: 'x402-auction-mcp' });
const client = new Client({ name: 'my-app', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);
// List available tools const tools = await client.listTools(); console.log(tools);
// Call a tool const result = await client.callTool({ name: 'get_auction_info', arguments: {} });
console.log(result);
______________________________________________________________________
### 5.任何MCP兼容客户端
服务器使用标准的MCP stdio协议，因此它适用于支持MCP的任何客户端：
**基本用法：**
Start the server (it reads from stdin, writes to stdout)
x402-auction-mcp
Or with node directly:
node /path/to/build/index.js
**通信格式：** 基于stdio的JSON-RPC 2.0
请求示例：
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_auction_info", "arguments": {} } }
______________________________________________________________________
## 开发者：发布你的分叉
看 [发布.md](PUBLISHING.md) 有关以下内容的详细说明：
- 发布到npm
- 发布到GitHub
- 版本控制和更新
- 营销您的MCP服务器