简介

Printr MCP 是一个基于 Model Context Protocol (MCP) 的 AI Agent 工具包，用于在多条区块链上创建和管理代币。该项目由 PrintrFi 团队开发，目标是为 AI 助手提供原生的链上操作能力，使用户能够通过自然语言在 Base、以太坊、Solana 等区块链上部署代币、查询余额、执行交易等操作。

项目采用 monorepo 结构，包含三个核心包：

资料来源：README.md:1-10

概述

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

安装方式

npm install @printr/sdk
# 或
bun add @printr/sdk
# 或
yarn add @printr/sdk

资料来源：packages/sdk/README.md:20-28

创建客户端

SDK 使用 createPrintrClient 工厂函数创建客户端实例，支持通过环境变量或直接传入配置：

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',
});

配置参数说明：

资料来源：packages/sdk/README.md:30-45

多环境支持

SDK 支持通过环境变量切换不同运行环境：

资料来源：README.md:40-55

MCP 服务器配置

MCP 协议集成

MCP 服务器通过 Model Context Protocol 与 AI Agent 通信，支持 stdio 和 HTTP 两种传输方式。配置时需要在 AI 客户端（如 Cursor、Claude Desktop 等）的 MCP 配置文件中声明服务器路径。

MCP 服务器工作流程：

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 访问权限和链上交互能力：

资料来源：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 客户端：

npx printr-mcp setup

CLI 安装流程如下：

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 会显示配置结果摘要：

资料来源：packages/cli/src/commands/setup/components/summary.tsx:1-35

技能安装

对于需要 AI Agent 能力的场景，可使用 skill 命令安装 Printr 技能：

npx printr-mcp skill install

该命令将 printr 技能定义安装到检测到的 AI 客户端代理中。

资料来源：packages/cli/src/commands/skill/components/summary.tsx:1-25

链配置

支持的链

Printr MCP 支持通过 CAIP-2 规范标识各链，格式为 namespace:reference：

资料来源：packages/mcp/src/tools/get-balance.ts:30-45

余额查询配置

余额查询工具支持原生代币和 SPL/ERC-20 代币余额查询：

原生代币查询 (printr_get_balance)：

inputSchema = {
  account: "eip155:8453:0x...",  // CAIP-10 格式地址
  rpc_url: "https://...",         // 可选，自定义 RPC
}

代币余额查询 (printr_get_token_balance)：

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

典型配置场景

场景一：仅查询（只读）

适用于不需要签名交易的场景：

{
  "mcpServers": {
    "printr": {
      "command": "npx",
      "args": ["-y", "printr-mcp"]
    }
  },
  "env": {
    "PRINTR_API_KEY": "your-api-key"
  }
}

资料来源：README.md:25-40

场景二：自主交易签名

适用于 AI Agent 需要自主执行链上交易的场景：

{
  "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 生成代币头像的场景：

{
  "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 配置：

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 可使用以下工具：

资料来源：README.md:60-80

故障排除

常见配置问题

资料来源：packages/mcp/src/tools/get-balance.ts:35-50

RPC 连接问题

使用自定义 RPC 时，确保：

1. RPC URL 可公开访问
2. 支持对应的链 ID
3. 有足够的请求配额

概述

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/ 目录下：

资料来源：package.json:9

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 包提供了精细化的子路径导出，允许消费者按需导入，避免不必要的依赖引入：

资料来源：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 函数：

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 工具。工具通过统一的注册机制暴露：

server.registerTool(
  "printr_get_balance",
  {
    description: "获取钱包的原生代币余额",
    inputSchema,
    outputSchema,
  },
  handler
);

资料来源：packages/mcp/src/tools/get-balance.ts:40-55

核心工具列表

资料来源：README.md:30-50

环境变量配置

MCP 包扩展了 SDK 的环境变量，并添加了 MCP 特定的配置：

资料来源：packages/mcp/src/lib/env.ts:15-35

CLI 包结构

命令模块

CLI 包提供了交互式终端界面，使用 ink（React for CLI）构建：

资料来源：packages/cli/src/commands/setup/components/summary.tsx:1-30

客户端检测

CLI 工具会自动检测支持的 AI 客户端，包括 Claude Desktop、Cursor、Windsurf 等，并生成相应的配置文件。资料来源：packages/cli/src/commands/setup/lib/clients.ts

构建与测试

根目录任务脚本

资料来源：package.json:12-18

包级别任务

每个包可以独立运行其任务：

# 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

构建流程

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]

版本与发布

当前版本

最新版本修复了与 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)

