# https://github.com/PrintrFi/printr-mcp 项目说明书
生成时间：2026-05-31 00:23:58 UTC
## 目录
- [项目概览](#overview)
- [安装配置](#installation)
- [Monorepo 结构](#monorepo-structure)
- [SDK 架构](#sdk-architecture)
- [MCP 服务器架构](#mcp-server-architecture)
- [MCP 工具列表](#mcp-tools)
- [钱包与签名](#wallet-signing)
- [交易工具](#trading-tools)
- [Workers 兼容性与优化](#workers-compatibility)
- [部署指南](#deployment)
## 项目概览
### 相关页面
相关主题：[安装配置](#installation), [Monorepo 结构](#monorepo-structure), [MCP 服务器架构](#mcp-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/sdk/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/README.md)
- [packages/mcp/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
- [packages/cli/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/package.json)
- [packages/mcp/src/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
- [examples/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
# 项目概览
## 简介
Printr MCP 是一个基于 Model Context Protocol (MCP) 的 AI Agent 工具包，用于在多条区块链上创建和管理代币。该项目由 PrintrFi 团队开发，目标是为 AI 助手提供原生的链上操作能力，使用户能够通过自然语言在 Base、以太坊、Solana 等区块链上部署代币、查询余额、执行交易等操作。
项目采用 monorepo 结构，包含三个核心包：
| 包名 | 描述 |
|------|------|
| `@printr/sdk` | TypeScript SDK，提供链上操作的底层接口 |
| `@printr/mcp` | MCP 服务器包，将 SDK 功能暴露为 MCP 工具 |
| `@printr/cli` | CLI 工具，用于在各种 AI 客户端中安装 Printr 技能 |
资料来源：[README.md:1-10](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
---
## 架构设计
### 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ AI Agent (用户) │
└─────────────────────────┬───────────────────────────────────┘
│ 自然语言请求
▼
┌─────────────────────────────────────────────────────────────┐
│ MCP Client SDK │
└─────────────────────────┬───────────────────────────────────┘
│ MCP 协议 (stdio/HTTP)
▼
┌─────────────────────────────────────────────────────────────┐
│ @printr/mcp Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ MCP Tools Layer │ │
│ │ - printr_quote - printr_get_token │ │
│ │ - printr_create_token - printr_get_deployments │ │
│ │ - printr_launch_token - printr_sign_and_submit_* │ │
│ │ - printr_get_balance - printr_generate_image │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│ SDK 调用
▼
┌─────────────────────────────────────────────────────────────┐
│ @printr/sdk │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Client │ │ Token │ │ Wallet │ │
│ │ (gRPC) │ │ Builder │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Balance │ │ Image │ │ Transfer │ │
│ │ Queries │ │ Generator │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ EVM RPC │ │ SVM RPC │ │ Printr │
│(viem) │ │(solana.js)│ │ API │
└──────────┘ └──────────┘ └──────────┘
```
### 技术栈
#### SDK 依赖
`@printr/sdk` 的核心依赖包括：
| 依赖 | 版本 | 用途 |
|------|------|------|
| `@bufbuild/protobuf` | ^1.10.1 | Protocol Buffers 运行时 |
| `@connectrpc/connect` | ^1.7.0 | gRPC-Web 协议实现 |
| `@connectrpc/connect-web` | ^1.7.0 | Web 端 gRPC 支持 |
| `@solana/web3.js` | ^1.98.4 | Solana 区块链交互 |
| `@solana/spl-token` | ^0.4.14 | SPL 代币标准支持 |
| `viem` | ^2.49.0 | EVM 区块链交互 |
| `openapi-fetch` | ^0.17.0 | REST API 调用 |
| `sharp` | ^0.34.5 | 图片处理 |
| `zod` | ~4.3.6 | 类型验证 |
| `neverthrow` | ^8.2.0 | Result 类型安全错误处理 |
| `@openrouter/sdk` | ^0.8.0 | AI 图片生成 |
资料来源：[packages/sdk/package.json:20-40](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
#### MCP 包依赖
`@printr/mcp` 继承 SDK 依赖并扩展 MCP 特定配置：
```typescript
// 环境变量配置
const mcpSchema = z.object({
// API 配置
PRINTR_API_KEY: z.string(),
PRINTR_API_BASE_URL: z.string(),
// 图片生成
OPENROUTER_API_KEY: z.string().optional(),
OPENROUTER_IMAGE_MODEL: z.string(),
// 区块链 RPC
ALCHEMY_API_KEY: z.string().optional(),
RPC_URLS: z.record(z.string(), z.string()),
// 钱包配置
EVM_WALLET_PRIVATE_KEY: z.string().optional(),
SVM_WALLET_PRIVATE_KEY: z.string().optional(),
// MCP 特定
AGENT_MODE: z.string().optional(),
PRINTR_DEPLOYMENT_PASSWORD: z.string().optional(),
});
```
资料来源：[packages/mcp/src/lib/env.ts:11-35](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
---
## 核心功能
### 1. 代币创建与部署
通过 `printr_create_token` 和 `printr_launch_token` 工具，AI Agent 可以：
- 指定代币名称、符号、描述
- 选择部署网络（Base、Ethereum、Solana 等）
- 设置初始购买金额
- 自动生成代币图标
- 一键创建并签名交易
```typescript
const result = await buildToken(
{
creator_accounts: ['eip155:8453:0xYourAddress'],
name: 'My Token',
symbol: 'TKN',
description: 'A cool token',
chains: ['eip155:8453'], // Base
initial_buy: { spend_usd: 10 },
},
client,
);
```
资料来源：[packages/sdk/README.md:35-50](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/README.md)
### 2. 多链支持
Printr MCP 支持以下区块链网络：
| 链类型 | 链 | CAIP-2 标识 |
|--------|-----|-------------|
| EVM | Base | `eip155:8453` |
| EVM | Ethereum | `eip155:1` |
| EVM | Testnet | `eip155:84532` |
| SVM | Solana | `solana:...` |
工具清单：
| 工具名 | 功能 |
|--------|------|
| `printr_quote` | 获取代币创建成本估算 |
| `printr_create_token` | 生成未签名交易载荷 |
| `printr_launch_token` | 创建并签名代币 |
| `printr_get_token` | 查询代币详情 |
| `printr_get_deployments` | 检查跨链部署状态 |
资料来源：[README.md:35-50](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
### 3. 钱包管理
#### 部署钱包
MCP 支持两种钱包模式：
1. **浏览器签名模式**：通过 `printr_open_web_signer` 启动浏览器会话（MetaMask/Phantom）
2. **私钥直传模式**：通过环境变量设置默认私钥
```json
{
"env": {
"EVM_WALLET_PRIVATE_KEY": "",
"SVM_WALLET_PRIVATE_KEY": ""
}
}
```
#### 钱包工具
| 工具名 | 功能 |
|--------|------|
| `printr_get_token_balance` | 查询 ERC-20/SPL 代币余额 |
| `printr_sign_and_submit_evm` | 签名并提交 EVM 交易 |
| `printr_sign_and_submit_svm` | 签名并提交 Solana 交易 |
| `drain_deployment_wallet` | 回收部署钱包资金 |
资料来源：[packages/mcp/src/tools/get-token-balance.ts:1-30](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
### 4. 图片生成
当设置 `OPENROUTER_API_KEY` 后，Agent 可以：
- 在创建代币时自动生成图标
- 使用 `printr_generate_image` 工具独立生成图片
```json
{
"env": {
"OPENROUTER_API_KEY": ""
}
}
```
---
## MCP 工具完整列表
| 工具 | 文件位置 | 描述 |
|------|----------|------|
| `printr_quote` | `packages/mcp/src/tools/quote.ts` | 获取代币创建成本估算 |
| `printr_create_token` | `packages/mcp/src/tools/create-token.ts` | 生成未签名代币创建交易 |
| `printr_launch_token` | `packages/mcp/src/tools/launch-token.ts` | 一站式创建并签名代币 |
| `printr_get_token` | `packages/mcp/src/tools/get-token.ts` | 按 ID 或地址查询代币详情 |
| `printr_get_deployments` | `packages/mcp/src/tools/get-deployments.ts` | 查询跨链部署状态 |
| `printr_sign_and_submit_evm` | `packages/mcp/src/tools/sign-and-submit-evm.ts` | 签名并提交 EVM 交易 |
| `printr_sign_and_submit_svm` | `packages/mcp/src/tools/sign-and-submit-svm.ts` | 签名并提交 Solana 交易 |
| `printr_open_web_signer` | `packages/mcp/src/tools/open-web-signer.ts` | 启动浏览器签名会话 |
| `printr_generate_image` | `packages/mcp/src/tools/generate-image.ts` | AI 生成代币头像 |
| `printr_get_token_balance` | `packages/mcp/src/tools/get-token-balance.ts` | 查询代币余额 |
| `claim_staking_rewards` | `packages/mcp/src/tools/claim-staking-rewards.ts` | 领取质押奖励 |
资料来源：[README.md:45-60](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
---
## 环境变量
| 变量 | 必需 | 描述 |
|------|------|------|
| `PRINTR_API_KEY` | 否 | 合作伙伴 API 密钥，默认为公共 AI 集成密钥 |
| `PRINTR_API_BASE_URL` | 否 | Printr API 地址 |
| `OPENROUTER_API_KEY` | 可选 | 启用图片自动生成功能 |
| `OPENROUTER_IMAGE_MODEL` | 可选 | 图片生成模型覆盖 |
| `EVM_WALLET_PRIVATE_KEY` | 可选 | EVM 链私钥（十六进制） |
| `SVM_WALLET_PRIVATE_KEY` | 可选 | Solana 私钥（Base58） |
| `ALCHEMY_API_KEY` | 可选 | Alchemy RPC 提供商密钥 |
| `RPC_URLS` | 可选 | 自定义 RPC URL 映射 |
| `AGENT_MODE` | 可选 | 代理模式配置 |
资料来源：[README.md:65-75](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
---
## 客户端安装
Printr MCP 支持通过 `@printr/cli` 快速安装到各类 AI 客户端：
```bash
npx @printr/cli setup
```
支持的客户端包括 Cursor、Claude Desktop、Cline 等。安装后，Agent 将自动识别 Printr 技能定义并加载相关工具。
资料来源：[packages/cli/src/commands/setup/components/summary.tsx:1-25](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/setup/components/summary.tsx)
---
## 开发与测试
### 项目结构
```
printr-mcp/
├── packages/
│ ├── sdk/ # 核心 SDK
│ │ ├── src/
│ │ │ ├── client/ # API 客户端
│ │ │ ├── token/ # 代币构建器
│ │ │ ├── wallet/ # 钱包管理
│ │ │ ├── balance/ # 余额查询
│ │ │ ├── image/ # 图片处理
│ │ │ └── proto/ # Protobuf 定义
│ │ └── README.md
│ ├── mcp/ # MCP 服务器
│ │ ├── src/
│ │ │ ├── tools/ # MCP 工具实现
│ │ │ ├── server/ # 服务器入口
│ │ │ └── lib/ # 工具函数
│ │ └── package.json
│ └── cli/ # CLI 工具
│ ├── src/
│ │ ├── commands/ # CLI 命令
│ │ └── skills/ # Agent 技能定义
│ └── package.json
└── examples/
├── sdk-basic/ # SDK 基本示例
└── mcp-client/ # MCP 客户端示例
```
### 运行示例
```bash
# 安装依赖
bun install
# 构建所有包
bun run build
# 运行 SDK 示例
bun run --cwd examples/sdk-basic start
# 运行 MCP 客户端示例
bun run --cwd examples/mcp-client start
# 执行测试
bun test
```
资料来源：[examples/README.md:1-35](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
---
## 路线图与社区动态
### 当前开发重点
根据 GitHub Issues 追踪，项目正围绕以下主题推进：
#### Epic A: SDK Workers-ready
目标：使 `@printr/sdk` 能够在 Cloudflare Workers / Edge 运行时上运行，无需 vendoring。
相关 Issue：
- #97: 移除 `createRequire` shim
- #96: 懒加载 `sharp` 和 `node:fs`
- #101: 轻量级余额查询（绕过 web3.js）
#### Epic B: 共享 SDK 原语
目标：将 MCP 内部逻辑提取为共享 SDK 子路径。
相关 Issue：
- #100: 提取 signer 原语到 `@printr/sdk/signer`
- #104: 共享 SDK 原语
#### Epic C: Agent 交易 UX
目标：使 Agent 能够执行 swap、buy、sell、bridge 操作。
相关 Issue：
- #62: 交易工具（按 ticker 交易）
- #63: 跨链桥接工具
### 最新发布
**SDK v0.6.1** (2026-05-18)
- 修复：pin zod 到 ~4.3.6 以兼容 MCP SDK 1.29
---
## 总结
Printr MCP 是一个功能完整的 AI Agent 链上操作框架，通过 MCP 协议将区块链能力以工具形式暴露给 AI 助手。项目采用模块化设计，SDK 层提供底层接口，MCP 层负责协议适配和工具封装，CLI 层简化客户端安装流程。
核心优势：
- **多链支持**：覆盖 EVM (Base/Ethereum) 和 Solana
- **类型安全**：完整的 TypeScript 支持和 Zod schema 验证
- **灵活签名**：支持浏览器钱包和私钥直传两种模式
- **AI 集成**：内置图片生成和自然语言交互能力
如需更多信息，请访问：
- 项目主页：https://github.com/PrintrFi/printr-mcp
- 技能定义：[packages/cli/skills/printr/SKILL.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/skills/printr/SKILL.md)
---
## 安装配置
### 相关页面
相关主题：[项目概览](#overview), [钱包与签名](#wallet-signing)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
- [packages/sdk/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/README.md)
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/cli/src/commands/setup/components/summary.tsx](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/skill/components/summary.tsx)
- [packages/cli/src/commands/setup/components/banner.tsx](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/setup/components/banner.tsx)
- [examples/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
- [packages/mcp/src/tools/get-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-balance.ts)
- [packages/mcp/src/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
# 安装配置
## 概述
Printr MCP 项目提供两种主要的安装配置方式：SDK 编程调用和 MCP 服务器集成。SDK 适用于需要在应用程序中直接集成 Printr 功能的开发者，而 MCP 服务器适用于 AI Agent 通过标准协议调用 Printr 工具的场景。项目支持 EVM 链（Base、Ethereum、BNB Chain 等）和 Solana 链的统一配置管理。
资料来源：[README.md:1-50]()
## SDK 安装配置
### 环境要求
SDK 支持 Node.js 18 及以上版本运行环境，支持 Bun 和 npm 等包管理工具。SDK 依赖包含 `@solana/web3.js`、`viem`、`@bufbuild/protobuf` 等区块链开发库。
资料来源：[packages/sdk/package.json:18]()
### 安装方式
```bash
npm install @printr/sdk
# 或
bun add @printr/sdk
# 或
yarn add @printr/sdk
```
资料来源：[packages/sdk/README.md:20-28]()
### 创建客户端
SDK 使用 `createPrintrClient` 工厂函数创建客户端实例，支持通过环境变量或直接传入配置：
```typescript
import { createPrintrClient } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
```
配置参数说明：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `apiKey` | `string` | 是 | Printr API 密钥 |
| `baseUrl` | `string` | 否 | API 基础地址，默认 `https://api-preview.printr.money` |
资料来源：[packages/sdk/README.md:30-45]()
### 多环境支持
SDK 支持通过环境变量切换不同运行环境：
| 环境变量 | 说明 |
|----------|------|
| `PRINTR_API_KEY` | API 认证密钥 |
| `PRINTR_API_BASE_URL` | API 服务地址 |
| `EVM_WALLET_PRIVATE_KEY` | EVM 链钱包私钥 |
| `SVM_WALLET_PRIVATE_KEY` | Solana 钱包私钥 (Base58 格式) |
资料来源：[README.md:40-55]()
## MCP 服务器配置
### MCP 协议集成
MCP 服务器通过 Model Context Protocol 与 AI Agent 通信，支持 stdio 和 HTTP 两种传输方式。配置时需要在 AI 客户端（如 Cursor、Claude Desktop 等）的 MCP 配置文件中声明服务器路径。
MCP 服务器工作流程：
```mermaid
graph TD
A[AI Agent] -->|MCP Protocol| B[printr-mcp Server]
B -->|gRPC/WebSocket| C[Printr API]
C -->|Blockchain| D[EVM Chains]
C -->|Blockchain| E[Solana]
B -->|RPC| F[EVM Wallets]
B -->|RPC| G[SVM Wallets]
```
资料来源：[README.md:10-30]()
### 必需环境变量
MCP 服务器的必需环境变量用于控制 API 访问权限和链上交互能力：
| 环境变量 | 说明 | 必需 |
|----------|------|------|
| `PRINTR_API_KEY` | Printr API 密钥 | 是 |
| `PRINTR_API_BASE_URL` | API 地址 | 否 |
| `EVM_WALLET_PRIVATE_KEY` | EVM 链十六进制私钥 | 交易时必需 |
| `SVM_WALLET_PRIVATE_KEY` | Solana Base58 私钥 | 交易时必需 |
| `OPENROUTER_API_KEY` | 启用图片生成功能 | 可选 |
资料来源：[README.md:40-55]()
### 钱包签名配置
MCP 工具支持三种签名方式，优先级从高到低：
1. **浏览器钱包签名**：默认方式，通过 URL 会话引导用户在浏览器中签名交易
2. **请求级私钥**：每次工具调用时通过参数传入私钥
3. **环境变量默认密钥**：设置 `EVM_WALLET_PRIVATE_KEY` 或 `SVM_WALLET_PRIVATE_KEY` 实现自主签名
> ⚠️ 注意：环境变量中的私钥会暴露给所有能访问配置的进程，建议使用环境级别的密钥管理服务。
资料来源：[README.md:50-60]()
## CLI 工具配置
### 技能安装流程
Printr MCP CLI 提供交互式安装向导，支持自动检测和配置主流 AI 客户端：
```bash
npx printr-mcp setup
```
CLI 安装流程如下：
```mermaid
graph LR
A[运行 setup] --> B[检测客户端]
B --> C[显示 Banner]
C --> D[选择要配置的客户端]
D --> E[配置 MCP 服务器]
E --> F[显示安装摘要]
```
CLI 支持的客户端列表：`Claude Desktop`、`Cursor`、`Windsurf`、`Cline`、` Roo Code`、`Open Code`、`A Cody`、`Void` 等。
资料来源：[packages/cli/src/commands/setup/components/banner.tsx:1-15]()
### 安装摘要展示
安装完成后，CLI 会显示配置结果摘要：
| 场景 | 显示内容 |
|------|----------|
| 安装成功 | `✓ Installed for N client(s)` + 重启提示 |
| 无客户端检测到 | `⚠ Nothing to configure` + 支持列表 |
| 已有配置 | 自动跳过已配置客户端 |
资料来源：[packages/cli/src/commands/setup/components/summary.tsx:1-35]()
### 技能安装
对于需要 AI Agent 能力的场景，可使用 skill 命令安装 Printr 技能：
```bash
npx printr-mcp skill install
```
该命令将 printr 技能定义安装到检测到的 AI 客户端代理中。
资料来源：[packages/cli/src/commands/skill/components/summary.tsx:1-25]()
## 链配置
### 支持的链
Printr MCP 支持通过 CAIP-2 规范标识各链，格式为 `namespace:reference`：
| 链类型 | Namespace | 示例 | 用途 |
|--------|-----------|------|------|
| Ethereum | `eip155` | `eip155:1` | Ethereum Mainnet |
| Base | `eip155` | `eip155:8453` | Base Mainnet |
| Solana | `solana` | `solana:mainnet` | Solana Mainnet |
资料来源：[packages/mcp/src/tools/get-balance.ts:30-45]()
### 余额查询配置
余额查询工具支持原生代币和 SPL/ERC-20 代币余额查询：
**原生代币查询** (`printr_get_balance`)：
```typescript
inputSchema = {
account: "eip155:8453:0x...", // CAIP-10 格式地址
rpc_url: "https://...", // 可选，自定义 RPC
}
```
**代币余额查询** (`printr_get_token_balance`)：
```typescript
inputSchema = {
token: "eip155:8453:0xTokenAddress", // 代币 CAIP-10
wallet: "eip155:8453:0xWalletAddress", // 钱包 CAIP-10
rpc_url: "https://...", // 可选
}
```
资料来源：[packages/mcp/src/tools/get-balance.ts:1-50]()
## 典型配置场景
### 场景一：仅查询（只读）
适用于不需要签名交易的场景：
```json
{
"mcpServers": {
"printr": {
"command": "npx",
"args": ["-y", "printr-mcp"]
}
},
"env": {
"PRINTR_API_KEY": "your-api-key"
}
}
```
资料来源：[README.md:25-40]()
### 场景二：自主交易签名
适用于 AI Agent 需要自主执行链上交易的场景：
```json
{
"mcpServers": {
"printr": {
"command": "npx",
"args": ["-y", "printr-mcp"]
}
},
"env": {
"PRINTR_API_KEY": "your-api-key",
"EVM_WALLET_PRIVATE_KEY": "0x...",
"SVM_WALLET_PRIVATE_KEY": "base58..."
}
}
```
资料来源：[README.md:50-60]()
### 场景三：启用图片生成
适用于需要 AI 生成代币头像的场景：
```json
{
"mcpServers": {
"printr": {
"command": "npx",
"args": ["-y", "printr-mcp"]
}
},
"env": {
"PRINTR_API_KEY": "your-api-key",
"OPENROUTER_API_KEY": "your-openrouter-key"
}
}
```
资料来源：[README.md:30-40]()
## 验证配置
### 本地示例测试
项目提供本地示例用于验证 SDK 和 MCP 配置：
```bash
bun install
bun run build
# 测试 SDK 基本功能
bun run --cwd examples/sdk-basic start
# 测试 MCP 客户端
bun run --cwd examples/mcp-client start
```
资料来源：[examples/README.md:10-35]()
### 可用工具列表
配置完成后，AI Agent 可使用以下工具：
| 工具名 | 功能 |
|--------|------|
| `printr_quote` | 获取代币创建成本估算 |
| `printr_create_token` | 生成无符号代币创建交易 |
| `printr_launch_token` | 创建并签名代币 |
| `printr_get_token` | 查询代币详情 |
| `printr_get_deployments` | 查询部署记录 |
| `printr_get_balance` | 查询原生代币余额 |
| `printr_get_token_balance` | 查询 ERC-20/SPL 代币余额 |
资料来源：[README.md:60-80]()
## 故障排除
### 常见配置问题
| 问题 | 原因 | 解决方案 |
|------|------|----------|
| `Invalid CAIP-10 address` | 地址格式错误 | 使用 `namespace:chainId:address` 格式 |
| `Unsupported chain` | 链标识符不正确 | 检查 CAIP-2 格式，如 `eip155:8453` |
| `Treasury wallet not configured` | 未设置钱包环境变量 | 设置 `EVM_WALLET_PRIVATE_KEY` 或 `SVM_WALLET_PRIVATE_KEY` |
| API 认证失败 | `PRINTR_API_KEY` 未设置或已过期 | 检查并更新 API 密钥 |
资料来源：[packages/mcp/src/tools/get-balance.ts:35-50]()
### RPC 连接问题
使用自定义 RPC 时，确保：
1. RPC URL 可公开访问
2. 支持对应的链 ID
3. 有足够的请求配额
---
## Monorepo 结构
### 相关页面
相关主题：[项目概览](#overview), [SDK 架构](#sdk-architecture), [MCP 服务器架构](#mcp-server-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [package.json](https://github.com/PrintrFi/printr-mcp/blob/main/package.json)
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/mcp/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
- [packages/cli/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/package.json)
- [packages/sdk/src/client.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/client.ts)
- [packages/sdk/src/balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/balance.ts)
- [packages/sdk/src/image.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/image.ts)
# Monorepo 结构
## 概述
printr-mcp 是一个基于 **Bun** 和 **pnpm workspaces** 的 TypeScript monorepo 项目，托管于 `https://github.com/PrintrFi/printr-mcp`。项目采用现代 monorepo 架构，包含三个核心包，分别负责 SDK 核心功能、MCP 服务器和 CLI 工具。
根目录 `package.json` 定义了完整的工作区结构和统一的任务脚本，支持跨包的构建、测试和类型检查。资料来源：[package.json:1-20]()
## 工作区架构
### 包结构一览
项目采用标准的 monorepo 布局，核心包位于 `packages/` 目录下：
| 包名 | 路径 | 描述 | 引擎要求 |
|------|------|------|----------|
| `@printr/sdk` | `packages/sdk` | 核心 TypeScript SDK，支持多链代币创建与管理 | Node >= 18 |
| `@printr/mcp` | `packages/mcp` | MCP 服务器，封装 SDK 为 Model Context Protocol 工具 | Node >= 18 |
| `@printr/cli` | `packages/cli` | CLI 工具，用于设置和配置 | - |
资料来源：[package.json:9]()
```mermaid
graph TD
A[printr-mcp root] --> B[packages/sdk]
A --> C[packages/mcp]
A --> D[packages/cli]
A --> E[examples/]
B --> B1[Core API Client]
B --> B2[EVM Support]
B --> B3[SVM Support]
B --> B4[Balance Queries]
B --> B5[Image Processing]
C --> C1[MCP Tools]
C --> C2[Server]
C --> C3[Wallet Management]
D --> D1[Setup Command]
D --> D2[Skill Command]
D --> D3[Dev Command]
```
## SDK 包结构
### 导出配置
`@printr/sdk` 包提供了精细化的子路径导出，允许消费者按需导入，避免不必要的依赖引入：
| 导出路径 | 类型入口 | 用途 |
|----------|----------|------|
| `.` | `index.js` | 主入口，包含所有核心功能 |
| `./client` | `client.js` | PrintrClient 客户端创建 |
| `./chains` | `chains.js` | 链配置和元数据 |
| `./evm` | `evm.js` | EVM 链操作 |
| `./svm` | `svm.js` | Solana 链操作 |
| `./schemas` | `schemas.js` | Zod 验证模式 |
| `./caip` | `caip.js` | CAIP-10 地址解析 |
| `./balance` | `balance.js` | 余额查询（含 web3 依赖） |
| `./balance-lite` | `balance-lite.js` | 轻量级余额查询 |
| `./transfer` | `transfer.js` | 代币转账 |
资料来源：[packages/sdk/package.json:28-70]()
### 依赖管理
SDK 包的依赖分为核心依赖和 Node.js 专有依赖两部分：
**核心依赖**（可在边缘/Workers 环境运行）：
- `@bufbuild/protobuf` — Protocol Buffers 支持
- `@connectrpc/connect` / `@connectrpc/connect-web` — gRPC-web
- `@openrouter/sdk` — OpenRouter API
- `bs58` — Base58 编解码
- `neverthrow` — 错误处理
- `openapi-fetch` — OpenAPI 客户端
- `pino` — 日志
- `ts-pattern` — 模式匹配
- `zod` — 运行时验证
**Node.js 专有依赖**（静态导入）：
- `@solana/spl-token` — SPL Token 操作
- `@solana/web3.js` — Solana Web3（约 600KB）
- `viem` — EVM 交互（约 500KB）
- `sharp` — 图像处理
> **重要提示**：由于这些 Node.js 专有依赖的体积较大，项目正在推进 "Epic A: SDK Workers-ready" 计划（Issue #103），目标是在不 vendoring 的情况下让 SDK 能在 Cloudflare Workers 环境中正常评估和运行。资料来源：[packages/sdk/package.json:37-60]()
### 客户端创建
SDK 的核心入口是 `createPrintrClient` 函数：
```typescript
import { createPrintrClient } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY,
baseUrl: 'https://api-preview.printr.money',
});
```
资料来源：[packages/sdk/src/client.ts:1-50]()
## MCP 包结构
### MCP 工具注册
MCP 包将 SDK 功能封装为 Model Context Protocol 工具。工具通过统一的注册机制暴露：
```typescript
server.registerTool(
"printr_get_balance",
{
description: "获取钱包的原生代币余额",
inputSchema,
outputSchema,
},
handler
);
```
资料来源：[packages/mcp/src/tools/get-balance.ts:40-55]()
### 核心工具列表
| 工具名称 | 功能 |
|----------|------|
| `printr_quote` | 获取代币创建成本估算 |
| `printr_create_token` | 生成未签名代币创建交易 |
| `printr_launch_token` | 创建并签名代币 |
| `printr_get_token` | 按 ID 或地址查询代币详情 |
| `printr_get_deployments` | 查询跨链部署状态 |
| `printr_get_balance` | 查询原生代币余额 |
| `printr_get_token_balance` | 查询 ERC-20/SPL 代币余额 |
| `printr_sign_and_submit_evm` | 签名并提交 EVM 交易 |
| `printr_sign_and_submit_svm` | 签名并提交 Solana 交易 |
| `printr_open_web_signer` | 启动浏览器签名会话 |
| `printr_generate_image` | 通过 OpenRouter 生成代币头像 |
资料来源：[README.md:30-50]()
### 环境变量配置
MCP 包扩展了 SDK 的环境变量，并添加了 MCP 特定的配置：
| 变量 | 必需 | 描述 |
|------|------|------|
| `PRINTR_API_KEY` | 是 | 合作伙伴 API 密钥 |
| `PRINTR_API_BASE_URL` | 是 | API 基础 URL |
| `EVM_WALLET_PRIVATE_KEY` | 否 | EVM 钱包私钥（十六进制） |
| `SVM_WALLET_PRIVATE_KEY` | 否 | Solana 钱包私钥（Base58） |
| `OPENROUTER_API_KEY` | 否 | 启用图像生成 |
| `PRINTR_DEPLOYMENT_PASSWORD` | 否 | 部署钱包加密主密码 |
| `AGENT_MODE` | 否 | 代理模式 |
资料来源：[packages/mcp/src/lib/env.ts:15-35]()
## CLI 包结构
### 命令模块
CLI 包提供了交互式终端界面，使用 `ink`（React for CLI）构建：
| 命令 | 功能 |
|------|------|
| `setup` | 检测并配置支持的 AI 客户端 |
| `skill` | 为代理安装 printr skill |
| `dev` | 启动 MCP 服务器（热重载） |
资料来源：[packages/cli/src/commands/setup/components/summary.tsx:1-30]()
### 客户端检测
CLI 工具会自动检测支持的 AI 客户端，包括 Claude Desktop、Cursor、Windsurf 等，并生成相应的配置文件。资料来源：[packages/cli/src/commands/setup/lib/clients.ts]()
## 构建与测试
### 根目录任务脚本
| 脚本 | 功能 |
|------|------|
| `bun dev` | 启动 MCP 服务器（热重载） |
| `bun test` | 运行所有测试 |
| `bun run check` | 类型检查 + lint + 测试 |
| `bun run build` | 构建 SDK 和所有包 |
资料来源：[package.json:12-18]()
### 包级别任务
每个包可以独立运行其任务：
```bash
# SDK
bun run --cwd packages/sdk test
bun run --cwd packages/sdk build
# MCP
bun run --cwd packages/mcp test
bun run --cwd packages/mcp build
```
### 构建流程
```mermaid
graph LR
A[TypeScript Source] --> B[tsconfig]
B --> C[Bun Build Script]
C --> D[packages/sdk/dist]
C --> E[packages/mcp/dist]
C --> F[packages/cli/dist]
D --> G[type declarations]
E --> H[MCP Server Bundle]
F --> I[CLI Bundle]
```
## 版本与发布
### 当前版本
| 包 | 版本 | 发布日期 |
|----|------|----------|
| `@printr/sdk` | v0.6.1 | 2026-05-18 |
最新版本修复了与 MCP SDK 1.29 兼容的 zod 版本锁定问题。资料来源：[packages/sdk/package.json:3]()
## 社区驱动的发展方向
根据社区讨论和 issues，项目正朝着以下方向发展：
### Epic A: SDK Workers-ready (Issue #103)
目标：使 `@printr/sdk` 能在 Cloudflare Workers 环境中正常评估和运行。子任务包括：
- 添加 `./balance-lite` 轻量级余额查询（Issue #101）
- 移除 `createRequire` shim（Issue #97）
- 延迟加载 `sharp` 和 `node:fs`（Issue #96）
- 添加 types-only `./openapi` 入口（Issue #98）
### Epic B: 共享 SDK 原语 (Issue #104)
目标：将 MCP 内部逻辑提取到共享 SDK 子路径，包括签名原语。
### Epic C: Agent 交易 UX (Issue #105)
目标：支持代币交换、购买、出售和跨链桥接功能。
## 快速开始
```bash
# 安装依赖
bun install
# 开发模式运行 MCP 服务器
bun dev
# 运行所有测试
bun test
# 完整检查（类型 + lint + 测试）
bun run check
```
## 技术栈总结
| 类别 | 技术选型 |
|------|----------|
| 运行时 | Bun |
| 包管理器 | pnpm workspaces |
| 语言 | TypeScript 6.0+ |
| 验证 | Zod ~4.3.6 |
| 链交互 | viem (EVM), @solana/web3.js (Solana) |
| RPC | Alchemy, 定制 JSON-RPC |
| 协议 | Protocol Buffers, gRPC-web |
| CLI UI | ink (React for CLI) |
---
## SDK 架构
### 相关页面
相关主题：[Monorepo 结构](#monorepo-structure), [MCP 工具列表](#mcp-tools), [Workers 兼容性与优化](#workers-compatibility)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/sdk/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/index.ts)
- [packages/sdk/src/client.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/client.ts)
- [packages/sdk/src/token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/token.ts)
- [packages/sdk/src/balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/balance.ts)
- [packages/sdk/src/balance-lite.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/balance-lite.ts)
- [packages/sdk/src/rpc.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/rpc.ts)
- [packages/sdk/src/caip.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/caip.ts)
- [packages/sdk/src/evm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/evm.ts)
- [packages/sdk/src/svm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/svm.ts)
- [packages/sdk/src/image.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/image.ts)
- [packages/sdk/src/keystore.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/keystore.ts)
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
# SDK 架构
## 概述
`@printr/sdk` 是 Printr 的 TypeScript SDK，提供了跨 EVM 链（Base、Ethereum 等）和 Solana 创建与管理代币的完整能力。该 SDK 采用模块化设计，支持多种运行环境，包括 Node.js、Bun 以及 Cloudflare Workers 等边缘运行时。
SDK 的核心目标是：
- 提供类型安全的 API 客户端，支持 Zod schema 验证
- 封装区块链交互细节，简化代币创建与管理流程
- 支持多种签名方式（浏览器钱包、私钥、服务端钱包）
- 针对不同运行时环境提供优化变体
资料来源：[packages/sdk/package.json:1-10]()
## 包结构与导出
### 目录组织
```
packages/sdk/
├── src/
│ ├── index.ts # 主入口（barrel export）
│ ├── client.ts # PrintrClient 客户端
│ ├── token.ts # 代币创建相关
│ ├── balance.ts # 余额查询（完整版）
│ ├── balance-lite.ts # 余额查询（轻量版）
│ ├── rpc.ts # RPC 配置管理
│ ├── caip.ts # CAIP-10/CAIP-2 地址解析
│ ├── evm.ts # EVM 链交互
│ ├── svm.ts # Solana 链交互
│ ├── image.ts # 图片生成处理
│ ├── keystore.ts # 加密钱包存储
│ ├── chains.ts # 链配置
│ ├── transfer.ts # 转账功能
│ └── env.ts # 环境变量配置
└── dist/ # 编译输出
```
### Subpath Exports
SDK 采用 subpath exports 模式，允许消费者按需导入，避免引入不必要的依赖：
| Subpath | 说明 | 主要依赖 |
|---------|------|----------|
| `./client` | PrintrClient 及相关类型 | openapi-fetch, connectrpc |
| `./chains` | 链配置与元数据 | - |
| `./evm` | EVM 链交互工具 | viem |
| `./svm` | Solana 交互工具 | @solana/web3.js, @solana/spl-token |
| `./schemas` | Zod schemas | zod |
| `./caip` | CAIP 地址解析 | - |
| `./balance` | 完整余额查询 | viem, @solana/web3.js |
| `./balance-lite` | 轻量余额查询（JSON-RPC 直连） | - |
| `./transfer` | 转账功能 | viem, @solana/web3.js |
资料来源：[packages/sdk/package.json:15-60]()
### 条件导出（Conditional Exports）
为支持边缘运行时，SDK 在 `package.json` 中配置了条件导出：
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
},
"./balance": {
"types": "./dist/balance.d.ts",
"import": "./dist/balance.js"
},
"./balance-lite": {
"types": "./dist/balance-lite.d.ts",
"import": "./dist/balance-lite.js"
}
}
}
```
这种设计确保了边缘运行时可以按需加载子模块，而不会因为主入口的静态依赖（如 `sharp`、`node:fs`）导致 bundle 过大。
资料来源：[packages/sdk/package.json:15-60]()
## 核心模块架构
### 客户端模块
#### PrintrClient
`PrintrClient` 是 SDK 的核心入口，通过 `createPrintrClient` 工厂函数创建：
```typescript
import { createPrintrClient } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
```
客户端内部使用 `openapi-fetch` 与 Printr API 通信，并集成了：
- **ConnectRPC**: 支持 gRPC-web 协议
- **OpenAPI Types**: 完整的 TypeScript 类型支持
- **Zod 验证**: 响应数据的运行时验证
资料来源：[packages/sdk/src/client.ts:1-50]()
#### buildToken 流程
`buildToken` 函数是代币创建的核心入口：
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const result = await buildToken(
{
creator_accounts: ['eip155:8453:0xYourAddress'],
name: 'My Token',
symbol: 'TKN',
description: 'A cool token',
chains: ['eip155:8453'], // Base
initial_buy: { spend_usd: 10 },
},
client,
);
```
该函数内部处理：
1. 调用 Printr API 获取创建报价
2. 构建跨链部署事务
3. 返回带类型的 `TokenCreateResponse`
资料来源：[packages/sdk/src/token.ts:1-80]()
### 链交互模块
#### EVM 模块
`evm.ts` 提供 EVM 链（Base、Ethereum 等）的交互能力：
- 创建 EVM 钱包客户端
- 发送签名交易
- 解析合约地址
- 处理链上事件
主要依赖 `viem` 库，提供类型安全的以太坊交互。
资料来源：[packages/sdk/src/evm.ts:1-50]()
#### SVM 模块
`svm.ts` 提供 Solana 链的交互能力：
- 创建 Solana 连接和签名者
- 发送交易
- 处理 SPL Token 操作
- 账户余额查询
主要依赖 `@solana/web3.js` 和 `@solana/spl-token`。
资料来源：[packages/sdk/src/svm.ts:1-50]()
#### CAIP 地址解析
`caip.ts` 实现了 CAIP-10 和 CAIP-2 规范，用于跨链地址标准化：
- `parseCaip10()`: 解析链地址（如 `eip155:8453:0x...`）
- `toCaip2()`: 提取链 ID（CAIP-2）
- `toCaip10()`: 构建完整 CAIP-10 地址
这些工具确保了跨链操作时地址的一致性。
资料来源：[packages/sdk/src/caip.ts:1-60]()
### 余额查询模块
#### 完整版（balance.ts）
标准余额查询模块，使用 `viem` 和 `@solana/web3.js`：
```typescript
import { getBalance } from '@printr/sdk/balance';
const result = await getBalance({
address: 'eip155:8453:0x...',
chainId: 'eip155:8453',
rpcUrl: 'https://...',
});
```
**问题**：完整版会引入约 600KB 的 `@solana/web3.js` 和 `viem` 依赖，对边缘运行时造成较大负担。
资料来源：[packages/sdk/src/balance.ts:1-60]()
#### 轻量版（balance-lite.ts）
为边缘运行时优化的余额查询模块，直接通过 JSON-RPC 调用：
```typescript
import { getBalanceLite } from '@printr/sdk/balance-lite';
const result = await getBalanceLite({
address: 'SolanaAddress',
rpcUrl: 'https://api.mainnet-beta.solana.com',
});
```
**优势**：
- 零额外依赖
- 支持 Cloudflare Workers
- 适用于只读余额查询场景
资料来源：[packages/sdk/src/balance-lite.ts:1-40]()
资料来源：[issues/101](https://github.com/PrintrFi/printr-mcp/issues/101)
### 图片处理模块
`image.ts` 提供代币头像的 AI 生成能力：
```typescript
import { processImagePath } from '@printr/sdk';
const result = await processImagePath('/path/to/image.png', {
size: 512,
format: 'webp',
});
```
**当前问题**：
- 静态导入 `sharp` 和 `node:fs/promises`
- 任何从 barrel 导入都会触发 Node.js 特定依赖
**优化计划**：实现 `processImageBytes()` 变体，支持从 Uint8Array 输入，适合浏览器和边缘环境。
资料来源：[packages/sdk/src/image.ts:1-50]()
资料来源：[issues/96](https://github.com/PrintrFi/printr-mcp/issues/96)
资料来源：[issues/102](https://github.com/PrintrFi/printr-mcp/issues/102)
### 钱包存储模块
`keystore.ts` 提供安全的加密钱包存储：
- AES-256-GCM 加密
- 内存中的钱包缓存
- 主密码保护
```typescript
import { keystore } from '@printr/sdk';
const wallet = await keystore.load({
id: 'my-wallet',
password: process.env.PRINTR_DEPLOYMENT_PASSWORD!,
});
```
资料来源：[packages/sdk/src/keystore.ts:1-80]()
## RPC 配置管理
`rpc.ts` 集中管理链的 RPC 配置：
```typescript
import { ALCHEMY_RPC_TEMPLATES, rpcUrlsSchema } from '@printr/sdk';
const configs = getRpcConfigs('mainnet');
```
支持的环境：
- `mainnet`
- `testnet`
- `devnet`
每个环境维护独立的 RPC URL 映射，并支持 Alchemy RPC 模板。
资料来源：[packages/sdk/src/rpc.ts:1-40]()
## 边缘运行时兼容性
### Epic A: SDK Workers-ready
当前主要技术债务是使 SDK 完全兼容 Cloudflare Workers 等边缘运行时。核心问题包括：
| 问题 | 影响 | 解决方案 |
|------|------|----------|
| `createRequire` shim | 每个模块顶部注入 CJS 兼容代码 | 移除 shim，生成纯 ESM bundle |
| `sharp` 静态导入 | 引入 Node.js 特定依赖 | 改为动态导入/懒加载 |
| `node:fs` 静态导入 | 阻塞浏览器环境 | 提取到独立子路径 |
| 完整版 balance 依赖 | ~600KB bundle | 提供 `balance-lite` 变体 |
**验收标准**：Worker 导入 SDK barrel 不抛出异常。
资料来源：[issues/103](https://github.com/PrintrFi/printr-mcp/issues/103)
资料来源：[issues/97](https://github.com/PrintrFi/printr-mcp/issues/97)
### 懒加载策略
为解决 Node.js 特定依赖问题，SDK 采用懒加载模式：
```typescript
// 静态导入（会触发依赖）
import { buildToken } from '@printr/sdk';
// 懒加载（条件执行）
async function getImageProcessor() {
const { default: sharp } = await import('sharp');
return sharp;
}
```
这种方式确保边缘运行时不会加载无用的 Node.js 模块。
资料来源：[issues/96](https://github.com/PrintrFi/printr-mcp/issues/96)
## 依赖管理
### 主要运行时依赖
| 依赖 | 用途 | 体积 |
|------|------|------|
| `@solana/web3.js` | Solana 交互 | ~600KB |
| `viem` | EVM 交互 | ~300KB |
| `sharp` | 图片处理 | ~2MB |
| `neverthrow` | Result 类型 | ~10KB |
| `zod` | Schema 验证 | ~100KB |
### 子路径与依赖隔离
通过子路径导出，SDK 实现依赖隔离：
```mermaid
graph TD
A[消费者导入] --> B[主入口 ./]
A --> C[./balance-lite]
A --> D[./svm]
A --> E[./evm]
B --> F[所有依赖]
C --> G[零额外依赖]
D --> H[@solana/web3.js]
E --> I[viem]
F --> J{运行时环境}
J -->|Node.js| K[完整功能]
J -->|Edge| L[按需加载]
```
这种方式允许边缘环境只导入 `balance-lite` 等轻量模块，而不会引入完整的 Solana/EVM 库。
资料来源：[packages/sdk/package.json:25-60]()
## 环境变量配置
### SDK 环境变量
| 变量 | 必需 | 说明 |
|------|------|------|
| `PRINTR_API_KEY` | 是 | Printr API 密钥 |
| `PRINTR_API_BASE_URL` | 否 | API 基础 URL，默认 `https://api-preview.printr.money` |
| `RPC_URLS` | 是 | JSON 格式的 RPC URL 映射 |
### 扩展配置
SDK 提供 `getConfigs(env)` 函数统一管理环境配置：
```typescript
import { getConfigs } from '@printr/sdk';
const configs = getConfigs('mainnet');
// { apiBaseUrl, appUrl, rpcUrls, ... }
```
配置经过 memoize 优化，避免重复计算。
资料来源：[issues/82](https://github.com/PrintrFi/printr-mcp/issues/82)
## 未来架构演进
### Epic B: Shared SDK Primitives
计划将 MCP 内部逻辑提取到 SDK 共享子路径：
1. **签名器原语** (`./signer`): 统一的浏览器/服务端签名接口
2. **配置管理**: 环境判别与配置获取的统一入口
资料来源：[issues/104](https://github.com/PrintrFi/printr-mcp/issues/104)
资料来源：[issues/100](https://github.com/PrintrFi/printr-mcp/issues/100)
### Epic C: Agent Trading UX
SDK 规划的交易功能：
| 功能 | 说明 |
|------|------|
| Swap | 代币交换 |
| Buy/Sell | 按 ticker 交易 |
| Bridge | 跨链桥接（Base ↔ Solana） |
资料来源：[issues/105](https://github.com/PrintrFi/printr-mcp/issues/105)
资料来源：[issues/62](https://github.com/PrintrFi/printr-mcp/issues/62)
资料来源：[issues/63](https://github.com/PrintrFi/printr-mcp/issues/63)
## 快速开始
### 安装
```bash
npm install @printr/sdk
# 或
bun add @printr/sdk
```
### 基本用法
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
});
const result = await buildToken(
{
creator_accounts: ['eip155:8453:0xYourAddress'],
name: 'My Token',
symbol: 'TKN',
description: 'A cool token',
chains: ['eip155:8453'],
initial_buy: { spend_usd: 10 },
},
client,
);
if (result.isOk()) {
console.log('Token created:', result.value.token_id);
}
```
### 边缘环境用法
```typescript
import { getBalanceLite } from '@printr/sdk/balance-lite';
const balance = await getBalanceLite({
address: 'SolanaAddress...',
rpcUrl: 'https://api.mainnet-beta.solana.com',
});
```
## 总结
`@printr/sdk` 采用模块化、类型安全的架构设计，通过 subpath exports 实现依赖按需加载。当前重点方向是边缘运行时兼容性（Epic A），通过 `balance-lite`、懒加载 `sharp`/`node:fs` 等措施，使 SDK 可在 Cloudflare Workers 等受限环境中运行。
长期规划包括共享 SDK 原语（Epic B）和交易功能（Epic C），旨在为 Agent 提供完整的代币生命周期管理能力。
---
## MCP 服务器架构
### 相关页面
相关主题：[Monorepo 结构](#monorepo-structure), [MCP 工具列表](#mcp-tools), [钱包与签名](#wallet-signing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/index.ts)
- [packages/mcp/src/mcp.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/mcp.ts)
- [packages/mcp/src/server/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/server/index.ts)
- [packages/mcp/src/server/app.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/server/app.ts)
- [packages/mcp/src/server/sessions.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/server/sessions.ts)
- [packages/mcp/src/server/wallet-sessions.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/server/wallet-sessions.ts)
- [packages/mcp/src/lib/logging.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/logging.ts)
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
- [packages/mcp/src/lib/wallet-elicit.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/wallet-elicit.ts)
- [packages/mcp/src/tools/launch-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/launch-token.ts)
- [packages/mcp/src/tools/transfer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/transfer.ts)
# MCP 服务器架构
## 概述
`@printr/mcp` 是 Printr 项目的 MCP（Model Context Protocol）服务器实现，使 AI Agent 能够通过标准化接口在 EVM 链（如 Base、Ethereum）和 Solana 链上创建和管理代币。服务器基于 `@modelcontextprotocol/sdk` 构建，提供一套完整的工具（Tools）用于代币发行、钱包管理、余额查询、转账等操作。
当前版本为 **v0.16.1**，支持节点环境 Node.js >= 18。资料来源：[packages/mcp/package.json]()
## 整体架构
```mermaid
graph TB
subgraph "MCP Server Layer"
MCP[MCP Server Core
@modelcontextprotocol/sdk]
TOOLS[Tools Registry
Token/Transfer/Balance...]
end
subgraph "Server Layer"
APP[App Server
app.ts]
SESSIONS[Session Manager
sessions.ts]
WALLET_SESSIONS[Wallet Sessions
wallet-sessions.ts]
end
subgraph "Business Logic Layer"
LAUNCH[launch-token.ts]
TRANSFER[transfer.ts]
GET_TOKEN[get-token.ts]
DRAIN[drain-deployment-wallet.ts]
end
subgraph "SDK Layer"
SDK[@printr/sdk]
BALANCE[balance.ts]
IMAGE[image.ts]
TOKEN[token.ts]
end
subgraph "External Services"
API[Printr API
api.printr.money]
RPC[RPC Providers
Alchemy/Custom]
OPENROUTER[OpenRouter
Image Generation]
end
MCP --> TOOLS
TOOLS --> LAUNCH
TOOLS --> TRANSFER
TOOLS --> GET_TOKEN
TOOLS --> DRAIN
APP --> SESSIONS
APP --> WALLET_SESSIONS
SESSIONS --> WALLET_SESSIONS
LAUNCH --> SDK
TRANSFER --> SDK
GET_TOKEN --> SDK
DRAIN --> SDK
SDK --> API
SDK --> RPC
SDK --> OPENROUTER
```
## 目录结构
```
packages/mcp/src/
├── index.ts # 入口文件，导出 MCP 服务器
├── mcp.ts # MCP 工具注册和服务器初始化
├── lib/ # 核心工具库
│ ├── env.ts # 环境变量配置
│ ├── logging.ts # 日志工具
│ ├── wallet-elicit.ts # 钱包解析和验证
│ ├── drain.ts # 部署钱包清空逻辑
│ ├── treasury.ts # 金库密钥管理
│ └── qr.ts # 二维码生成
├── server/ # 服务器核心
│ ├── index.ts # 服务器导出
│ ├── app.ts # HTTP 应用（会话启动）
│ ├── sessions.ts # 浏览器会话管理
│ └── wallet-sessions.ts # 活跃钱包状态
└── tools/ # MCP 工具实现
├── launch-token.ts
├── create-token.ts
├── quote.ts
├── get-token.ts
├── transfer.ts
├── get-token-balance.ts
├── get-deployments.ts
├── sign-and-submit-evm.ts
├── sign-and-submit-svm.ts
├── open-web-signer.ts
├── generate-image.ts
└── drain-deployment-wallet.ts
```
资料来源：[packages/mcp/src/index.ts]()、[packages/mcp/src/mcp.ts]()
## 服务器启动流程
```mermaid
sequenceDiagram
participant CLI as CLI / Entry
participant MCP as MCP Server
participant APP as App Server
participant SDK as @printr/sdk
participant ENV as Environment
CLI->>ENV: 加载环境变量
CLI->>MCP: 创建 MCP Server 实例
MCP->>SDK: 初始化 PrintrClient
MCP->>MCP: 注册所有 Tools
CLI->>APP: 启动会话服务器
alt Web Signer Mode
APP->>APP: 启动本地 HTTP 服务器
APP->>APP: 生成随机端口
Note over APP: LOCAL_SESSION_ORIGIN
end
CLI->>MCP: 连接传输层
MCP->>MCP: 开始处理请求
```
## 核心组件详解
### 1. 环境配置（env.ts）
`env.ts` 定义了 MCP 服务器所需的所有环境变量，整合了 SDK 环境变量和 MCP 特有变量。
```typescript
const mcpSchema = z.object({
// SDK 继承的环境变量
PRINTR_API_KEY: z.string(),
PRINTR_API_BASE_URL: z.string(),
OPENROUTER_API_KEY: z.string().optional(),
OPENROUTER_IMAGE_MODEL: z.string(),
ALCHEMY_API_KEY: z.string().optional(),
RPC_URLS: z.record(z.string(), z.string()),
// MCP 特有环境变量
EVM_WALLET_PRIVATE_KEY: z.string().optional(),
SVM_WALLET_PRIVATE_KEY: z.string().optional(),
AGENT_MODE: z.string().optional(),
PRINTR_DEPLOYMENT_PASSWORD: z.string().optional(),
PRINTR_BACKEND_URL: z.string(),
PRINTR_APP_URL: z.string().default("https://app.printr.money"),
PRINTR_CDN_URL: z.string().default("https://cdn.printr.money"),
VERBOSE: z.string().optional(),
PRINTR_TEST_TOKEN_ID: z.string().optional(),
});
```
| 环境变量 | 必填 | 说明 |
|---------|------|------|
| `PRINTR_API_KEY` | 是 | Printr API 密钥 |
| `PRINTR_API_BASE_URL` | 是 | Printr API 基础 URL |
| `OPENROUTER_API_KEY` | 否 | 启用图像生成功能 |
| `OPENROUTER_IMAGE_MODEL` | 否 | OpenRouter 图像模型 |
| `ALCHEMY_API_KEY` | 否 | Alchemy RPC 访问 |
| `RPC_URLS` | 是 | 各链 RPC URL 配置 |
| `EVM_WALLET_PRIVATE_KEY` | 否 | 默认 EVM 钱包私钥 |
| `SVM_WALLET_PRIVATE_KEY` | 否 | 默认 Solana 钱包私钥 |
| `PRINTR_DEPLOYMENT_PASSWORD` | 否 | 部署钱包加密密码 |
| `PRINTR_BACKEND_URL` | 是 | Printr 后端 URL |
资料来源：[packages/mcp/src/lib/env.ts]()
### 2. 会话管理（sessions.ts）
会话管理器负责浏览器钱包签名流程，支持 MetaMask（EVM）和 Phantom（Solana）。
```typescript
export function createSession(
chainType: ChainType,
sessionId: string,
payload: SessionPayload,
): Session {
return {
id: sessionId,
chainType,
state: "pending",
payload,
createdAt: new Date(),
};
}
```
会话状态流转：
```mermaid
stateDiagram-v2
[*] --> pending: 创建会话
pending --> active: 浏览器已打开
active --> approved: 用户签名
active --> rejected: 用户拒绝
rejected --> [*]
approved --> [*]: 交易已提交
```
关键配置：
| 配置项 | 说明 |
|--------|------|
| `LOCAL_SESSION_ORIGIN` | 本地会话服务器地址 |
| 会话超时 | 浏览器签名等待时间 |
| QR 码生成 | 用于移动端钱包扫码 |
资料来源：[packages/mcp/src/server/sessions.ts]()
### 3. 钱包会话状态（wallet-sessions.ts）
活跃钱包管理当前已连接的钱包，支持通过私钥直接签名或浏览器钱包签名。
```typescript
export interface ActiveWallet {
chainType: ChainType;
address: string;
privateKey?: string; // 仅在私钥模式下可用
sessionId?: string; // 浏览器签名模式
}
export const activeWallets = new Map();
```
| 签名模式 | 使用场景 | 配置方式 |
|---------|---------|---------|
| 私钥模式 | 服务端自动签名 | 设置 `EVM_WALLET_PRIVATE_KEY` / `SVM_WALLET_PRIVATE_KEY` |
| 浏览器模式 | 用户确认后签名 | 调用 `printr_open_web_signer` 工具 |
资料来源：[packages/mcp/src/server/wallet-sessions.ts]()
### 4. 钱包解析（wallet-elicit.ts）
`wallet-elicit.ts` 提供钱包地址解析和余额检查功能。
```typescript
export type WalletResolution =
| { kind: "ready"; privateKey: string; address: string }
| {
kind: "insufficient_funds";
address: string;
balance: string;
required: string;
symbol: string;
chain: string;
}
| { kind: "error"; message: string };
```
地址派生逻辑：
| 链类型 | 派生方式 | 工具库 |
|-------|---------|--------|
| EVM | `privateKeyToAccount()` | `viem/accounts` |
| SVM | `Keypair.fromSecretKey()` | `@solana/web3.js` |
资料来源：[packages/mcp/src/lib/wallet-elicit.ts]()
### 5. 工具注册（mcp.ts）
MCP 服务器通过 `@modelcontextprotocol/sdk` 注册所有工具。
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
export function createMcpServer(deps: McpServerDeps): McpServer {
const server = new McpServer({ name: "printr", version: "0.16.1" });
registerQuoteTool(server);
registerCreateTokenTool(server);
registerLaunchTokenTool(server);
registerGetTokenTool(server);
registerTransferTool(server);
// ... 其他工具
return server;
}
```
资料来源：[packages/mcp/src/mcp.ts]()
## MCP 工具列表
| 工具名称 | 功能描述 | 链支持 |
|---------|---------|--------|
| `printr_quote` | 获取代币创建成本估算 | EVM, SVM |
| `printr_create_token` | 生成未签名代币创建交易 | EVM, SVM |
| `printr_launch_token` | 创建并签名代币（一步完成） | EVM, SVM |
| `printr_get_token` | 查询代币详情 | EVM, SVM |
| `printr_get_token_balance` | 查询钱包代币余额 | EVM, SVM |
| `printr_get_deployments` | 查询跨链部署状态 | EVM, SVM |
| `printr_transfer` | 转账代币或原生资产 | EVM, SVM |
| `printr_sign_and_submit_evm` | 签名并提交 EVM 交易 | EVM |
| `printr_sign_and_submit_svm` | 签名并提交 Solana 交易 | SVM |
| `printr_open_web_signer` | 启动浏览器签名会话 | EVM, SVM |
| `printr_generate_image` | 通过 OpenRouter 生成代币图标 | - |
| `printr_drain_deployment_wallet` | 清空部署钱包到金库 | EVM, SVM |
资料来源：[packages/mcp/src/tools/launch-token.ts]()、[packages/mcp/src/tools/transfer.ts]()
## 核心工具工作流
### 代币创建流程
```mermaid
sequenceDiagram
participant Agent
participant MCP as MCP Server
participant SDK as @printr/sdk
participant API as Printr API
participant Wallet
Agent->>MCP: printr_launch_token(params)
MCP->>SDK: buildToken(params, client)
SDK->>API: 创建代币请求
API-->>SDK: unsigned tx payload
SDK-->>MCP: EvmPayload | SvmPayload
alt 私钥模式
MCP->>Wallet: 签名交易
Wallet-->>MCP: signed tx
else 浏览器模式
MCP->>MCP: 启动 web signer session
Agent->>Browser: 打开签名页面
User->>Wallet: 签名交易
Wallet-->>MCP: signed tx
end
MCP->>SDK: signAndSubmitEvm/Svm
SDK->>RPC: 提交交易
RPC-->>SDK: tx hash
SDK-->>MCP: deployment result
MCP-->>Agent: 部署结果
```
### 转账流程
```mermaid
flowchart LR
A[输入 CAIP-10 地址] --> B{验证地址格式}
B -->|有效| C[解析链类型]
B -->|无效| D[返回错误]
C --> E{获取私钥}
E -->|提供参数| F[使用提供的私钥]
E -->|使用活跃钱包| G[从 wallet-sessions 获取]
F --> H[executeTransfer]
G --> H
H --> I[广播交易]
I --> J[返回结果]
```
资料来源：[packages/mcp/src/tools/transfer.ts]()
## 日志系统
`logging.ts` 提供结构化日志和工具执行追踪功能。
```typescript
export function logToolExecution(
toolName: string,
handler: ToolLoggerFn,
): (params: T) => Promise {
return async (params: T) => {
logger.info({ tool: toolName, params }, "Executing tool");
const result = await handler(params);
logger.info({ tool: toolName, success: result.isOk() }, "Tool completed");
return result;
};
}
```
| 日志级别 | 使用场景 |
|---------|---------|
| `info` | 工具执行、请求处理 |
| `error` | 错误和异常 |
| `debug` | 详细调试信息（需设置 `VERBOSE=true`）|
资料来源：[packages/mcp/src/lib/logging.ts]()
## SDK 集成
MCP 服务器的核心业务逻辑依赖 `@printr/sdk`，包括：
| SDK 模块 | 用途 |
|---------|------|
| `buildToken` | 代币创建核心逻辑 |
| `createPrintrClient` | API 客户端初始化 |
| `getChainMeta` | 链元数据查询 |
| `parseCaip10` | CAIP-10 地址解析 |
| `executeTransfer` | 转账执行 |
| `checkEvmBalance` / `checkSvmBalance` | 余额查询 |
```typescript
import {
buildToken,
type ChainType,
caip2ChainId,
getChainMeta,
quoteOutput,
signAndSubmitEvm,
signAndSubmitSvm,
type ToolResponse,
} from "@printr/sdk";
```
资料来源：[packages/mcp/src/tools/launch-token.ts]()
## Epic 规划与未来架构
根据社区讨论（Epic A/B/C），SDK 和 MCP 正在向以下方向演进：
### Epic A: SDK Workers-ready (#103)
目标：使 `@printr/sdk` 能在 Cloudflare Workers 等边缘运行时运行。
当前问题：
- 静态导入 `sharp` 和 `node:fs/promises` 导致 Node.js 依赖
- 使用 `createRequire` shim 不兼容 Workers
- 完整引入 `@solana/web3.js` (~600KB) 体积过大
### Epic B: Shared SDK Primitives (#104)
目标：将 MCP 内部逻辑提取为共享 SDK 子路径。
待提取组件：
- `@printr/sdk/signer` - 签名原语（从 `sessions.ts` 提取）
- 共享钱包解析逻辑
### Epic C: Agent Trading UX (#105)
目标：扩展工具集支持交易功能（Swap、Buy、Sell、Bridge）。
依赖：
- Epic B 的签名原语
- 跨链桥接工具
- 交易提供商集成
## 运行要求
| 组件 | 最低版本 |
|------|---------|
| Node.js | >= 18 |
| Bun | 推荐使用 |
### 启动方式
```bash
# 生产环境
bun src/index.ts
# 开发模式（热重载）
bun --hot src/index.ts
# 使用 MCP Inspector 调试
bunx @modelcontextprotocol/inspector bun src/index.ts
```
## 安全考虑
1. **私钥管理**：不建议在共享配置中存储私钥，应使用环境级 secrets
2. **部署钱包加密**：通过 `PRINTR_DEPLOYMENT_PASSWORD` 使用 AES-256-GCM 加密
3. **会话隔离**：每个浏览器签名会话独立，不可复用
4. **余额检查**：交易前自动检查余额是否充足
资料来源：[README.md]()、[packages/mcp/src/lib/wallet-elicit.ts]()
## 相关资源
- [SDK 源码](https://github.com/PrintrFi/printr-mcp/tree/main/packages/sdk)
- [CLI 工具](https://github.com/PrintrFi/printr-mcp/tree/main/packages/cli)
- [Skill 定义](https://github.com/PrintrFi/printr-mcp/tree/main/packages/cli/skills/printr)
- [Model Context Protocol 规范](https://modelcontextprotocol.io)
---
## MCP 工具列表
### 相关页面
相关主题：[MCP 服务器架构](#mcp-server-architecture), [钱包与签名](#wallet-signing), [交易工具](#trading-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/tools/quote.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/quote.ts)
- [packages/mcp/src/tools/create-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/create-token.ts)
- [packages/mcp/src/tools/launch-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/launch-token.ts)
- [packages/mcp/src/tools/get-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token.ts)
- [packages/mcp/src/tools/get-deployments.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-deployments.ts)
- [packages/mcp/src/tools/sign-and-submit-evm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-evm.ts)
- [packages/mcp/src/tools/sign-and-submit-svm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-svm.ts)
- [packages/mcp/src/tools/open-web-signer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/open-web-signer.ts)
- [packages/mcp/src/tools/generate-image.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/generate-image.ts)
- [packages/mcp/src/tools/get-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-balance.ts)
- [packages/mcp/src/tools/transfer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/transfer.ts)
- [packages/mcp/src/tools/transfer-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/transfer-token.ts)
- [packages/mcp/src/tools/claim-fees.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/claim-fees.ts)
- [packages/mcp/src/tools/drain-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/drain-deployment-wallet.ts)
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
# MCP 工具列表
## 概述
`@printr/mcp` 提供了一套完整的 MCP（Model Context Protocol）工具集，使 AI Agent 能够通过自然语言对话的方式与 Printr 协议交互，执行代币创建、部署、交易、钱包管理等操作。这些工具封装了复杂的区块链交互逻辑，提供了统一的接口层，让开发者无需深入了解底层细节即可构建区块链应用。
工具系统基于 [MCP SDK](https://github.com/modelcontextprotocol/sdk) 实现，每个工具都包含输入输出 Schema 定义，通过 `zod` 进行参数验证，并返回结构化的结果。工具注册流程统一由 `@modelcontextprotocol/sdk` 的 `registerTool` 方法处理。资料来源：[packages/mcp/src/tools/launch-token.ts:1-27]()
## 工具分类架构
```mermaid
graph TD
A[Printr MCP Tools] --> B[代币操作工具]
A --> C[钱包与签名工具]
A --> D[查询工具]
A --> E[转账工具]
A --> F[费用管理工具]
B --> B1[printr_quote]
B --> B2[printr_create_token]
B --> B3[printr_launch_token]
B --> B4[printr_generate_image]
C --> C1[printr_sign_and_submit_evm]
C --> C2[printr_sign_and_submit_svm]
C --> C3[printr_open_web_signer]
D --> D1[printr_get_token]
D --> D2[printr_get_deployments]
D --> D3[printr_get_balance]
D --> D4[printr_get_token_balance]
E --> E1[printr_transfer]
E --> E2[printr_transfer_token]
F --> F1[printr_claim_fees]
F --> F2[printr_drain_deployment_wallet]
```
## 代币操作工具
### printr_quote
获取代币创建的成本估算。该工具允许用户在正式创建代币前了解所需费用，支持多链部署场景。
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `name` | string | 否 | 代币名称 |
| `symbol` | string | 否 | 代币符号 |
| `chains` | string[] | 是 | 部署链 ID 数组（CAIP-2 格式） |
| `initial_buy_supply_percentage` | number | 否 | 初始购买占供应量的百分比 |
| `initial_buy_spend_amount` | object | 否 | 初始购买花费金额 |
| `fee_sink` | enum | 否 | 费用接收方：`dev`、`stake_pool`、`buyback`、`liquidity_pool` |
| `image` | string | 否 | 代币图标 URL 或 base64 编码 |
资料来源：[packages/mcp/src/tools/quote.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/quote.ts)
### printr_create_token
生成未签名的代币创建交易载荷。与 `printr_launch_token` 不同，该工具仅返回交易数据，签名操作需由外部完成。
**核心功能：**
- 生成跨链代币创建请求
- 支持 EVM 和 SVM 双协议栈
- 返回符合 CAIP-2 标准的链标识
- 可指定初始购买参数
资料来源：[packages/mcp/src/tools/create-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/create-token.ts)
### printr_launch_token
一站式代币创建和签名工具。整合了交易生成、签名、提交全流程，是最常用的代币发行接口。
```typescript
// 核心流程示意
import { buildToken, signAndSubmitEvm, signAndSubmitSvm } from "@printr/sdk";
// 支持的 fee_sink 类型
const feeSinkSchema = z.enum(["dev", "stake_pool", "buyback", "liquidity_pool"]);
```
**参数说明：**
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `name` | string | 代币名称 |
| `symbol` | string | 代币符号（3-8字符） |
| `chains` | string[] | 目标链数组 |
| `initial_buy` | object | 初始购买配置 |
| `fee_sink` | string | 费用分配策略 |
| `image` | string | 代币图标 |
| `deploy_wallet_id` | string | 部署钱包 ID |
**返回结果包含：**
- 代币 ID（十六进制格式）
- 各链的合约地址
- 交易哈希
- 部署状态
资料来源：[packages/mcp/src/tools/launch-token.ts:1-45]()
### printr_generate_image
通过 OpenRouter API 生成代币头像。该工具需要配置 `OPENROUTER_API_KEY` 环境变量。
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `prompt` | string | 是 | 图像生成提示词 |
| `model` | string | 否 | 图像模型名称 |
资料来源：[packages/mcp/src/tools/generate-image.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/generate-image.ts)
## 钱包与签名工具
### printr_sign_and_submit_evm
签署并提交 EVM 链交易。处理 MetaMask 等 EVM 钱包签名的核心工具。
**功能特点：**
- 支持通过私钥或浏览器钱包签名
- 自动处理 gas 估算
- 支持自定义 gas limit 和 gas price
- 返回交易哈希和状态
资料来源：[packages/mcp/src/tools/sign-and-submit-evm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-evm.ts)
### printr_sign_and_submit_svm
签署并提交 Solana 链交易。处理 Phantom 等 SVM 钱包签名。
**支持的钱包类型：**
- 浏览器钱包（Phantom 等）
- 私钥直接签名
- 部署钱包
资料来源：[packages/mcp/src/tools/sign-and-submit-svm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-svm.ts)
### printr_open_web_signer
启动浏览器签名会话。通过 URL 方式打开钱包，让用户在浏览器中完成签名操作。
**工作流程：**
```mermaid
sequenceDiagram
Agent->>MCP: 调用 open_web_signer
MCP->>MCP: 创建签名会话
MCP-->>Agent: 返回签名 URL
Agent->>Browser: 重定向用户到签名 URL
User->>Browser: 使用钱包签名
Browser->>MCP: 回调通知签名结果
MCP-->>Agent: 返回签名状态
```
资料来源：[packages/mcp/src/tools/open-web-signer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/open-web-signer.ts)
## 查询工具
### printr_get_token
通过代币 ID 或地址查询代币详情。
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `token_id` | string | 代币 ID（十六进制）或 CAIP-10 地址 |
| `chain` | string | CAIP-2 链 ID（可选） |
**返回数据结构：**
- 代币基本信息（名称、符号、描述）
- 供应量信息
- 部署状态
- 各链合约地址
- 代币图标
资料来源：[packages/mcp/src/tools/get-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token.ts)
### printr_get_deployments
查询代币在各链的部署状态。
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `token_id` | string | 代币 ID |
| `chains` | string[] | 要查询的链 ID 数组 |
**返回信息包括：**
- 各链的合约地址
- 交易 ID
- 区块时间戳
- 毕业价格和供应量
- 初始流动性状态
资料来源：[packages/mcp/src/tools/get-deployments.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-deployments.ts)
### printr_get_balance
查询钱包的原生代币余额。
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `wallet` | string | 钱包地址（CAIP-10 格式） |
| `chain` | string | 链 ID（CAIP-2 格式） |
| `rpc_url` | string | 可选的 RPC URL 覆盖 |
资料来源：[packages/mcp/src/tools/get-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-balance.ts)
### printr_get_token_balance
查询钱包的 ERC-20 或 SPL 代币余额。
```typescript
const inputSchema = z.object({
token: z.string().describe("Token address (CAIP-10)"),
wallet: z.string().describe("Wallet address (CAIP-10)"),
rpc_url: z.string().optional().describe("RPC URL override"),
});
```
**返回字段：**
| 字段名 | 说明 |
|--------|------|
| `chain_name` | 可读链名称 |
| `balance_atomic` | 原子单位余额 |
| `balance_formatted` | 格式化后余额 |
| `symbol` | 代币符号 |
| `decimals` | 代币精度 |
**验证规则：**
- Token 和 Wallet 必须在同一链上
- 地址必须符合 CAIP-10 标准
资料来源：[packages/mcp/src/tools/get-token-balance.ts:1-60]()
## 转账工具
### printr_transfer
转账原生代币（ETH、SOL 等）。
**核心验证流程：**
```mermaid
graph TD
A[输入 to 地址] --> B{parseCaip10}
B -->|失败| E[返回错误]
B -->|成功| C{getChainMeta}
C -->|失败| E
C -->|成功| D{validateBalance}
D -->|余额不足| F[返回错误]
D -->|通过| G[执行转账]
```
**参数结构：**
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `to` | string | 目标地址（CAIP-10 格式） |
| `amount` | string | 转账金额 |
| `private_key` | string | 可选，签名私钥 |
**链支持：**
- EVM 链（Base、Ethereum、Polygon 等）
- SVM 链（Solana）
资料来源：[packages/mcp/src/tools/transfer.ts:1-45]()
### printr_transfer_token
转账 ERC-20 或 SPL 代币。
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `token` | string | 代币地址（CAIP-10） |
| `to` | string | 目标地址（CAIP-10） |
| `amount` | string | 转账金额 |
| `private_key` | string | 可选，签名私钥 |
## 费用管理工具
### printr_claim_fees
领取协议费用。允许代币创建者或指定角色领取累积的费用收入。
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `token_id` | string | 代币 ID（十六进制）或 CAIP-10 地址 |
| `chain` | string | 链 ID（CAIP-2 格式） |
**支持的费用类型：** `dev`、`stake_pool`、`buyback`、`liquidity_pool`
资料来源：[packages/mcp/src/tools/claim-fees.ts:1-35]()
### printr_drain_deployment_wallet
清空部署钱包余额到金库。支持 EVM 和 SVM 双链。
**输出参数：**
| 字段名 | 说明 |
|--------|------|
| `success` | 操作是否成功 |
| `symbol` | 原生代币符号 |
| `from_address` | 源钱包地址 |
| `to_address` | 金库地址 |
| `tx_signature` | Solana 交易签名 |
| `tx_hash` | EVM 交易哈希 |
| `remaining_balance` | 剩余余额 |
| `wallet_id` | 钱包 ID |
**依赖注入设计：**
```typescript
export type DrainDeploymentWalletDeps = {
resolveWallet: ResolveWalletFn;
getTreasuryKeyOrError: GetTreasuryKeyOrErrorFn;
getChainMeta: GetChainMetaFn;
getEvmConfig: GetEvmConfigFn;
drainSvm: DrainSvmFn;
drainEvm: DrainEvmFn;
};
```
资料来源：[packages/mcp/src/tools/drain-deployment-wallet.ts:1-80]()
## 工具注册机制
所有工具通过统一的注册函数 `registerTool` 注册到 MCP 服务器：
```typescript
export function registerGetTokenBalanceTool(server: McpServer): void {
server.registerTool(
"printr_get_token_balance",
{
description: "获取钱包的代币余额...",
inputSchema,
outputSchema,
},
handler
);
}
```
**注册流程：**
1. 定义输入输出 Schema（使用 `zod`）
2. 实现处理函数
3. 调用 `registerTool` 注册
4. 工具自动暴露给 MCP 客户端
资料来源：[packages/mcp/src/tools/get-token-balance.ts:50-65]()
## 环境变量配置
MCP 工具依赖多个环境变量：
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `PRINTR_API_KEY` | 是 | Printr API 密钥 |
| `PRINTR_API_BASE_URL` | 是 | API 基础 URL |
| `OPENROUTER_API_KEY` | 否 | 启用图片生成 |
| `OPENROUTER_IMAGE_MODEL` | 否 | 图片模型 |
| `ALCHEMY_API_KEY` | 否 | Alchemy RPC 访问 |
| `RPC_URLS` | 是 | 各链 RPC URL 配置 |
| `EVM_WALLET_PRIVATE_KEY` | 否 | EVM 钱包私钥 |
| `SVM_WALLET_PRIVATE_KEY` | 否 | SVM 钱包私钥 |
| `PRINTR_BACKEND_URL` | 是 | 后端服务 URL |
资料来源：[packages/mcp/src/lib/env.ts:1-45]()
## 错误处理
工具采用统一的错误处理模式：
```typescript
import { err, ok, type Result } from "neverthrow";
import { ResultAsync } from "neverturn";
function toolHandler(input: Input): ResultAsync {
return ResultAsync.fromPromise(
async () => { /* 业务逻辑 */ },
(e) => ({ message: String(e) })
);
}
```
**错误类型：**
- `TransferToolError` - 转账相关错误
- `ImageError` - 图片处理错误
- `PrintrApiError` - API 调用错误
## 相关 Epic 与路线图
根据社区反馈，以下功能正在规划中：
| Epic | 描述 | 相关工具 |
|------|------|----------|
| Epic A: SDK Workers-ready | SDK 支持边缘运行时 | 所有工具 |
| Epic B: Shared SDK primitives | 共享 SDK 基础组件 | 签名工具 |
| Epic C: Agent trading UX | Agent 交易功能 | swap、buy、sell |
**规划中的交易工具：**
- `printr_swap` - 代币兑换
- `printr_buy` - 买入代币
- `printr_sell` - 卖出代币
- 跨链桥接工具（Base ↔ Solana）
资料来源：[Epic C: Agent trading UX](https://github.com/PrintrFi/printr-mcp/issues/105)
## 最佳实践
### 1. 使用 CAIP-10 地址格式
所有地址参数应使用 CAIP-10 标准格式：
- EVM: `eip155:1:0x1234...`
- SVM: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
### 2. 优先使用部署钱包
避免在代码中硬编码私钥，使用部署钱包管理功能：
```typescript
// 推荐方式
const walletId = await resolveWallet(chainType);
```
### 3. 利用 Quote 工具预估费用
在创建代币前，先调用 `printr_quote` 获取准确的成本估算。
### 4. 批量操作优化
对于多链部署，使用 `printr_get_deployments` 批量查询部署状态，减少 API 调用次数。
---
## 钱包与签名
### 相关页面
相关主题：[MCP 服务器架构](#mcp-server-architecture), [MCP 工具列表](#mcp-tools), [安装配置](#installation)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/tools/open-web-signer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/open-web-signer.ts)
- [packages/mcp/src/tools/sign-and-submit-evm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-evm.ts)
- [packages/mcp/src/tools/sign-and-submit-svm.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/sign-and-submit-svm.ts)
- [packages/mcp/src/server/wallet-sessions.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/server/wallet-sessions.ts)
- [packages/mcp/src/lib/wallet-elicit.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/wallet-elicit.ts)
- [packages/mcp/src/tools/fund-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/fund-deployment-wallet.ts)
- [packages/mcp/src/tools/drain-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/drain-deployment-wallet.ts)
- [packages/sdk/src/keystore.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/keystore.ts)
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
# 钱包与签名
Printr-MCP 的钱包与签名系统是支持跨链代币操作的核心基础设施。该系统管理 EVM（以太坊虚拟机）链和 SVM（Solana 虚拟机）链上的钱包操作，包括浏览器签名会话管理、交易签名与提交、以及部署钱包的资金流转。
## 系统架构概览
钱包与签名系统由多个层次的组件构成，形成从环境配置到实际交易签署的完整流程。
```mermaid
graph TD
A["环境变量配置
(env.ts)"] --> B["钱包会话管理
(wallet-sessions.ts)"]
B --> C["签名策略选择"]
C --> D1["浏览器签名
(open-web-signer.ts)"]
C --> D2["私钥直签 EVM
(sign-and-submit-evm.ts)"]
C --> D3["私钥直签 SVM
(sign-and-submit-svm.ts)"]
E["部署钱包管理"] --> E1["资金充值
(fund-deployment-wallet.ts)"]
E --> E2["资金回收
(drain-deployment-wallet.ts)"]
F["SDK 密钥库
(keystore.ts)"] --> G["AES-256-GCM 加密"]
G --> H["keystore.json 持久化"]
style A fill:#e1f5fe
style F fill:#fff3e0
style G fill:#fff3e0
```
## 核心组件关系
| 组件 | 文件路径 | 主要职责 |
|------|---------|---------|
| 环境配置 | `packages/mcp/src/lib/env.ts` | 定义钱包相关环境变量 |
| 钱包会话 | `packages/mcp/src/server/wallet-sessions.ts` | 管理浏览器签名 URL 会话 |
| EVM 签名 | `packages/mcp/src/tools/sign-and-submit-evm.ts` | EVM 交易签名与提交 |
| SVM 签名 | `packages/mcp/src/tools/sign-and-submit-svm.ts` | Solana 交易签名与提交 |
| 浏览器签名 | `packages/mcp/src/tools/open-web-signer.ts` | 生成 MetaMask/Phantom 签名 URL |
| 密钥库 | `packages/sdk/src/keystore.ts` | 钱包私钥加密存储 |
| 资金管理 | `packages/mcp/src/tools/fund-deployment-wallet.ts` | 充值部署钱包 |
| 资金回收 | `packages/mcp/src/tools/drain-deployment-wallet.ts` | 从部署钱包转回财库 |
## 环境变量配置
钱包系统依赖多个环境变量进行配置，定义于 `packages/mcp/src/lib/env.ts`：
| 环境变量 | 类型 | 描述 |
|---------|------|------|
| `EVM_WALLET_PRIVATE_KEY` | `string` (可选) | EVM 链钱包私钥（十六进制格式） |
| `SVM_WALLET_PRIVATE_KEY` | `string` (可选) | Solana 钱包私钥（Base58 格式） |
| `PRINTR_DEPLOYMENT_PASSWORD` | `string` (可选) | 部署钱包私钥加密的主密码 |
| `PRINTR_WALLET_STORE` | `string` (可选) | 密钥库文件路径 |
资料来源：[packages/mcp/src/lib/env.ts:29-34]()
### 配置优先级
当环境变量与密钥库同时存在时，系统遵循以下优先级：
1. **私钥直签优先**：若设置了 `*_WALLET_PRIVATE_KEY`，直接使用该私钥签名
2. **密钥库兜底**：若无直传私钥，则尝试从加密密钥库加载钱包
3. **浏览器签名兜底**：若均不可用，则启动浏览器签名会话
## 密钥库系统
SDK 层的密钥库系统 (`packages/sdk/src/keystore.ts`) 提供了安全的私钥存储机制。
### 核心功能
密钥库使用 AES-256-GCM 加密算法保护私钥安全：
- **主密码派生**：使用 PBKDF2 从主密码派生加密密钥
- **随机盐值**：每次加密使用唯一的随机盐值
- **认证标签**：包含加密数据的完整性验证
### 密钥库文件结构
```json
{
"version": 1,
"wallets": {
"eip155:8453:0x...": {
"encryptedKey": "base64编码的加密私钥",
"salt": "base64编码的盐值",
"iv": "base64编码的初始向量"
}
}
}
```
## 签名会话管理
### 浏览器签名工作流
对于非托管钱包场景，系统通过浏览器签名 URL 会话实现安全签名：
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant MCP as MCP Server
participant Browser as 用户浏览器
participant Wallet as MetaMask/Phantom
Agent->>MCP: 调用 open-web-signer 工具
MCP->>MCP: 生成签名会话 URL
MCP-->>Agent: 返回签名 URL 和 session_id
Agent->>Browser: 提示用户打开签名链接
Browser->>Wallet: 用户确认签名
Wallet->>MCP: 回调确认签名完成
MCP-->>Agent: 签名会话状态更新
```
### 钱包邀请流程
`packages/mcp/src/lib/wallet-elicit.ts` 实现了钱包地址获取的引导流程：
1. **地址验证**：检查钱包地址是否符合 CAIP-10 格式
2. **链类型识别**：解析 `eip155:8453:0x...` 或 `solana:...` 格式
3. **签名绑定**：将钱包地址与会话关联
资料来源：[packages/mcp/src/lib/wallet-elicit.ts]()
## 交易签名与提交
### EVM 交易签名
`sign-and-submit-evm.ts` 处理以太坊系链（Base、以太坊主网等）的交易：
```typescript
// 核心流程伪代码
async function signAndSubmitEvm(payload: EvmTransactionPayload) {
// 1. 获取签名者（私钥或浏览器会话）
const signer = await resolveSigner(payload.chain_id);
// 2. 使用 viem 构建签名
const signature = await signer.signTransaction(payload);
// 3. 发送到 RPC 节点
const txHash = await provider.sendRawTransaction(signature);
return { tx_hash: txHash };
}
```
### SVM 交易签名
`sign-and-submit-svm.ts` 处理 Solana 链的交易：
```typescript
// 核心流程伪代码
async function signAndSubmitSvm(payload: SolanaTransactionPayload) {
// 1. 解析交易消息
const message = VersionedMessage.deserialize(payload.message);
// 2. 获取签名者
const signer = await resolveSvmSigner();
// 3. 使用 @solana/web3.js 签名
const signature = signer.sign(message);
// 4. 发送到 Solana 节点
const txSignature = await connection.sendRawTransaction(signature);
return { tx_signature: txSignature };
}
```
资料来源：[packages/mcp/src/tools/sign-and-submit-evm.ts]()
资料来源：[packages/mcp/src/tools/sign-and-submit-svm.ts]()
### 签名策略接口
```typescript
type SignerStrategy = {
// EVM 签名
signEvm: (payload: Uint8Array, chainId: string) => Promise;
// SVM 签名
signSvm: (message: Uint8Array) => Promise;
// 获取钱包地址
getAddress: (chain: ChainType) => Promise;
};
```
## 部署钱包管理
部署钱包是用于支付代币部署 Gas 费用的专用钱包，与用户主钱包分离。
### 资金充值
`fund-deployment-wallet.ts` 将资金从主钱包转入部署钱包：
| 参数 | 类型 | 描述 |
|------|------|------|
| `chain` | `string` | 目标链 ID（如 `eip155:8453`） |
| `amount` | `string` | 充值金额（原始单位） |
| `wallet_id` | `string` | 部署钱包标识符 |
### 资金回收
`drain-deployment-wallet.ts` 将部署钱包剩余资金转回财库：
| 参数 | 类型 | 描述 |
|------|------|------|
| `chain` | `string` | 链 ID |
| `remaining_balance` | `string` | 回收后保留余额 |
| `to_address` | `string` | 目标财库地址 |
资料来源：[packages/mcp/src/tools/drain-deployment-wallet.ts:1-50]()
### 部署钱包生命周期
```mermaid
graph LR
A["创建部署钱包"] --> B["充值资金"]
B --> C["执行代币部署"]
C --> D["交易完成"]
D --> E["回收剩余资金"]
E --> F["部署钱包清空"]
style B fill:#e8f5e9
style E fill:#ffebee
```
## 钱包会话状态管理
`wallet-sessions.ts` 维护会话状态：
| 状态 | 描述 |
|------|------|
| `pending` | 等待用户打开签名链接 |
| `opened` | 用户已打开签名页面 |
| `signed` | 用户已完成签名 |
| `expired` | 会话已过期 |
| `failed` | 签名失败 |
## 安全考虑
### 私钥处理原则
1. **最小暴露**：私钥仅在必要时加载到内存
2. **加密存储**：磁盘持久化必须使用 AES-256-GCM 加密
3. **环境隔离**：生产环境应使用 KMS 或硬件钱包
4. **日志脱敏**：日志输出必须隐藏私钥关键信息
### 社区驱动的安全改进
根据社区反馈，当前版本正在推进以下安全优化：
- **Epic B (#104)**：提取 signer 原语到 `@printr/sdk/signer`，实现更安全的签名逻辑复用
- **Epic A (#103)**：使 SDK 兼容 Cloudflare Workers 边缘运行时，避免将私钥带入不可信环境
- **Issue #97**：移除 `createRequire` shim，减少供应链攻击面
## 未来规划
根据 Epic B 的规划，签名原语将逐步迁移到 SDK 层：
```typescript
// 目标 API 结构
import { createSigner } from '@printr/sdk/signer';
const signer = createSigner({
type: 'browser' | 'private-key' | 'hardware',
chain: 'eip155:8453',
onSign: async (payload) => { /* 签名回调 */ }
});
```
这将使所有 Printr 客户端（不仅是 MCP）能够以统一、安全的方式处理签名操作。
---
## 交易工具
### 相关页面
相关主题：[MCP 工具列表](#mcp-tools), [钱包与签名](#wallet-signing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/tools/quote.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/quote.ts)
- [packages/mcp/src/tools/launch-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/launch-token.ts)
- [packages/mcp/src/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
- [packages/mcp/src/tools/transfer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/transfer.ts)
- [packages/mcp/src/tools/claim-staking-rewards.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/claim-staking-rewards.ts)
- [packages/mcp/src/tools/get-staking-positions.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-staking-positions.ts)
- [packages/sdk/src/staking-api.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/staking-api.ts)
- [packages/sdk/src/transfer.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/transfer.ts)
- [packages/sdk/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/README.md)
# 交易工具
Printr MCP 的交易工具模块为 AI Agent 提供了一套完整的代币操作能力，涵盖代币创建报价、余额查询、跨链转账、质押管理等功能。这些工具使 Agent 能够在多链环境（EVM 和 SVM）中执行代币相关的操作，无需用户手动干预。
## 功能概览
Printr MCP 当前提供的交易工具主要分为以下几个类别：
| 类别 | 工具名称 | 功能描述 |
|------|----------|----------|
| 报价与创建 | `printr_quote` | 获取代币创建成本估算 |
| | `printr_create_token` | 生成未签名代币创建交易 |
| | `printr_launch_token` | 一站式创建并签名代币 |
| 余额查询 | `printr_get_token_balance` | 查询 ERC-20 或 SPL 代币余额 |
| 转账操作 | `printr_transfer` | 跨链代币转账 |
| 质押管理 | `printr_get_staking_positions` | 查询质押仓位 |
| | `printr_claim_staking_rewards` | 领取质押奖励 |
| | `printr_claim_fees` | 领取手续费收益 |
## 核心工具详解
### 代币报价与创建
#### 获取报价 (`printr_quote`)
`printr_quote` 工具用于在正式创建代币之前获取成本估算，帮助用户和 Agent 了解需要准备的资金量。
**输入参数：**
| 参数 | 类型 | 必填 | 描述 |
|------|------|------|------|
| `creator_accounts` | string[] | 是 | CAIP-10 格式的创建者地址列表 |
| `chains` | string[] | 是 | 目标链列表（如 `["eip155:8453"]` 表示 Base） |
| `initial_buy` | object | 是 | 初始购买配置 |
**初始购买配置示例：**
```typescript
{
spend_usd: 10, // 花费 USD 数量
// 或
supply_percentage: 100 // 供应量百分比
}
```
#### 创建代币 (`printr_create_token`)
生成未签名的代币创建交易载荷，Agent 或用户需要使用外部钱包进行签名。
**核心流程：**
```mermaid
graph TD
A[输入代币配置] --> B[验证 CAIP-10 地址]
B --> C[调用 Printr API]
C --> D{创建成功?}
D -->|是| E[返回 unsigned tx payload]
D -->|否| F[返回错误信息]
```
#### 一站式发射 (`printr_launch_token`)
将创建和签名流程合并，适合配置了私钥的环境。资料来源：[packages/mcp/src/tools/launch-token.ts]()
**支持的签名方式：**
- `EVM_WALLET_PRIVATE_KEY` 环境变量指定的私钥
- `SVM_WALLET_PRIVATE_KEY` 环境变量指定的 Solana 密钥对
- Web 签名会话（通过 `printr_open_web_signer` 启动浏览器钱包）
### 余额查询
`printr_get_token_balance` 工具支持查询任意 ERC-20（EVM）或 SPL（SVM）代币的余额。
**输入参数：**
| 参数 | 类型 | 描述 |
|------|------|------|
| `token` | string | CAIP-10 格式的代币地址 |
| `wallet` | string | CAIP-10 格式的钱包地址 |
| `rpc_url` | string | 可选的 RPC URL（默认使用环境配置） |
**输出参数：**
| 字段 | 描述 |
|------|------|
| `token` | 代币地址 |
| `wallet` | 钱包地址 |
| `chain` | 链标识符 |
| `chain_name` | 人类可读的链名称 |
| `balance_atomic` | 最小单位的余额 |
| `balance_formatted` | 带小数位的格式化余额 |
| `symbol` | 代币符号 |
| `decimals` | 代币精度 |
**实现逻辑：**
工具首先解析 token 和 wallet 的 CAIP-10 格式，提取链标识和地址。验证链匹配后，根据链类型调用相应的余额查询接口：
- **EVM 链**：使用 `getEvmBalance` 获取原生代币余额，使用 `getErc20Balance` 获取 ERC-20 余额
- **SVM 链**：使用 `getSvmBalance` 获取原生代币余额，使用 `getSplBalance` 获取 SPL 代币余额
资料来源：[packages/mcp/src/tools/get-token-balance.ts]()
### 转账操作
`printr_transfer` 工具支持跨链代币转账，包括原生代币和 SPL/ERC-20 代币。
**支持的转账类型：**
| 源链类型 | 目标链类型 | 转账内容 |
|----------|------------|----------|
| SVM | SVM | SOL、SPL 代币 |
| EVM | EVM | 原生代币、ERC-20 |
| SVM | EVM | 跨链桥接（待实现） |
| EVM | SVM | 跨链桥接（待实现） |
资料来源：[packages/mcp/src/tools/transfer.ts]()、[packages/sdk/src/transfer.ts]()
**核心参数：**
| 参数 | 类型 | 描述 |
|------|------|------|
| `from` | string | CAIP-10 发送方地址 |
| `to` | string | CAIP-10 接收方地址 |
| `amount` | string | 转账金额（人类可读格式） |
### 质押管理
Printr 提供了完整的质押工具套件，支持创建质押仓位、查询仓位和领取奖励。
#### 查询质押仓位 (`printr_get_staking_positions`)
获取指定钱包地址的所有质押仓位信息。
**输出结构：**
| 字段 | 类型 | 描述 |
|------|------|------|
| `positions` | Position[] | 质押仓位列表 |
| `total_staked` | string | 总质押金额 |
| `total_rewards` | string | 总待领取奖励 |
每个 Position 包含：
- `position_id`: 仓位 ID（CAIP-10）
- `chain`: 链标识
- `staked_amount`: 质押金额
- `rewards_claimable`: 可领取奖励
- `unlock_time`: 解锁时间（若有）
#### 领取质押奖励 (`printr_claim_staking_rewards`)
从指定质押仓位领取累积的奖励。
**输入参数：**
| 参数 | 类型 | 描述 |
|------|------|------|
| `position` | string | CAIP-10 格式的质押仓位地址 |
**错误处理：**
工具会检查 Treasury 钱包配置，确保签名者有权限领取奖励：
```typescript
function getTreasuryContext(chainType: ChainType): Result {
const treasuryKey = getTreasuryKey(chainType);
if (!treasuryKey) {
const envVar = chainType === "svm" ? "SVM" : "EVM";
return err(
claimErr(
`Treasury wallet not configured for ${chainType.toUpperCase()}. ` +
`Use printr_set_treasury_wallet or set ${envVar}_WALLET_PRIVATE_KEY.`,
),
);
}
// ...
}
```
资料来源：[packages/mcp/src/tools/claim-staking-rewards.ts]()
#### 领取手续费收益 (`printr_claim_fees`)
允许从协议手续费池中领取收益份额。
## 工具注册与架构
所有交易工具通过 MCP 服务器统一注册和管理：
```mermaid
graph LR
A[MCP Server] --> B[Tool Registry]
B --> C[printr_quote]
B --> D[printr_create_token]
B --> E[printr_launch_token]
B --> F[printr_get_token_balance]
B --> G[printr_transfer]
B --> H[printr_get_staking_positions]
B --> I[printr_claim_staking_rewards]
B --> J[printr_claim_fees]
```
**工具注册模式：**
```typescript
export function registerGetTokenBalanceTool(server: McpServer): void {
server.registerTool(
"printr_get_token_balance",
{
description:
"Get the balance of an ERC-20 or SPL token for a wallet address. " +
"Use this to check token holdings before trading or transferring.",
inputSchema,
outputSchema,
},
logToolExecution("printr_get_token_balance", ({ token, wallet, rpc_url }) => {
// 实现逻辑
}),
);
}
```
资料来源：[packages/mcp/src/tools/get-token-balance.ts]()
## SDK 层实现
交易工具的底层实现封装在 `@printr/sdk` 包中，提供可复用的业务逻辑：
| SDK 模块 | 功能 |
|----------|------|
| `staking-api.ts` | 质押 API 调用封装 |
| `transfer.ts` | 转账逻辑与签名构建 |
| `balance.ts` | 余额查询（支持轻量级 JSON-RPC 模式） |
**轻量级余额查询（规划中）：**
根据社区反馈（Issue #101），当前的 `balance.ts` 依赖 `@solana/web3.js`（约 600KB）和 `viem`，对边缘运行时（如 Cloudflare Workers）造成负担。计划中的轻量级版本将直接使用 JSON-RPC 调用，减少 bundle 体积。
## 环境配置
交易工具依赖以下环境变量：
| 变量 | 必需 | 描述 |
|------|------|------|
| `PRINTR_API_KEY` | 否 | API 密钥（有默认值） |
| `EVM_WALLET_PRIVATE_KEY` | 部分 | EVM 链签名私钥 |
| `SVM_WALLET_PRIVATE_KEY` | 部分 | Solana 链签名私钥 |
| `RPC_URLS` | 是 | 各链 RPC URL 映射 |
资料来源：[packages/mcp/src/lib/env.ts]()
## 路线图与社区讨论
### Epic C: Agent Trading UX
根据 Issue #105，团队正在规划下一阶段的交易能力扩展：
**目标：**
使 Agent 能够执行 **Swap（兑换）**、**Buy（买入）**、**Sell（卖出）** 和 **Bridge（跨链桥接）** 操作，而不仅仅是 Launch（发射）。
**依赖项：**
- Epic B（#104）：共享 SDK 签名原语
- Epic A（#103）：SDK Workers 兼容化
### 跨链桥接
Issue #63 描述了跨链桥接工具的规划，将支持 Base ↔ Solana 之间的资产转移。这是实现真正的多链 Agent UX 的关键能力。
### 交易工具限制
当前版本（v0.6.1）的交易工具有以下限制：
1. **签名方式**：需要配置私钥环境变量或使用浏览器钱包会话
2. **Bundle 体积**：完整 SDK 包含较大的依赖（`@solana/web3.js`、`viem`）
3. **跨链转账**：仅支持同链转账，跨链桥接功能待实现
## 使用示例
### 获取代币创建报价
```json
{
"name": "printr_quote",
"arguments": {
"creator_accounts": ["eip155:8453:0xYourAddress"],
"chains": ["eip155:8453"],
"initial_buy": {
"spend_usd": 10
}
}
}
```
### 查询代币余额
```json
{
"name": "printr_get_token_balance",
"arguments": {
"token": "eip155:8453:0xTokenAddress",
"wallet": "eip155:8453:0xWalletAddress"
}
}
```
### 转账代币
```json
{
"name": "printr_transfer",
"arguments": {
"from": "eip155:8453:0xSenderAddress",
"to": "eip155:8453:0xRecipientAddress",
"amount": "100"
}
}
```
## 相关资源
- SDK 文档：[packages/sdk/README.md]()
- 完整工具列表：[packages/cli/skills/printr/SKILL.md]()
- 最新版本：sdk v0.6.1（2026-05-18）
---
## Workers 兼容性与优化
### 相关页面
相关主题：[SDK 架构](#sdk-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/sdk/src/balance-lite.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/balance-lite.ts)
- [packages/sdk/src/image.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/image.ts)
- [packages/sdk/src/balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/balance.ts)
- [packages/sdk/src/openapi.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/openapi.ts)
# Workers 兼容性与优化
## 概述
`@printr/sdk` 的 Workers 兼容性是 Printr 项目的核心优化目标之一（Epic A: SDK Workers-ready，Issue #103）。该 Epic 的验收标准为：**"一个 Worker 导入 SDK barrel 文件时不抛出异常"**。
当前 SDK 依赖 `@solana/web3.js`（约 600KB 压缩后）和 `viem` 等重型库，对于只需要查询余额或基础功能的边缘计算/Workers 场景，这造成了不必要的包体积负担。
## 问题分析
### 核心痛点
| 问题 | 影响 | 相关 Issue |
|------|------|------------|
| 重型依赖拉高包体积 | Cloudflare Workers 有 1MBbundle 限制 | #101, #103 |
| `createRequire` shim 不兼容 Workers | 每个模块顶部注入 Node.js 专用代码 | #97 |
| `sharp` 和 `node:fs` 静态导入 | 导入任何功能都携带 Node-only 依赖 | #96 |
| 完整类型导出包含运行时代码 | 仅需类型时也必须导入完整模块 | #98 |
### 依赖体积对比
```javascript
// 当前完整 SDK 依赖（约 600KB+）
@solana/web3.js // ~600KB minified
viem // ~200KB
sharp // Node.js 原生模块
neverthrow // ~10KB
```
## 解决方案
### 1. 轻量级余额查询：`@printr/sdk/balance-lite`
通过直接 JSON-RPC 调用替代重型 SDK，仅查询原生代币或 SPL 代币余额：
```typescript
// packages/sdk/src/balance-lite.ts
import { ResultAsync } from 'neverthrow';
export interface BalanceLiteOptions {
rpcUrl: string;
}
export const getNativeBalance = (
address: string,
options: BalanceLiteOptions
): ResultAsync => {
// 直接 JSON-RPC 调用，无重型依赖
};
```
**文件路径：** `packages/sdk/src/balance-lite.ts`
该子路径导出不包含 `@solana/web3.js` 和 `viem`，大幅降低包体积。
### 2. 类型专用导出：`@printr/sdk/openapi`
仅导出 OpenAPI 生成的类型定义（`paths`、`components`、`operations`），不包含任何运行时代码：
```typescript
// packages/sdk/src/openapi.ts
export type { paths, components, operations } from './api.gen.d.ts';
```
**文件路径：** `packages/sdk/src/openapi.ts`
消费者若仅需严格响应类型，可使用此入口而非 `@printr/sdk/client`。
### 3. 懒加载 Node.js 专用模块
`image.ts` 中的 `sharp` 和 `node:fs/promises` 改为懒加载：
```typescript
// packages/sdk/src/image.ts
let _sharp: typeof import('sharp') | undefined;
let _fs: typeof import('node:fs/promises') | undefined;
const getSharp = async () => {
if (!_sharp) {
_sharp = await import('sharp');
}
return _sharp;
};
```
**文件路径：** `packages/sdk/src/image.ts`
通过 `@printr/sdk` barrel 导入任何功能不再触发 Node-only 依赖的加载。
### 4. 移除 `createRequire` shim
清除所有模块顶部的 `createRequire` 导入，改为使用 ESM 原生 `import.meta.url`：
```javascript
// 修复前
import { createRequire } from "node:module";
var __require = createRequire(import.meta.url);
// 修复后
// 无 shim 代码，直接使用 ESM
```
## 导出子路径配置
`package.json` 中定义了多个专用导出路径，实现条件加载：
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
},
"./balance": {
"types": "./dist/balance.d.ts",
"import": "./dist/balance.js"
},
"./balance-lite": {
"types": "./dist/balance-lite.d.ts",
"import": "./dist/balance-lite.js"
},
"./openapi": {
"types": "./dist/openapi.d.ts",
"import": "./dist/openapi.js"
},
"./transfer": {
"types": "./dist/transfer.d.ts",
"import": "./dist/transfer.js"
}
}
}
```
**文件路径：** `packages/sdk/package.json:20-50`
## 使用指南
### Cloudflare Workers 场景
```typescript
// 推荐：使用轻量级导入
import { getNativeBalance } from '@printr/sdk/balance-lite';
import type { paths } from '@printr/sdk/openapi';
// 避免：完整导入（包含重型依赖）
// import { createPrintrClient, buildToken } from '@printr/sdk';
```
### 包体积对比
| 导入方式 | 预估体积 | 适用场景 |
|----------|----------|----------|
| `@printr/sdk` | ~800KB | Node.js 服务端完整功能 |
| `@printr/sdk/balance-lite` | ~20KB | 仅余额查询 |
| `@printr/sdk/openapi` | ~5KB (仅类型) | 仅类型定义 |
| `@printr/sdk/transfer` | ~50KB | 转账功能 |
## 架构流程图
```mermaid
graph TD
A[Consumer Import] --> B{导入路径判断}
B -->|完整导入| C[完整 SDK]
B -->|balance-lite| D[轻量余额模块]
B -->|openapi| E[仅类型定义]
B -->|transfer| F[转账模块]
C --> G[包含重型依赖]
D --> H[直接 JSON-RPC]
E --> I[无运行时代码]
F --> J[轻量转账逻辑]
G --> K[Workers 可能超限]
H --> L[Workers 友好]
J --> L
I --> L
```
## 相关 Issue 与路线图
| Issue | 标题 | 状态 | 依赖 |
|-------|------|------|------|
| #103 | Epic A: SDK Workers-ready | 进行中 | 全部子项 |
| #101 | feat: lighter balance via direct JSON-RPC | 已完成 | - |
| #97 | fix: emit Workers-friendly bundle | 进行中 | - |
| #96 | fix: lazy-load sharp + node:fs | 进行中 | - |
| #98 | feat: types-only @printr/sdk/openapi entry | 进行中 | - |
| #102 | feat: processImageBytes bytes helper | 待处理 | #96 |
## 未来优化方向
1. **更多轻量子路径**：将 `transfer`、`evm`、`svm` 等拆分为独立轻量模块
2. **图片字节处理**（#102）：添加 `processImageBytes(bytes: Uint8Array)` 支持浏览器/边缘场景
3. **签名原语提取**（#100）：将 `@printr/sdk/signer` 提取为独立子路径
## 验收标准
所有 Workers 兼容性修复共享同一验收门控：
> **"在 Cloudflare Worker 环境中导入 SDK barrel 文件，评估过程不抛出异常"**
测试可通过以下方式验证：
```typescript
// workers-entry.js
import('@printr/sdk'); // 不应抛出
```
## 总结
通过子路径导出、懒加载重型模块、直接 JSON-RPC 调用替代 SDK，`@printr/sdk` 正逐步实现 Cloudflare Workers 兼容性。开发者应根据实际需求选择合适的导入路径，平衡功能完整性与包体积限制。
---
## 部署指南
### 相关页面
相关主题：[安装配置](#installation), [钱包与签名](#wallet-signing)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/mcp/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
- [package.json](https://github.com/PrintrFi/printr-mcp/blob/main/package.json)
- [README.md](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
# 部署指南
本页面介绍 `@printr/sdk` 和 `@printr/mcp` 的部署配置方法，涵盖环境变量设置、运行时要求、支持的目标平台以及最佳实践。
## 概述
Printr MCP 项目包含两个主要部署单元：
| 包名 | 类型 | 描述 |
|------|------|------|
| `@printr/sdk` | SDK 库 | 跨链 Token 创建和管理的核心库 |
| `@printr/mcp` | MCP 服务器 | 提供 Agent 工具调用的 MCP 协议服务 |
`@printr/mcp` 依赖 `@printr/sdk`，两者需协同部署。
## 系统要求
### Node.js 环境
```yaml
引擎版本: Node.js >= 18
包管理器: Bun (推荐) 或 npm/yarn/pnpm
TypeScript: >= 6.0.0
```
资料来源：[packages/sdk/package.json:14](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
### MCP 服务器依赖
```yaml
@modelcontextprotocol/sdk: ^1.29.0
@hono/node-server: ^1.19.14
@solana/web3.js: ^1.98.4
viem: ^2.49.0
zod: ~4.3.6
```
资料来源：[packages/mcp/package.json:18-26](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
## 环境变量配置
### 必需变量
| 变量名 | 描述 | 示例 |
|--------|------|------|
| `PRINTR_API_KEY` | Printr 合作伙伴 API 密钥 | `pk_live_xxxx` |
| `PRINTR_API_BASE_URL` | Printr API 基础地址 | `https://api.printr.money` |
资料来源：[packages/mcp/src/lib/env.ts:10-11](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
### 钱包配置
| 变量名 | 描述 | 格式 |
|--------|------|------|
| `EVM_WALLET_PRIVATE_KEY` | EVM 链钱包私钥 | 十六进制 (0x...) |
| `SVM_WALLET_PRIVATE_KEY` | Solana 钱包私钥 | Base58 编码 |
> ⚠️ **安全警告**: 私钥应存储在环境级别而非共享配置文件。使用 secrets 管理工具处理敏感信息。
资料来源：[README.md:48-54](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
### 可选变量
| 变量名 | 描述 | 默认值 |
|--------|------|--------|
| `OPENROUTER_API_KEY` | 启用 AI 图片生成功能 | - |
| `OPENROUTER_IMAGE_MODEL` | 图片生成模型覆盖 | - |
| `ALCHEMY_API_KEY` | Alchemy RPC 提供商密钥 | - |
| `RPC_URLS` | 自定义 RPC 端点映射 | 见下表 |
| `PRINTR_APP_URL` | Printr 应用 URL | `https://app.printr.money` |
| `PRINTR_CDN_URL` | Printr CDN URL | `https://cdn.printr.money` |
### RPC URL 配置
`RPC_URLS` 支持通过 `ALCHEMY_RPC_TEMPLATES` 模板或自定义端点配置多链 RPC：
```typescript
RPC_URLS: {
base: "https://base-mainnet.g.alchemy.com/v2/YOUR_KEY",
ethereum: "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
solana: "https://api.mainnet-beta.solana.com"
}
```
资料来源：[packages/mcp/src/lib/env.ts:7-8](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
## 部署架构
### 单进程部署
适用于开发环境和轻量级生产部署：
```bash
# 构建
bun run build
# 启动 MCP 服务器
cd packages/mcp
bun src/index.ts
```
### HTTP 服务部署
MCP 支持通过 Hono HTTP 服务器暴露：
```bash
# 启动 HTTP 模式
cd packages/mcp
bun run start
```
服务默认监听端口 `3000`，可通过环境变量 `PORT` 调整。
### MCP 工具调用方式
| 工具名 | 用途 |
|--------|------|
| `printr_quote` | 获取 Token 创建成本估算 |
| `printr_create_token` | 生成未签名交易载荷 |
| `printr_launch_token` | 一站式创建和签名 Token |
| `printr_get_token` | 查询 Token 详情 |
| `printr_get_deployments` | 查询跨链部署状态 |
| `printr_sign_and_submit_evm` | EVM 交易签名和提交 |
| `printr_sign_and_submit_svm` | Solana 交易签名和提交 |
| `printr_open_web_signer` | 启动浏览器签名会话 |
资料来源：[README.md:56-74](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
## 构建流程
### 完整构建
从仓库根目录执行：
```bash
# 安装依赖
bun install
# 构建所有包
bun run build
```
### 分包构建
```bash
# 仅构建 SDK
cd packages/sdk && bun run build
# 仅构建 MCP
cd packages/mcp && bun run build
```
### 构建产物
| 包 | 产物路径 | 说明 |
|----|----------|------|
| SDK 核心 | `packages/sdk/dist/index.js` | 主入口 |
| SDK 客户端 | `packages/sdk/dist/client.js` | OpenAPI 客户端 |
| SDK 链抽象 | `packages/sdk/dist/chains.js` | 链配置 |
| MCP 服务器 | `packages/mcp/dist/index.js` | MCP 服务端 |
资料来源：[packages/sdk/package.json:7-8](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
## 多环境部署
### 开发环境
```bash
PRINTR_API_KEY=pk_dev_xxx
PRINTR_API_BASE_URL=https://api-preview.printr.money
PRINTR_APP_URL=http://localhost:3001
PRINTR_CDN_URL=http://localhost:3002
```
### 测试环境
```bash
PRINTR_API_KEY=pk_test_xxx
PRINTR_API_BASE_URL=https://api-staging.printr.money
```
### 生产环境
```bash
PRINTR_API_KEY=pk_live_xxx
PRINTR_API_BASE_URL=https://api.printr.money
```
## Workers/Edge 运行时支持
> 社区追踪: [Epic A: SDK Workers-ready (#103)](https://github.com/PrintrFi/printr-mcp/issues/103)
`@printr/sdk` 正朝着 Cloudflare Workers 和边缘运行时兼容方向演进。
### 当前限制
标准 SDK 包包含以下 Node.js 专用模块：
- `sharp` - 图片处理（通过 `@printr/sdk/image` 访问）
- `node:fs/promises` - 文件系统操作
- `node:module` (createRequire) - CJS 互操作
### 边缘兼容子路径
| 子路径 | 用途 | Workers 兼容 |
|--------|------|--------------|
| `@printr/sdk/client` | OpenAPI 客户端 | ✅ |
| `@printr/sdk/chains` | 链配置 | ✅ |
| `@printr/sdk/evm` | EVM 工具 | ✅ |
| `@printr/sdk/svm` | Solana 工具 | ⚠️ 需 JSON-RPC |
| `@printr/sdk/balance` | 余额查询 | ⚠️ 完整包 |
| `@printr/sdk/balance-lite` | 轻量余额 | ✅ 计划中 |
资料来源：[packages/sdk/package.json:20-36](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
### 轻量余额方案
> 社区追踪: [feat: lighter balance via direct JSON-RPC (#101)](https://github.com/PrintrFi/printr-mcp/issues/101)
为减少包体积，新增 `@printr/sdk/balance-lite` 子路径，直接调用 Solana JSON-RPC 而不引入 `@solana/web3.js` (~600KB)：
```typescript
// 边缘兼容方式
import { getBalanceLite } from '@printr/sdk/balance-lite';
// 标准方式 (含完整 web3.js)
import { getBalance } from '@printr/sdk/balance';
```
## 类型导出
> 社区追踪: [feat: types-only @printr/sdk/openapi entry (#98)](https://github.com/PrintrFi/printr-mcp/issues/98)
仅需类型定义时，使用 OpenAPI 类型子路径：
```typescript
// 仅导入类型，无运行时依赖
import type { paths, components, operations } from '@printr/sdk/openapi';
// 使用类型
type TokenResponse = components['schemas']['Token'];
```
## 本地开发部署
### 1. 克隆仓库
```bash
git clone https://github.com/PrintrFi/printr-mcp.git
cd printr-mcp
```
### 2. 安装依赖
```bash
bun install
```
### 3. 构建 SDK
```bash
bun run build:sdk
```
### 4. 配置环境
创建 `.env` 文件：
```bash
PRINTR_API_KEY=pk_dev_xxx
PRINTR_API_BASE_URL=https://api-preview.printr.money
```
### 5. 启动 MCP 服务器
```bash
# 开发模式 (热重载)
cd packages/mcp && bun run dev
# 生产模式
cd packages/mcp && bun run start
```
### 6. 验证部署
```bash
# 运行测试
bun test
# 类型检查
bun run typecheck
# 完整检查
bun run check
```
资料来源：[package.json:15-30](https://github.com/PrintrFi/printr-mcp/blob/main/package.json)
## 示例验证
### SDK 基础示例
```bash
bun run --cwd examples/sdk-basic start
```
### MCP 客户端示例
```bash
bun run --cwd examples/mcp-client start
```
### 示例测试
```bash
bun run examples:test
```
资料来源：[examples/README.md:1-50](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
## 常见问题
### Q: MCP 服务器启动失败
检查以下配置：
1. `PRINTR_API_KEY` 是否正确设置
2. `PRINTR_API_BASE_URL` 是否可达
3. 端口 3000 是否被占用
### Q: 交易签名失败
确保：
- `EVM_WALLET_PRIVATE_KEY` 或 `SVM_WALLET_PRIVATE_KEY` 已配置
- 私钥格式正确（EVM 为十六进制，Solana 为 Base58）
- 钱包有足够的 Gas/余额
### Q: 图片生成不可用
配置 `OPENROUTER_API_KEY` 环境变量：
```json
{
"env": {
"OPENROUTER_API_KEY": ""
}
}
```
### Q: Workers 环境导入失败
当前需使用 `@printr/sdk` 的子路径导入，避免导入 `image.ts` 等 Node.js 专用模块。
## 相关资源
- [GitHub 仓库](https://github.com/PrintrFi/printr-mcp)
- [SDK 文档](./sdk/README.md)
- [CLI 安装指南](./cli/README.md)
- [社区 Issue #103: SDK Workers-ready](https://github.com/PrintrFi/printr-mcp/issues/103)
- [社区 Issue #100: Signer 原语提取](https://github.com/PrintrFi/printr-mcp/issues/100)
---
---
## Doramagic 踩坑日志
项目：PrintrFi/printr-mcp
摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Epic A: SDK Workers-ready。
## 1. 安装坑 · 来源证据：Epic A: SDK Workers-ready
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Epic A: SDK Workers-ready
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_29b9aed5d33e473983c9b6d2f328e9a3 | https://github.com/PrintrFi/printr-mcp/issues/103 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 2. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `printr-mcp` 与安装入口 `@printr/mcp` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npm install @printr/mcp`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | repo=printr-mcp; install=@printr/mcp
## 3. 安装坑 · 来源证据：feat(sdk): extract signer primitive to @printr/sdk/signer
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(sdk): extract signer primitive to @printr/sdk/signer
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5d0a8de4311d400b8906158d86986f93 | https://github.com/PrintrFi/printr-mcp/issues/100 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：fix(sdk): emit Workers-friendly bundle, drop createRequire shim
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(sdk): emit Workers-friendly bundle, drop createRequire shim
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f67e8511c09a4830815ffe723906fb6e | https://github.com/PrintrFi/printr-mcp/issues/97 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 5. 配置坑 · 来源证据：Environment discriminant + memoized getConfigs(env)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Environment discriminant + memoized getConfigs(env)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_559212dc171940c4b45b5e0a598cefb2 | https://github.com/PrintrFi/printr-mcp/issues/82 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | README/documentation is current enough for a first validation pass.
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：ABI codegen pipeline for printr contracts
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ABI codegen pipeline for printr contracts
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1a90df3c69554032b209fe1f2740be23 | https://github.com/PrintrFi/printr-mcp/issues/85 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 11. 安全/权限坑 · 来源证据：Epic B: Shared SDK primitives
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Epic B: Shared SDK primitives
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a639b0c625d54d81a36e6c2a5748fee2 | https://github.com/PrintrFi/printr-mcp/issues/104 | 来源类型 github_issue 暴露的待验证使用条件。
## 12. 安全/权限坑 · 来源证据：feat(sdk): lighter balance via direct JSON-RPC
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(sdk): lighter balance via direct JSON-RPC
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_325628e3191e47fcb9eb5174d7adf1cc | https://github.com/PrintrFi/printr-mcp/issues/101 | 来源类型 github_issue 暴露的待验证使用条件。
## 13. 安全/权限坑 · 来源证据：feat(sdk): types-only @printr/sdk/openapi entry
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(sdk): types-only @printr/sdk/openapi entry
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a51e6052cf214b6fbdc4a79113af79d5 | https://github.com/PrintrFi/printr-mcp/issues/98 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. 安全/权限坑 · 来源证据：feat(sdk,mcp): cross-chain bridge tools (Base ↔ Solana)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(sdk,mcp): cross-chain bridge tools (Base ↔ Solana)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_be3c80140bee4db4a5894e0352aa9061 | https://github.com/PrintrFi/printr-mcp/issues/63 | 来源类型 github_issue 暴露的待验证使用条件。
## 15. 安全/权限坑 · 来源证据：feat(sdk,mcp): trading tools — swap, buy, sell by ticker
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(sdk,mcp): trading tools — swap, buy, sell by ticker
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e0b064711428444693fdc8f1b799e8f5 | https://github.com/PrintrFi/printr-mcp/issues/62 | 来源类型 github_issue 暴露的待验证使用条件。
## 16. 安全/权限坑 · 来源证据：feat: Privy agentic wallet support
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: Privy agentic wallet support
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5944b6734be44c1bb06310cbebfbf684 | https://github.com/PrintrFi/printr-mcp/issues/7 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 17. 安全/权限坑 · 来源证据：fix(sdk): lazy-load sharp + node:fs in image.ts
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：fix(sdk): lazy-load sharp + node:fs in image.ts
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d19b09d9ce0d406c80390e54f4658131 | https://github.com/PrintrFi/printr-mcp/issues/96 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 18. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | issue_or_pr_quality=unknown
## 19. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp | release_recency=unknown