Futarchy402 MCP

Futarchi402 MCP

Futarchi402治理平台的多平台人工智能工具，具有x402支付门控投票功能。

概述

Futarchi402 MCP为AI代理提供了一个统一的接口，用于跨多个框架与Futarchi402治理平台进行交互：

• OpenAI -函数调用
• Anthropic Claude -工具使用
• 模型上下文协议（MCP） -人工智能工具的标准协议
• LangChain -代理框架集成

所有平台共享相同的核心实现，包括关键的 x402支付门控投票协议.

特性

• 🗳️ 全面治理整合 -列出民意调查，获取详细信息，查看职位
• 💰 x402支付协议 -在链上执行付款门控投票
• 🔌 多平台支持 -与OpenAI、Claude、MCP、LangChain合作
• 🛠️ 类型安全 -完全支持TypeScript
• 🧪 测试良好 -全面的测试覆盖率
• 📦 树摇晃 -只导入您需要的内容

安装

npm install @futarchy402/mcp

快速开始

OpenAI

import { OpenAIFutarchyAdapter } from '@futarchy402/mcp/adapters/openai';
import OpenAI from 'openai';

const openai = new OpenAI();
const adapter = new OpenAIFutarchyAdapter();

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Show me open polls' }],
  tools: adapter.getTools(),
});

// Handle tool calls
for (const toolCall of response.choices[0].message.tool_calls || []) {
  const result = await adapter.executeFunction(
    toolCall.function.name,
    toolCall.function.arguments
  );
  console.log(result);
}

Anthropic Claude

import { ClaudeFutarchyAdapter } from '@futarchy402/mcp/adapters/anthropic';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();
const adapter = new ClaudeFutarchyAdapter();

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Show me open polls' }],
  tools: adapter.getTools(),
});

// Handle tool uses in response.content

MCP服务器（克劳德桌面）

地点： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

基本配置（主网）：

{
  "mcpServers": {
    "futarchy402": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@futarchy402/mcp/dist/adapters/mcp/server.js"],
      "env": {
        "FUTARCHY_NETWORK": "mainnet"
      }
    }
  }
}

使用钱包进行Devnet配置：

{
  "mcpServers": {
    "futarchy402": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@futarchy402/mcp/dist/adapters/mcp/server.js"],
      "env": {
        "FUTARCHY_NETWORK": "devnet",
        "WALLET_PRIVATE_KEY": "your-devnet-wallet-base58-key"
      }
    }
  }
}

⚠️ 安全警告： 仅限使用 WALLET_PRIVATE_KEY 在配置中使用devnet键。对于主网，每次让Claude询问密钥。

更新配置后，重新启动Claude Desktop。

LangChain

import { LangChainFutarchyAdapter } from '@futarchy402/mcp/adapters/langchain';
import { ChatOpenAI } from '@langchain/openai';
import { createToolCallingAgent, AgentExecutor } from 'langchain/agents';

const adapter = new LangChainFutarchyAdapter();
const tools = adapter.getTools();

const llm = new ChatOpenAI({ modelName: 'gpt-4o' });
const agent = await createToolCallingAgent({ llm, tools, prompt });
const executor = new AgentExecutor({ agent, tools });

const result = await executor.invoke({
  input: 'What polls are open?',
});

直接使用SDK

import { Futarchy402Client, executeVote } from '@futarchy402/mcp';

const client = new Futarchy402Client();

// List polls
const { polls } = await client.listPolls({ status: 'open' });

// Get poll details
const poll = await client.getPoll('poll-id');

// Get position
const position = await client.getPosition('poll-id', 'wallet-pubkey');

// Vote (x402 payment-gated)
const result = await executeVote({
  pollId: 'poll-id',
  side: 'yes',
  walletPrivateKey: 'base58-key',
  slippage: 0.05,
});

可用工具

所有平台都公开了这5个工具：

1. futarchy_list_polls

列出具有可选过滤功能的治理民意调查。

参数：

• status （可选）-按“打开”或“已解决”筛选
• treasury_id （可选）-按金库筛选
• limit （可选）-最大结果（默认值：20）
• offset （可选）-分页偏移

退货： 一系列包含流动性、费用、概率和投票计数的民意调查

2. futarchy_get_poll

获取有关特定投票的详细信息，包括所有投票。

参数：

• poll_id （必填）-轮询标识符

退货： 完整的投票详情，包括提案信息、流动性统计数据、所有投票

3. futarchy_get_position

在损益预测的民意调查中获得钱包的位置。

参数：

• poll_id （必填）-轮询标识符
• voter_pubkey （必填）-Solana钱包公钥

退货： 职位详情、预测、实际结果（如已解决）

4. futarchy_vote

使用x402协议执行付款门控投票。

参数：