目标：支持代币交换、购买、出售和跨链桥接功能。

快速开始

# 安装依赖
bun install

# 开发模式运行 MCP 服务器
bun dev

# 运行所有测试
bun test

# 完整检查（类型 + lint + 测试）
bun run check

技术栈总结

概述

@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 模式，允许消费者按需导入，避免引入不必要的依赖：

资料来源：packages/sdk/package.json:15-60

条件导出（Conditional Exports）

为支持边缘运行时，SDK 在 package.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 工厂函数创建：

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 函数是代币创建的核心入口：

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：

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 调用：

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

图片处理模块

image.ts 提供代币头像的 AI 生成能力：

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 资料来源：issues/102

钱包存储模块

keystore.ts 提供安全的加密钱包存储：

• AES-256-GCM 加密
• 内存中的钱包缓存
• 主密码保护

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 配置：

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 等边缘运行时。核心问题包括：

验收标准：Worker 导入 SDK barrel 不抛出异常。

资料来源：issues/103 资料来源：issues/97

懒加载策略

为解决 Node.js 特定依赖问题，SDK 采用懒加载模式：

// 静态导入（会触发依赖）
import { buildToken } from '@printr/sdk';

// 懒加载（条件执行）
async function getImageProcessor() {
  const { default: sharp } = await import('sharp');
  return sharp;
}

这种方式确保边缘运行时不会加载无用的 Node.js 模块。

资料来源：issues/96

依赖管理

主要运行时依赖

子路径与依赖隔离

通过子路径导出，SDK 实现依赖隔离：

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 环境变量

扩展配置

SDK 提供 getConfigs(env) 函数统一管理环境配置：

import { getConfigs } from '@printr/sdk';

const configs = getConfigs('mainnet');
// { apiBaseUrl, appUrl, rpcUrls, ... }

配置经过 memoize 优化，避免重复计算。

资料来源：issues/82

未来架构演进

Epic B: Shared SDK Primitives

计划将 MCP 内部逻辑提取到 SDK 共享子路径：

1. 签名器原语 (./signer): 统一的浏览器/服务端签名接口
2. 配置管理: 环境判别与配置获取的统一入口

资料来源：issues/104 资料来源：issues/100

Epic C: Agent Trading UX

SDK 规划的交易功能：

资料来源：issues/105 资料来源：issues/62 资料来源：issues/63

快速开始

安装

npm install @printr/sdk
# 或
bun add @printr/sdk

基本用法

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);
}

边缘环境用法

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 提供完整的代币生命周期管理能力。

概述

@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

整体架构

graph TB
    subgraph "MCP Server Layer"
        MCP[MCP Server Core<br/>@modelcontextprotocol/sdk]
        TOOLS[Tools Registry<br/>Token/Transfer/Balance...]
    end
    
    subgraph "Server Layer"
        APP[App Server<br/>app.ts]
        SESSIONS[Session Manager<br/>sessions.ts]
        WALLET_SESSIONS[Wallet Sessions<br/>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<br/>api.printr.money]
        RPC[RPC Providers<br/>Alchemy/Custom]
        OPENROUTER[OpenRouter<br/>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

服务器启动流程

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 特有变量。

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(),
});

资料来源：packages/mcp/src/lib/env.ts

2. 会话管理（sessions.ts）

会话管理器负责浏览器钱包签名流程，支持 MetaMask（EVM）和 Phantom（Solana）。

export function createSession(
  chainType: ChainType,
  sessionId: string,
  payload: SessionPayload,
): Session {
  return {
    id: sessionId,
    chainType,
    state: "pending",
    payload,
    createdAt: new Date(),
  };
}

会话状态流转：

stateDiagram-v2
    [*] --> pending: 创建会话
    pending --> active: 浏览器已打开
    active --> approved: 用户签名
    active --> rejected: 用户拒绝
    rejected --> [*]
    approved --> [*]: 交易已提交

关键配置：

资料来源：packages/mcp/src/server/sessions.ts

3. 钱包会话状态（wallet-sessions.ts）

活跃钱包管理当前已连接的钱包，支持通过私钥直接签名或浏览器钱包签名。

export interface ActiveWallet {
  chainType: ChainType;
  address: string;
  privateKey?: string;  // 仅在私钥模式下可用
  sessionId?: string;   // 浏览器签名模式
}

export const activeWallets = new Map<ChainType, ActiveWallet>();

资料来源：packages/mcp/src/server/wallet-sessions.ts

4. 钱包解析（wallet-elicit.ts）

wallet-elicit.ts 提供钱包地址解析和余额检查功能。

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 };

地址派生逻辑：

资料来源：packages/mcp/src/lib/wallet-elicit.ts

5. 工具注册（mcp.ts）

MCP 服务器通过 @modelcontextprotocol/sdk 注册所有工具。

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 工具列表

资料来源：packages/mcp/src/tools/launch-token.ts、packages/mcp/src/tools/transfer.ts

核心工具工作流

代币创建流程

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: 部署结果

转账流程

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 提供结构化日志和工具执行追踪功能。

export function logToolExecution<T>(
  toolName: string,
  handler: ToolLoggerFn<T>,
): (params: T) => Promise<ToolResponse> {
  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;
  };
}

资料来源：packages/mcp/src/lib/logging.ts

SDK 集成

MCP 服务器的核心业务逻辑依赖 @printr/sdk，包括：

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 的签名原语
• 跨链桥接工具
• 交易提供商集成

运行要求

启动方式

# 生产环境
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 源码
• CLI 工具
• Skill 定义
• Model Context Protocol 规范

概述

@printr/mcp 提供了一套完整的 MCP（Model Context Protocol）工具集，使 AI Agent 能够通过自然语言对话的方式与 Printr 协议交互，执行代币创建、部署、交易、钱包管理等操作。这些工具封装了复杂的区块链交互逻辑，提供了统一的接口层，让开发者无需深入了解底层细节即可构建区块链应用。

工具系统基于 MCP SDK 实现，每个工具都包含输入输出 Schema 定义，通过 zod 进行参数验证，并返回结构化的结果。工具注册流程统一由 @modelcontextprotocol/sdk 的 registerTool 方法处理。资料来源：packages/mcp/src/tools/launch-token.ts:1-27

工具分类架构

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

获取代币创建的成本估算。该工具允许用户在正式创建代币前了解所需费用，支持多链部署场景。

资料来源：packages/mcp/src/tools/quote.ts

printr_create_token

生成未签名的代币创建交易载荷。与 printr_launch_token 不同，该工具仅返回交易数据，签名操作需由外部完成。

核心功能：

• 生成跨链代币创建请求
• 支持 EVM 和 SVM 双协议栈
• 返回符合 CAIP-2 标准的链标识
• 可指定初始购买参数

资料来源：packages/mcp/src/tools/create-token.ts

printr_launch_token

一站式代币创建和签名工具。整合了交易生成、签名、提交全流程，是最常用的代币发行接口。

// 核心流程示意
import { buildToken, signAndSubmitEvm, signAndSubmitSvm } from "@printr/sdk";

// 支持的 fee_sink 类型
const feeSinkSchema = z.enum(["dev", "stake_pool", "buyback", "liquidity_pool"]);

参数说明：

返回结果包含：

• 代币 ID（十六进制格式）
• 各链的合约地址
• 交易哈希
• 部署状态

资料来源：packages/mcp/src/tools/launch-token.ts:1-45

printr_generate_image

通过 OpenRouter API 生成代币头像。该工具需要配置 OPENROUTER_API_KEY 环境变量。

资料来源：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

printr_sign_and_submit_svm

签署并提交 Solana 链交易。处理 Phantom 等 SVM 钱包签名。

支持的钱包类型：

• 浏览器钱包（Phantom 等）
• 私钥直接签名
• 部署钱包

资料来源：packages/mcp/src/tools/sign-and-submit-svm.ts

printr_open_web_signer

启动浏览器签名会话。通过 URL 方式打开钱包，让用户在浏览器中完成签名操作。

工作流程：

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

查询工具

printr_get_token

通过代币 ID 或地址查询代币详情。

返回数据结构：

• 代币基本信息（名称、符号、描述）
• 供应量信息
• 部署状态
• 各链合约地址
• 代币图标

资料来源：packages/mcp/src/tools/get-token.ts