• poll_id （必填）-投票表决
• side （必填）-“是”或“否”
• wallet_private_key （可选）-Base58编码私钥（可以使用 WALLET_PRIVATE_KEY 改为env var）
• slippage （可选）-最大滑动公差（默认值：0.05=5%）

退货： 投票结果，包括交易签名、金额、滑点

⚠️ 重要： 这执行了一个真正的链上交易，成本为USDC。

钱包配置选项：

1. 每次提示输入密钥（最安全-建议用于主网）：

- 人工智能在投票时会要求你提供钱包钥匙 - 密钥从不存储 - 在提供密钥之前，您会对每张投票进行审核

1. 环境变量（便于测试）：

   export WALLET_PRIVATE_KEY="your-base58-private-key"

- AI在投票时自动使用此密钥 - 仅与devnet密钥一起用于测试 - 切勿将主网密钥存储在环境变量中

1. 在工具调用中提供：

   await adapter.executeFunction('futarchy_vote', {
     poll_id: 'abc123',
     side: 'yes',
     wallet_private_key: 'your-base58-key'
   });

5. futarchy_get_stats

获取平台范围内的统计数据。

退货： 活跃民意调查、项目总数、提案总数

x402支付协议

投票机制使用x402支付门控协议：

1. 请求投票→ 收到402付款要求
2. 使用@solana/SPL代币构建SPL代币转账交易
3. 使用钱包签署交易
4. 提交已签名的交易 X-Payment 标题到投票端点

这是在 src/core/x402.ts 手柄：

• SPL代币转账交易楼
• 防滑保护
• 防止重复投票
• 交易确认
• 全面的错误处理

配置

网络选择

SDK支持主网和开发网。 始终先在devnet上测试！

这 network 参数决定了哪个Solana网络（主网/devnet）用于事务签名。Futarchy402 API URL对于两个网络都是相同的。

# Set network (mainnet or devnet)
FUTARCHY_NETWORK=devnet

# API URL (same for both networks)
FUTARCHY_API_URL="https://futarchy402-api-385498168887.us-central1.run.app"

或者以编程方式配置：

import { Futarchy402Client } from '@futarchy402/mcp';

// Use devnet for testing
const devnetClient = new Futarchy402Client({
  network: 'devnet'
});

// Use mainnet for production
const mainnetClient = new Futarchy402Client({
  network: 'mainnet'
});

环境变量

# Network selection (default: mainnet)
FUTARCHY_NETWORK=devnet

# Wallet private key for voting (optional - only use with devnet!)
WALLET_PRIVATE_KEY="your-base58-private-key"

# Override API URL (optional)
FUTARCHY_API_URL="https://custom-api.example.com"

# Override Solana RPC endpoints (optional)
SOLANA_RPC_DEVNET="https://api.devnet.solana.com"
SOLANA_RPC_MAINNET="https://api.mainnet-beta.solana.com"

自定义配置

import { Futarchy402Client } from '@futarchy402/mcp';

const client = new Futarchy402Client({
  apiBaseUrl: 'https://custom-api.example.com',
  network: 'devnet',
});

建筑

futarchy402-mcp/
├── src/
│   ├── core/           # Platform-agnostic SDK
│   │   ├── client.ts   # API client
│   │   ├── x402.ts     # Payment-gated voting
│   │   ├── wallet.ts   # Solana utilities
│   │   └── types.ts    # Type definitions
│   ├── tools/          # Universal tool definitions
│   │   ├── definitions.ts
│   │   └── handlers.ts
│   └── adapters/       # Platform-specific adapters
│       ├── openai/
│       ├── anthropic/
│       ├── mcp/
│       └── langchain/
└── examples/           # Integration examples

例子

请参阅 examples/ 完整工作示例目录：

• OpenAI函数调用
• 拟人克劳德工具使用
• MCP配置
• 朗链代理

发展

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format

安全

关键安全指南

• 从不提交私钥 到版本控制（.env文件位于.gitignore中）
• 从不存储主网密钥 在环境变量或配置文件中
• 仅限使用 WALLET_PRIVATE_KEY 带有devnet密钥的env-var 用于测试
• 签署前审查所有交易
• 在使用主网之前，始终在devnet上进行测试
• 这 futarchy_vote 该工具执行花费USDC的真实链上交易

钱包密钥最佳实践

对于Devnet测试：

• ✅ 将devnet密钥存储在 WALLET_PRIVATE_KEY 环境变量
• ✅ 添加到MCP服务器配置以方便使用
• ✅ 用于自动化测试

对于主网生产：

• ✅ 让AI每次提示钱包钥匙
• ✅ 在提供密钥之前查看投票详细信息
• ✅ 将密钥保存在安全密码管理器中
• ❌ 切勿在环境变量中存储
• ❌ 从不存储在配置文件中
• ❌ 从不承诺版本控制

许可证

麻省理工学院

链接

• Futarchi402平台
• x402协议
• MCP规范
• OpenAI函数调用
• 克劳德工具使用
• LangChain