printr_get_deployments

查询代币在各链的部署状态。

返回信息包括：

• 各链的合约地址
• 交易 ID
• 区块时间戳
• 毕业价格和供应量
• 初始流动性状态

资料来源：packages/mcp/src/tools/get-deployments.ts

printr_get_balance

查询钱包的原生代币余额。

资料来源：packages/mcp/src/tools/get-balance.ts

printr_get_token_balance

查询钱包的 ERC-20 或 SPL 代币余额。

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"),
});

返回字段：

验证规则：

• Token 和 Wallet 必须在同一链上
• 地址必须符合 CAIP-10 标准

资料来源：packages/mcp/src/tools/get-token-balance.ts:1-60

转账工具

printr_transfer

转账原生代币（ETH、SOL 等）。

核心验证流程：

graph TD
    A[输入 to 地址] --> B{parseCaip10}
    B -->|失败| E[返回错误]
    B -->|成功| C{getChainMeta}
    C -->|失败| E
    C -->|成功| D{validateBalance}
    D -->|余额不足| F[返回错误]
    D -->|通过| G[执行转账]

参数结构：

链支持：

• EVM 链（Base、Ethereum、Polygon 等）
• SVM 链（Solana）

资料来源：packages/mcp/src/tools/transfer.ts:1-45

printr_transfer_token

转账 ERC-20 或 SPL 代币。

费用管理工具

printr_claim_fees

领取协议费用。允许代币创建者或指定角色领取累积的费用收入。

支持的费用类型： dev、stake_pool、buyback、liquidity_pool

资料来源：packages/mcp/src/tools/claim-fees.ts:1-35

printr_drain_deployment_wallet

清空部署钱包余额到金库。支持 EVM 和 SVM 双链。

输出参数：

依赖注入设计：

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 服务器：

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 工具依赖多个环境变量：

资料来源：packages/mcp/src/lib/env.ts:1-45

错误处理

工具采用统一的错误处理模式：

import { err, ok, type Result } from "neverthrow";
import { ResultAsync } from "neverturn";

function toolHandler(input: Input): ResultAsync<Output, ToolError> {
  return ResultAsync.fromPromise(
    async () => { /* 业务逻辑 */ },
    (e) => ({ message: String(e) })
  );
}

错误类型：

• TransferToolError - 转账相关错误
• ImageError - 图片处理错误
• PrintrApiError - API 调用错误

相关 Epic 与路线图

根据社区反馈，以下功能正在规划中：

规划中的交易工具：

• printr_swap - 代币兑换
• printr_buy - 买入代币
• printr_sell - 卖出代币
• 跨链桥接工具（Base ↔ Solana）

资料来源：Epic C: Agent trading UX

最佳实践

1. 使用 CAIP-10 地址格式

所有地址参数应使用 CAIP-10 标准格式：

• EVM: eip155:1:0x1234...
• SVM: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp

2. 优先使用部署钱包

避免在代码中硬编码私钥，使用部署钱包管理功能：

// 推荐方式
const walletId = await resolveWallet(chainType);

3. 利用 Quote 工具预估费用

在创建代币前，先调用 printr_quote 获取准确的成本估算。

4. 批量操作优化

对于多链部署，使用 printr_get_deployments 批量查询部署状态，减少 API 调用次数。

系统架构概览

钱包与签名系统由多个层次的组件构成，形成从环境配置到实际交易签署的完整流程。

graph TD
    A["环境变量配置<br/>(env.ts)"] --> B["钱包会话管理<br/>(wallet-sessions.ts)"]
    B --> C["签名策略选择"]
    C --> D1["浏览器签名<br/>(open-web-signer.ts)"]
    C --> D2["私钥直签 EVM<br/>(sign-and-submit-evm.ts)"]
    C --> D3["私钥直签 SVM<br/>(sign-and-submit-svm.ts)"]
    
    E["部署钱包管理"] --> E1["资金充值<br/>(fund-deployment-wallet.ts)"]
    E --> E2["资金回收<br/>(drain-deployment-wallet.ts)"]
    
    F["SDK 密钥库<br/>(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/lib/env.ts:29-34

配置优先级

当环境变量与密钥库同时存在时，系统遵循以下优先级：

1. 私钥直签优先：若设置了 *_WALLET_PRIVATE_KEY，直接使用该私钥签名
2. 密钥库兜底：若无直传私钥，则尝试从加密密钥库加载钱包
3. 浏览器签名兜底：若均不可用，则启动浏览器签名会话

密钥库系统

SDK 层的密钥库系统 (packages/sdk/src/keystore.ts) 提供了安全的私钥存储机制。

核心功能

密钥库使用 AES-256-GCM 加密算法保护私钥安全：

• 主密码派生：使用 PBKDF2 从主密码派生加密密钥
• 随机盐值：每次加密使用唯一的随机盐值
• 认证标签：包含加密数据的完整性验证

密钥库文件结构

{
  "version": 1,
  "wallets": {
    "eip155:8453:0x...": {
      "encryptedKey": "base64编码的加密私钥",
      "salt": "base64编码的盐值",
      "iv": "base64编码的初始向量"
    }
  }
}

签名会话管理

浏览器签名工作流

对于非托管钱包场景，系统通过浏览器签名 URL 会话实现安全签名：

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、以太坊主网等）的交易：

// 核心流程伪代码
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 链的交易：

// 核心流程伪代码
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

签名策略接口

type SignerStrategy = {
  // EVM 签名
  signEvm: (payload: Uint8Array, chainId: string) => Promise<string>;
  
  // SVM 签名  
  signSvm: (message: Uint8Array) => Promise<Uint8Array>;
  
  // 获取钱包地址
  getAddress: (chain: ChainType) => Promise<string>;
};

部署钱包管理

部署钱包是用于支付代币部署 Gas 费用的专用钱包，与用户主钱包分离。

资金充值

fund-deployment-wallet.ts 将资金从主钱包转入部署钱包：

资金回收

drain-deployment-wallet.ts 将部署钱包剩余资金转回财库：

资料来源：packages/mcp/src/tools/drain-deployment-wallet.ts:1-50

部署钱包生命周期

graph LR
    A["创建部署钱包"] --> B["充值资金"]
    B --> C["执行代币部署"]
    C --> D["交易完成"]
    D --> E["回收剩余资金"]
    E --> F["部署钱包清空"]
    
    style B fill:#e8f5e9
    style E fill:#ffebee

钱包会话状态管理

wallet-sessions.ts 维护会话状态：

安全考虑

私钥处理原则

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 层：

// 目标 API 结构
import { createSigner } from '@printr/sdk/signer';

const signer = createSigner({
  type: 'browser' | 'private-key' | 'hardware',
  chain: 'eip155:8453',
  onSign: async (payload) => { /* 签名回调 */ }
});

这将使所有 Printr 客户端（不仅是 MCP）能够以统一、安全的方式处理签名操作。

功能概览

Printr MCP 当前提供的交易工具主要分为以下几个类别：

核心工具详解

代币报价与创建

#### 获取报价 (printr_quote)

printr_quote 工具用于在正式创建代币之前获取成本估算，帮助用户和 Agent 了解需要准备的资金量。

输入参数：

初始购买配置示例：

{
  spend_usd: 10,           // 花费 USD 数量
  // 或
  supply_percentage: 100   // 供应量百分比
}

#### 创建代币 (printr_create_token)

生成未签名的代币创建交易载荷，Agent 或用户需要使用外部钱包进行签名。

核心流程：

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 和 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 代币。

支持的转账类型：

资料来源：packages/mcp/src/tools/transfer.ts、packages/sdk/src/transfer.ts

核心参数：

质押管理

Printr 提供了完整的质押工具套件，支持创建质押仓位、查询仓位和领取奖励。

#### 查询质押仓位 (printr_get_staking_positions)

获取指定钱包地址的所有质押仓位信息。

输出结构：

每个 Position 包含：

• position_id: 仓位 ID（CAIP-10）
• chain: 链标识
• staked_amount: 质押金额
• rewards_claimable: 可领取奖励
• unlock_time: 解锁时间（若有）

#### 领取质押奖励 (printr_claim_staking_rewards)

从指定质押仓位领取累积的奖励。

输入参数：

错误处理：

工具会检查 Treasury 钱包配置，确保签名者有权限领取奖励：

function getTreasuryContext(chainType: ChainType): Result<TreasuryContext, ClaimError> {
  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 服务器统一注册和管理：

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]

工具注册模式：

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 包中，提供可复用的业务逻辑：

轻量级余额查询（规划中）：

根据社区反馈（Issue #101），当前的 balance.ts 依赖 @solana/web3.js（约 600KB）和 viem，对边缘运行时（如 Cloudflare Workers）造成负担。计划中的轻量级版本将直接使用 JSON-RPC 调用，减少 bundle 体积。

环境配置

交易工具依赖以下环境变量：

资料来源：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. 跨链转账：仅支持同链转账，跨链桥接功能待实现

使用示例

获取代币创建报价

{
  "name": "printr_quote",
  "arguments": {
    "creator_accounts": ["eip155:8453:0xYourAddress"],
    "chains": ["eip155:8453"],
    "initial_buy": {
      "spend_usd": 10
    }
  }
}

查询代币余额

{
  "name": "printr_get_token_balance",
  "arguments": {
    "token": "eip155:8453:0xTokenAddress",
    "wallet": "eip155:8453:0xWalletAddress"
  }
}

转账代币

{
  "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）

概述

@printr/sdk 的 Workers 兼容性是 Printr 项目的核心优化目标之一（Epic A: SDK Workers-ready，Issue #103）。该 Epic 的验收标准为："一个 Worker 导入 SDK barrel 文件时不抛出异常"。

当前 SDK 依赖 @solana/web3.js（约 600KB 压缩后）和 viem 等重型库，对于只需要查询余额或基础功能的边缘计算/Workers 场景，这造成了不必要的包体积负担。

问题分析

核心痛点

依赖体积对比

// 当前完整 SDK 依赖（约 600KB+）
@solana/web3.js  // ~600KB minified
viem             // ~200KB
sharp            // Node.js 原生模块
neverthrow       // ~10KB

解决方案

1. 轻量级余额查询：`@printr/sdk/balance-lite`

通过直接 JSON-RPC 调用替代重型 SDK，仅查询原生代币或 SPL 代币余额：

// packages/sdk/src/balance-lite.ts
import { ResultAsync } from 'neverthrow';

export interface BalanceLiteOptions {
  rpcUrl: string;
}

export const getNativeBalance = (
  address: string,
  options: BalanceLiteOptions
): ResultAsync<bigint, BalanceError> => {
  // 直接 JSON-RPC 调用，无重型依赖
};

文件路径： packages/sdk/src/balance-lite.ts

该子路径导出不包含 @solana/web3.js 和 viem，大幅降低包体积。

2. 类型专用导出：`@printr/sdk/openapi`

仅导出 OpenAPI 生成的类型定义（paths、components、operations），不包含任何运行时代码：

// 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 改为懒加载：

// 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：

// 修复前
import { createRequire } from "node:module";
var __require = createRequire(import.meta.url);

// 修复后
// 无 shim 代码，直接使用 ESM

导出子路径配置

package.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 场景

// 推荐：使用轻量级导入
import { getNativeBalance } from '@printr/sdk/balance-lite';
import type { paths } from '@printr/sdk/openapi';

// 避免：完整导入（包含重型依赖）
// import { createPrintrClient, buildToken } from '@printr/sdk';

包体积对比

架构流程图

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 与路线图

未来优化方向

1. 更多轻量子路径：将 transfer、evm、svm 等拆分为独立轻量模块
2. 图片字节处理（#102）：添加 processImageBytes(bytes: Uint8Array) 支持浏览器/边缘场景
3. 签名原语提取（#100）：将 @printr/sdk/signer 提取为独立子路径

验收标准

所有 Workers 兼容性修复共享同一验收门控：

"在 Cloudflare Worker 环境中导入 SDK barrel 文件，评估过程不抛出异常"

测试可通过以下方式验证：

// workers-entry.js
import('@printr/sdk'); // 不应抛出

总结

通过子路径导出、懒加载重型模块、直接 JSON-RPC 调用替代 SDK，@printr/sdk 正逐步实现 Cloudflare Workers 兼容性。开发者应根据实际需求选择合适的导入路径，平衡功能完整性与包体积限制。

概述

Printr MCP 项目包含两个主要部署单元：

@printr/mcp 依赖 @printr/sdk，两者需协同部署。

系统要求

Node.js 环境

引擎版本: Node.js >= 18
包管理器: Bun (推荐) 或 npm/yarn/pnpm
TypeScript: >= 6.0.0

资料来源：packages/sdk/package.json:14

MCP 服务器依赖

@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

环境变量配置

必需变量

资料来源：packages/mcp/src/lib/env.ts:10-11

钱包配置

⚠️ 安全警告: 私钥应存储在环境级别而非共享配置文件。使用 secrets 管理工具处理敏感信息。

资料来源：README.md:48-54

可选变量

RPC URL 配置

RPC_URLS 支持通过 ALCHEMY_RPC_TEMPLATES 模板或自定义端点配置多链 RPC：

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

部署架构

单进程部署

适用于开发环境和轻量级生产部署：

# 构建
bun run build

# 启动 MCP 服务器
cd packages/mcp
bun src/index.ts

HTTP 服务部署

MCP 支持通过 Hono HTTP 服务器暴露：

# 启动 HTTP 模式
cd packages/mcp
bun run start

服务默认监听端口 3000，可通过环境变量 PORT 调整。

MCP 工具调用方式

资料来源：README.md:56-74

构建流程

完整构建

从仓库根目录执行：

# 安装依赖
bun install

# 构建所有包
bun run build

分包构建

# 仅构建 SDK
cd packages/sdk && bun run build

# 仅构建 MCP
cd packages/mcp && bun run build

构建产物

资料来源：packages/sdk/package.json:7-8

多环境部署

开发环境

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

测试环境

PRINTR_API_KEY=pk_test_xxx
PRINTR_API_BASE_URL=https://api-staging.printr.money

生产环境

PRINTR_API_KEY=pk_live_xxx
PRINTR_API_BASE_URL=https://api.printr.money

Workers/Edge 运行时支持

社区追踪: Epic A: SDK Workers-ready (#103)

@printr/sdk 正朝着 Cloudflare Workers 和边缘运行时兼容方向演进。

当前限制

标准 SDK 包包含以下 Node.js 专用模块：

• sharp - 图片处理（通过 @printr/sdk/image 访问）
• node:fs/promises - 文件系统操作
• node:module (createRequire) - CJS 互操作

边缘兼容子路径

资料来源：packages/sdk/package.json:20-36

轻量余额方案

社区追踪: feat: lighter balance via direct JSON-RPC (#101)

为减少包体积，新增 @printr/sdk/balance-lite 子路径，直接调用 Solana JSON-RPC 而不引入 @solana/web3.js (~600KB)：

// 边缘兼容方式
import { getBalanceLite } from '@printr/sdk/balance-lite';

// 标准方式 (含完整 web3.js)
import { getBalance } from '@printr/sdk/balance';

类型导出

社区追踪: feat: types-only @printr/sdk/openapi entry (#98)

仅需类型定义时，使用 OpenAPI 类型子路径：

// 仅导入类型，无运行时依赖
import type { paths, components, operations } from '@printr/sdk/openapi';

// 使用类型
type TokenResponse = components['schemas']['Token'];

本地开发部署

1. 克隆仓库

git clone https://github.com/PrintrFi/printr-mcp.git
cd printr-mcp

2. 安装依赖

bun install

3. 构建 SDK

bun run build:sdk

4. 配置环境

创建 .env 文件：

PRINTR_API_KEY=pk_dev_xxx
PRINTR_API_BASE_URL=https://api-preview.printr.money

5. 启动 MCP 服务器

# 开发模式 (热重载)
cd packages/mcp && bun run dev

# 生产模式
cd packages/mcp && bun run start

6. 验证部署

# 运行测试
bun test

# 类型检查
bun run typecheck

# 完整检查
bun run check

资料来源：package.json:15-30

示例验证

SDK 基础示例

bun run --cwd examples/sdk-basic start

MCP 客户端示例

bun run --cwd examples/mcp-client start

示例测试

bun run examples:test

资料来源：examples/README.md:1-50

常见问题

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 环境变量：

{
  "env": {
    "OPENROUTER_API_KEY": "<your-openrouter-key>"
  }
}

Q: Workers 环境导入失败

当前需使用 @printr/sdk 的子路径导入，避免导入 image.ts 等 Node.js 专用模块。

相关资源

• GitHub 仓库
• SDK 文档
• CLI 安装指南
• 社区 Issue #103: SDK Workers-ready
• 社区 Issue #100: Signer 原语提取

Pitfall Log / 踩坑日志

项目：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