# https://github.com/PrintrFi/printr-mcp Project Manual
Generated at: 2026-05-31 00:34:19 UTC
## Table of Contents
- [Introduction](#introduction)
- [Quick Start Guide](#quickstart)
- [System Architecture](#architecture-overview)
- [SDK Package (@printr/sdk)](#sdk-package)
- [MCP Server (@printr/mcp)](#mcp-server)
- [CLI Package (@printr/cli)](#cli-package)
- [Token Operations](#token-operations)
- [Wallet Management](#wallet-management)
- [Chain Support](#chain-support)
- [Epic Roadmap](#epic-roadmap)
## Introduction
### Related Pages
Related topics: [System Architecture](#architecture-overview), [Quick Start Guide](#quickstart)
Related Source Files
The following source files were used to generate this page:
- [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/mcp/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/README.md)
- [examples/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
# Introduction
Printr MCP is an open-source project that enables AI agents to create, manage, and trade tokens across multiple blockchain networks through a Model Context Protocol (MCP) interface. The project provides a TypeScript SDK (`@printr/sdk`) and an MCP server (`@printr/mcp`) that together allow any MCP-compatible AI client to interact with the Printr API for token operations.
## What is Printr MCP?
Printr MCP bridges the gap between AI agent workflows and blockchain token operations. Rather than requiring developers to build custom integrations, Printr MCP exposes a standardized tool interface that AI agents can use directly to:
- **Create tokens** on EVM chains (Base, Ethereum) and Solana
- **Manage wallets** with encrypted keystore storage
- **Query balances** across multiple chains
- **Transfer assets** between addresses
- **Monitor deployments** across target networks
- **Generate token images** via AI image models
Source: [README.md:1-10]()
## Architecture Overview
The project is organized as a monorepo with three primary packages that work together:
```mermaid
graph TD
A[AI Agent / MCP Client] --> B[@printr/mcp
MCP Server]
B --> C[@printr/sdk
TypeScript SDK]
C --> D[Printr API
api.printr.money]
C --> E[Blockchain RPCs
Solana / EVM]
B --> F[@printr/cli
Setup Commands]
```
### Package Structure
| Package | Description | Entry Point |
|---------|-------------|-------------|
| `@printr/sdk` | Core TypeScript SDK for Printr API | `packages/sdk/` |
| `@printr/mcp` | MCP server exposing blockchain tools | `packages/mcp/` |
| `@printr/cli` | CLI for installing Printr skill into agents | `packages/cli/` |
Source: [packages/sdk/package.json:1-5]()
## SDK Module Organization
The `@printr/sdk` package exposes multiple subpath exports for tree-shaking and selective imports:
```typescript
import { createPrintrClient } from '@printr/sdk'; // Main client
import { createPrintrClient } from '@printr/sdk/client'; // Client only
import { buildToken } from '@printr/sdk/evm'; // EVM token operations
import { buildToken } from '@printr/sdk/svm'; // Solana token operations
import { getBalance } from '@printr/sdk/balance'; // Balance queries
import { getBalance } from '@printr/sdk/balance-lite'; // Lightweight balance (Workers-ready)
import { transfer } from '@printr/sdk/transfer'; // Cross-chain transfers
import type { paths } from '@printr/sdk/openapi'; // OpenAPI types only
```
Source: [packages/sdk/package.json:20-50]()
### Bundle Optimization
The SDK is designed with Workers-readiness in mind ([Epic A: #103](https://github.com/PrintrFi/printr-mcp/issues/103)). Heavy dependencies like `@solana/web3.js` (~600KB) and `viem` are lazily loaded where possible, and a `balance-lite` variant avoids pulling these libraries for simple balance queries ([#101](https://github.com/PrintrFi/printr-mcp/issues/101)).
Node-specific dependencies (`sharp`, `node:fs`) in image processing are lazy-loaded to prevent them from being evaluated when imported in edge runtimes ([#96](https://github.com/PrintrFi/printr-mcp/issues/96)).
## MCP Tools Reference
The MCP server exposes tools organized by category:
### Token Operations
| Tool | Description |
|------|-------------|
| `printr_quote` | Get cost estimates for token creation |
| `printr_create_token` | Generate unsigned token creation tx |
| `printr_launch_token` | Create and sign a token in one call |
| `printr_get_token` | Look up token details by ID or address |
| `printr_get_deployments` | Check deployment status across chains |
Source: [README.md:40-50]()
### Signing
| Tool | Description |
|------|-------------|
| `printr_sign_and_submit_evm` | Sign and submit an EVM transaction |
| `printr_sign_and_submit_svm` | Sign and submit a Solana transaction |
| `printr_open_web_signer` | Start browser signing session |
Source: [packages/mcp/README.md:60-65]()
### Wallet Management
| Tool | Description |
|------|-------------|
| `printr_wallet_new` | Generate a new encrypted wallet |
| `printr_wallet_import` | Import an existing private key |
| `printr_wallet_unlock` | Activate a stored wallet for signing |
| `printr_wallet_list` | List wallets in keystore |
| `printr_wallet_remove` | Remove a wallet from keystore |
### Treasury & Deployment
| Tool | Description |
|------|-------------|
| `printr_set_treasury_wallet` | Unlock treasury wallet for funding |
| `printr_fund_deployment_wallet` | Create and fund an ephemeral wallet |
| `printr_drain_deployment_wallet` | Return unused funds to treasury |
Source: [packages/mcp/README.md:70-85]()
## Quick Start
### 1. Install the CLI
```bash
npm install -g @printr/cli
# or
bun add -g @printr/cli
```
### 2. Set up an AI Agent
```bash
printr setup
```
This installs the Printr skill into supported AI clients, configuring the necessary MCP server connection.
### 3. Configure Environment
```json
{
"env": {
"PRINTR_API_KEY": "",
"OPENROUTER_API_KEY": ""
}
}
```
Source: [README.md:15-35]()
### 4. Start Creating Tokens
```bash
# Example agent prompt:
"Create a new token called MyToken with symbol TKN on Base chain"
```
## SDK Usage Example
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
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,
);
if (result.isOk()) {
console.log('Token created:', result.value.token_id);
}
```
Source: [packages/sdk/README.md:25-50]()
## Key Concepts
### CAIP-10 Address Format
All addresses in Printr MCP use the [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-10.md) format for chain-aware addressing:
```
eip155:8453:0x1234... # EVM (eip155:chainId:address)
solana:4sdf... # Solana (solana:address)
```
Source: [packages/mcp/src/tools/get-token-balance.ts:1-10]()
### Chain Identifiers
| Chain | CAIP-2 ID | Type |
|-------|-----------|------|
| Base | `eip155:8453` | EVM |
| Ethereum | `eip155:1` | EVM |
| Solana | `solana:...` | SVM |
### Result Type Pattern
The SDK uses `neverthrow`'s `Result` and `ResultAsync` types for error handling:
```typescript
import { ok, err, ResultAsync } from 'neverthrow';
const result = await someAsyncOperation();
if (result.isOk()) {
console.log(result.value);
} else {
console.error(result.error);
}
```
## Run Examples
The repository includes runnable examples in `examples/`:
```bash
bun install
bun run build
# Run SDK basic example
bun run --cwd examples/sdk-basic start
# Run MCP client example
bun run --cwd examples/mcp-client start
```
Source: [examples/README.md:1-30]()
## Related Documentation
- [SDK Reference](packages/sdk/README.md) — Detailed SDK API documentation
- [MCP Tools Reference](packages/mcp/README.md) — Complete list of MCP tools
- [CLI Reference](packages/cli/README.md) — Setup and configuration commands
- [Skill Definition](packages/cli/skills/printr/SKILL.md) — Full tool list and behavioral hints
## Roadmap
Active development focuses on three main epics:
1. **Epic A: SDK Workers-ready** ([#103](https://github.com/PrintrFi/printr-mcp/issues/103)) — Full Cloudflare Workers compatibility
2. **Epic B: Shared SDK primitives** ([#104](https://github.com/PrintrFi/printr-mcp/issues/104)) — Extract common signing and wallet logic
3. **Epic C: Agent trading UX** ([#105](https://github.com/PrintrFi/printr-mcp/issues/105)) — Enable swap, buy, sell, and bridge operations
Additional planned features include:
- Cross-chain bridging between Base and Solana ([#63](https://github.com/PrintrFi/printr-mcp/issues/63))
- Trading tools for token swaps ([#62](https://github.com/PrintrFi/printr-mcp/issues/62))
- Privy agentic wallet support ([#7](https://github.com/PrintrFi/printr-mcp/issues/7))
- ABI codegen pipeline for contracts ([#85](https://github.com/PrintrFi/printr-mcp/issues/85))
## Support and Contributing
- **Issues**: [GitHub Issues](https://github.com/PrintrFi/printr-mcp/issues)
- **Documentation**: This wiki and inline code documentation
- **Community**:参与社区讨论获取最新更新和功能请求
---
## Quick Start Guide
### Related Pages
Related topics: [Introduction](#introduction), [MCP Server (@printr/mcp)](#mcp-server)
Related Source Files
The following source files were used to generate this page:
- [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/skills/printr/SKILL.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/skills/printr/SKILL.md)
- [examples/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/examples/README.md)
- [packages/mcp/src/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
# Quick Start Guide
This guide provides everything you need to get started with Printr MCP — from installing the SDK to launching your first token programmatically.
## Overview
Printr MCP is a TypeScript SDK and MCP server that enables AI agents to create and manage tokens across EVM chains (Base, Ethereum, etc.) and Solana. The repository provides:
- **@printr/sdk** — TypeScript SDK for programmatic token operations
- **@printr/mcp** — MCP server exposing tools for AI agent consumption
- **@printr/cli** — CLI for agent setup and configuration
Source: [README.md]()
## Installation
### SDK Installation
Install the SDK using your preferred package manager:
```bash
npm install @printr/sdk
# or
bun add @printr/sdk
# or
yarn add @printr/sdk
```
The SDK requires Node.js >=18 and supports TypeScript ^6.0. Source: [packages/sdk/package.json:1-10]()
### MCP Server Setup
For MCP server installation, use the CLI to install the Printr skill into your AI client:
```bash
printr setup
```
This command detects supported clients (Claude Desktop, etc.) and installs the required configuration. Source: [packages/cli/src/commands/setup/components/summary.tsx:5-7]()
## Environment Configuration
### Required Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `PRINTR_API_KEY` | Partner API key | Yes |
| `PRINTR_API_BASE_URL` | API endpoint (defaults to preview) | No |
### Optional Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `OPENROUTER_API_KEY` | Enables auto image generation | — |
| `OPENROUTER_IMAGE_MODEL` | Image model override | — |
| `EVM_WALLET_PRIVATE_KEY` | Hex private key for autonomous signing | — |
| `SVM_WALLET_PRIVATE_KEY` | Base58 keypair secret for Solana | — |
Source: [README.md:28-48]()
For autonomous transaction signing without browser prompts, set private keys in your environment:
```json
{
"env": {
"EVM_WALLET_PRIVATE_KEY": "",
"SVM_WALLET_PRIVATE_KEY": ""
}
}
```
> **Security Note:** Keep private keys out of shared configs. Use environment-level secrets when possible. Source: [README.md:43-44]()
## SDK Quick Start
### Initialize the Client
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
```
Source: [packages/sdk/README.md:26-32]()
### Create a Token
```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,
);
if (result.isOk()) {
console.log('Token created:', result.value.token_id);
}
```
Source: [packages/sdk/README.md:33-47]()
### SDK Export Subpaths
The SDK provides granular imports to optimize bundle size:
| Subpath | Purpose |
|---------|---------|
| `@printr/sdk` | Full SDK (all features) |
| `@printr/sdk/client` | API client + types |
| `@printr/sdk/chains` | Chain configurations |
| `@printr/sdk/evm` | EVM utilities |
| `@printr/sdk/svm` | Solana (SVM) utilities |
| `@printr/sdk/schemas` | Zod validation schemas |
| `@printr/sdk/caip` | CAIP-10/CAIP-2 address utilities |
| `@printr/sdk/balance` | Balance queries (full) |
| `@printr/sdk/balance-lite` | Lightweight balance via JSON-RPC |
| `@printr/sdk/transfer` | Token transfers |
Source: [packages/sdk/package.json:18-46]()
## MCP Tools Reference
Once the MCP server is running, agents have access to the following tools:
### Token Operations
| Tool | Description | Source |
|------|-------------|--------|
| `printr_quote` | Get cost estimates for token creation | [README.md:50]() |
| `printr_create_token` | Generate unsigned token creation tx | [README.md:51]() |
| `printr_launch_token` | Create and sign a token in one call | [README.md:52]() |
| `printr_get_token` | Look up token details by ID or address | [README.md:53]() |
| `printr_get_deployments` | Check deployment status across chains | [README.md:54]() |
### Signing Tools
| Tool | Description | Source |
|------|-------------|--------|
| `printr_sign_and_submit_evm` | Sign and submit EVM transaction | [README.md:55]() |
| `printr_sign_and_submit_svm` | Sign and submit Solana transaction | [README.md:56]() |
| `printr_open_web_signer` | Start browser signing session | [README.md:57]() |
### Utility Tools
| Tool | Description | Source |
|------|-------------|--------|
| `printr_get_token_balance` | Query ERC-20 or SPL token balance | [packages/mcp/src/tools/get-token-balance.ts:1-5]() |
| `printr_generate_image` | AI-powered token avatar generation | [README.md:58]() |
For the complete tool list including wallet, balance, transfer, fees, and staking tools, see the [skill definition](packages/cli/skills/printr/SKILL.md). Source: [README.md:59-61]()
## Workflow: Launch a Token
```mermaid
graph TD
A[Agent] -->|quote| B[Get cost estimate]
A -->|create_token| C[Generate unsigned tx]
C -->|sign| D[Browser wallet or private key]
D -->|launch_token| E[Submit to blockchain]
E -->|check| F[Verify deployment]
style A fill:#e1f5fe
style F fill:#c8e6c9
```
### Step 1: Get a Quote
```typescript
const quote = await printr_quote({
chains: ['eip155:8453'],
initial_buy: { spend_usd: 10 },
});
```
### Step 2: Create the Token
```typescript
const unsigned = await printr_create_token({
creator_accounts: ['eip155:8453:0xYourAddress'],
name: 'My Token',
symbol: 'TKN',
chains: ['eip155:8453'],
initial_buy: { spend_usd: 10 },
});
```
### Step 3: Sign and Submit
Without autonomous signing, the agent returns a deep link for browser signing:
```json
{
"url": "https://app.printr.money/sign?session=...",
"session_token": "ephemeral-token",
"api_port": 3456
}
```
With `EVM_WALLET_PRIVATE_KEY` set, the transaction is signed and submitted automatically.
Source: [packages/mcp/src/tools/launch-token.ts:1-25]()
## Running Examples
The repository includes runnable examples in the `examples/` directory:
### SDK Basic Example
Demonstrates core SDK functionality:
- Creating a Printr client
- Getting quotes for token creation
- Fetching token details
- Checking deployment status
- Listing supported chains
```bash
bun run --cwd examples/sdk-basic start
```
### MCP Client Example
Demonstrates programmatic MCP server interaction:
- Spawning the MCP server
- Connecting via stdio transport
- Listing available tools
- Calling tools directly
```bash
bun run --cwd examples/mcp-client start
```
Source: [examples/README.md:1-35]()
### CI Validation
Run all examples for post-publish smoke testing:
```bash
# Run all examples
bun run examples:test
# Or individually
bun run --cwd examples/sdk-basic test
bun run --cwd examples/mcp-client test
```
> **Note:** Examples use `workspace:*` dependencies for local development. No API key is required for read-only operations (quotes, token lookup, chains). Source: [examples/README.md:36-42]()
## Framework Compatibility
| Runtime | Status | Notes |
|---------|--------|-------|
| Node.js >=18 | ✅ Supported | Full feature support |
| Bun | ✅ Supported | Primary development runtime |
| Browsers | ⚠️ Partial | Browser wallet signing required |
| Cloudflare Workers | ⚠️ In Progress | See Epic A (#103) |
The SDK is framework-agnostic and works with Node.js, Bun, and browsers. Source: [packages/sdk/README.md:14]()
## Next Steps
- Review the [SKILL.md](packages/cli/skills/printr/SKILL.md) for complete tool documentation
- Explore [Epic A: SDK Workers-ready](https://github.com/PrintrFi/printr-mcp/issues/103) for edge runtime support
- Consider [Epic C: Agent Trading UX](https://github.com/PrintrFi/printr-mcp/issues/105) for future swap/buy/sell capabilities
- Set up image generation by adding `OPENROUTER_API_KEY` to your environment
---
## System Architecture
### Related Pages
Related topics: [SDK Package (@printr/sdk)](#sdk-package), [MCP Server (@printr/mcp)](#mcp-server), [CLI Package (@printr/cli)](#cli-package)
Related Source Files
The following source files were used to generate this page:
- [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
- [packages/sdk/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/index.ts)
- [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/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)
- [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/drain-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/drain-deployment-wallet.ts)
- [packages/sdk/src/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.ts)
# System Architecture
## Overview
The printr-mcp repository implements a dual-layer architecture consisting of the `@printr/sdk` TypeScript SDK and the `@printr/mcp` Model Context Protocol server. This architecture enables AI agents to interact with Printr's token creation and management platform across multiple blockchain ecosystems through a standardized interface.
The system is designed to support multi-chain token operations including EVM chains (Base, Ethereum, BNB, AVAX) and Solana, providing a unified API surface for token launching, balance queries, and wallet management. Source: [packages/sdk/package.json:1-15]()
## Architecture Layers
The architecture follows a layered approach with clear separation of concerns:
```mermaid
graph TD
subgraph "Client Layer"
CLI[CLI Agents]
AI[AI Assistants]
Apps[Web Applications]
end
subgraph "Protocol Layer"
MCP[MCP Server
@printr/mcp]
end
subgraph "SDK Layer"
SDK[@printr/sdk]
HTTP[OpenAPI Client]
gRPC[gRPC Client]
end
subgraph "API Layer"
API[Printr API
api.printr.money]
end
subgraph "Blockchain Layer"
EVM[EVM Chains]
SVM[Solana]
end
CLI --> MCP
AI --> MCP
Apps --> MCP
MCP --> SDK
SDK --> HTTP
SDK --> gRPC
HTTP --> API
gRPC --> API
SDK --> EVM
SDK --> SVM
```
## Package Structure
### @printr/sdk
The SDK package provides the core functionality for interacting with Printr's API and blockchain networks. It exports several key subpaths for different capabilities:
| Export | Purpose |
|--------|---------|
| `@printr/sdk` (default) | Barrel export for all SDK functionality |
| `@printr/sdk/client` | OpenAPI REST client |
| `@printr/sdk/proto` | Protocol Buffer definitions |
| `@printr/sdk/evm` | EVM chain utilities |
| `@printr/sdk/solana` | Solana utilities |
| `@printr/sdk/token` | Token creation and management |
| `@printr/sdk/balance` | Balance query operations |
| `@printr/sdk/signer` | Signing session primitives |
Source: [packages/sdk/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/index.ts)
The SDK uses Protocol Buffers for type-safe communication with the backend API, generating TypeScript classes from `.proto` definitions in `packages/sdk/src/proto/api/`. Source: [packages/sdk/src/proto/api/api_pb.ts:1-50]()
### @printr/mcp
The MCP package wraps the SDK functionality as Model Context Protocol tools, enabling AI agents to invoke operations through a standardized tool-calling interface:
```mermaid
graph LR
Tools[Tool Definitions] --> Register[registerTool
MCP Server]
Register --> Server[McpServer Instance]
Server --> Transport[Stdio Transport]
Transport --> Agent[AI Agent]
```
Source: [packages/mcp/src/mcp.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/mcp.ts)
## Core Components
### SDK Client
The `createPrintrClient` factory creates a configured client instance:
```typescript
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
```
The client supports dual transport protocols:
- **REST/OpenAPI** via `openapi-fetch` for standard REST endpoints
- **gRPC/Connect** via `@connectrpc/connect` and `@connectrpc/connect-web` for high-performance streaming
Source: [packages/sdk/package.json:20-35]()
### MCP Tool Registration
Tools are registered using the MCP SDK's `registerTool` method with Zod schemas for input/output validation:
```typescript
export function registerGetBalanceTool(server: McpServer): void {
server.registerTool(
"printr_get_balance",
{
description: "Get the native token balance of a wallet address...",
inputSchema,
outputSchema,
},
logToolExecution("printr_get_balance", ({ account, rpc_url }) => {
// Implementation
}),
);
}
```
Source: [packages/mcp/src/tools/get-balance.ts:1-50]()
### Available Tools
| Tool | File | Purpose |
|------|------|---------|
| `printr_quote` | `quote.ts` | Get cost estimates for token creation |
| `printr_create_token` | `create-token.ts` | Generate unsigned token creation tx payload |
| `printr_launch_token` | `launch-token.ts` | Create and sign a token in one call |
| `printr_get_token` | `get-token.ts` | Look up token details by ID or address |
| `printr_get_deployments` | `get-deployments.ts` | Check deployment status across chains |
| `printr_get_balance` | `get-balance.ts` | Get native token balance |
| `printr_get_token_balance` | `get-token-balance.ts` | Get ERC-20 or SPL token balance |
| `printr_sign_and_submit_evm` | `sign-and-submit-evm.ts` | Sign and submit EVM transactions |
| `printr_sign_and_submit_svm` | `sign-and-submit-svm.ts` | Sign and submit Solana transactions |
| `printr_drain_deployment_wallet` | `drain-deployment-wallet.ts` | Return deployment funds to treasury |
Source: [packages/mcp/src/tools/get-token-balance.ts:1-30]()
## Blockchain Integration
### CAIP-10 Address Parsing
The system uses CAIP-10 (Blockchain-Agnostic Account Format) for address representation:
```
eip155:8453:0xYourAddress // EVM (Chain ID 8453 = Base)
solana:5gjMXXXXXXX // Solana
```
All tools validate addresses using the `parseCaip10` utility before processing. Source: [packages/mcp/src/tools/get-balance.ts:35-45]()
### Chain Metadata
Chain information is centralized through a `CHAIN_META` registry that maps CAIP-2 chain identifiers to RPC URLs, chain names, and configuration:
```typescript
const meta = getChainMeta(caip2);
if (!meta) {
return toolError(
`Unsupported chain: ${caip2}. Supported chains: ${Object.keys(CHAIN_META).join(", ")}`,
);
}
```
Source: [packages/mcp/src/tools/get-balance.ts:45-55]()
### Multi-Chain Support
The SDK supports querying balances across both EVM and SVM namespaces:
```typescript
const isSupportedNamespace = (namespace: string): boolean => {
return namespace === 'eip155' || namespace === 'solana';
};
```
Source: [packages/mcp/src/tools/get-balance.ts:55-60]()
## Dependency Architecture
### SDK Dependencies
The SDK has significant runtime dependencies to support its feature set:
| Package | Purpose | Size Impact |
|---------|---------|-------------|
| `@solana/web3.js` | Solana RPC interactions | ~600KB minified |
| `viem` | EVM RPC interactions | Large |
| `sharp` | Image processing | Node.js only |
| `neverthrow` | Error handling (Result types) | Runtime |
| `openapi-fetch` | REST client | Minimal |
| `@connectrpc/connect` | gRPC client | Minimal |
Source: [packages/sdk/package.json:25-45]()
### Current Limitations
Community issues highlight ongoing work to optimize the dependency footprint:
1. **Epic A: SDK Workers-ready (#103)** — The SDK currently does not run on Cloudflare Workers due to:
- Static imports of `sharp` and `node:fs` in `image.ts`
- `createRequire` shim for CommonJS interop
- Heavy dependencies like `@solana/web3.js` (~600KB)
2. **Lazy Loading (#96)** — Image processing should be lazy-loaded to avoid pulling Node-only dependencies into browser/edge consumers.
Source: [packages/sdk/package.json:1-60]()
## Workflow: Token Creation and Launch
```mermaid
sequenceDiagram
participant Agent as AI Agent
participant MCP as MCP Server
participant SDK as @printr/sdk
participant API as Printr API
participant Blockchain
Agent->>MCP: printr_quote(creator, chains)
MCP->>SDK: buildQuote(...)
SDK->>API: REST/gRPC
API-->>SDK: Quote response
SDK-->>MCP: Quote result
MCP-->>Agent: Cost breakdown
Agent->>MCP: printr_launch_token(params)
MCP->>SDK: buildToken(...)
SDK->>API: Create token
API-->>SDK: Unsigned transaction
SDK-->>MCP: Unsigned tx + session URL
MCP-->>Agent: Browser signing URL
Note over Agent: User signs in browser
Agent->>MCP: printr_sign_and_submit_evm(tx_payload)
MCP->>SDK: signAndSubmitEVM(...)
SDK->>Blockchain: Signed transaction
Blockchain-->>SDK: Transaction receipt
SDK-->>MCP: Tx hash + status
MCP-->>Agent: Confirmation
alt Deployment wallet drain
Agent->>MCP: printr_drain_deployment_wallet
MCP->>SDK: drainDeploymentWallet(...)
SDK->>Blockchain: Drain transaction
Blockchain-->>SDK: Drain receipt
SDK-->>MCP: Remaining balance
MCP-->>Agent: Drain status
end
```
Source: [packages/mcp/src/tools/launch-token.ts:1-50]()
## Data Models
### Token Contract Deployment
Generated from Protocol Buffers, representing deployment state across chains:
| Field | Type | Description |
|-------|------|-------------|
| `contract_address` | Account (CAIP) | Deployed contract address |
| `transaction_id` | string | On-chain transaction ID |
| `block_timestamp` | Timestamp | When deployed |
| `telecoin_initial_price` | PricedAsset | Initial pricing data |
| `telecoin_graduation_supply` | AssetAmountV1 | Supply at graduation |
| `telecoin_graduation_price` | PricedAsset | Price at graduation |
| `telecoin_max_supply` | AssetAmountV1 | Maximum supply |
Source: [packages/sdk/src/proto/api/api_pb.ts:100-150]()
### Drain Deployment Wallet Result
Return type for deployment wallet drainage operations:
| Field | Type | Description |
|-------|------|-------------|
| `amount` | string | Amount drained (lamports/wei) |
| `symbol` | string | Native token symbol |
| `from_address` | string | Deployment wallet address |
| `to_address` | string | Treasury wallet address |
| `tx_signature` | string? | Solana transaction signature |
| `tx_hash` | string? | EVM transaction hash |
| `remaining_balance` | string | Remaining balance |
| `wallet_id` | string | Keystore wallet ID |
Source: [packages/mcp/src/tools/drain-deployment-wallet.ts:1-30]()
## Signing Architecture
### Session-Based Signing
The system supports browser-based signing through session tokens:
```typescript
// Output includes browser signing flow
{
url: "https://app.printr.money/sign?session=...",
session_token: "ephemeral-session-token",
api_port: 3456,
expires_at: 1234567890,
}
```
### Private Key Signing
For automated agents, private keys can be supplied via environment variables:
```json
{
"env": {
"EVM_WALLET_PRIVATE_KEY": "",
"SVM_WALLET_PRIVATE_KEY": ""
}
}
```
Source: [README.md](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
## Environment Configuration
| Variable | Description | Default |
|----------|-------------|---------|
| `PRINTR_API_KEY` | Partner API key | Public AI-integration key |
| `PRINTR_API_BASE_URL` | API endpoint | `https://api-preview.printr.money` |
| `OPENROUTER_API_KEY` | Image generation | Not set (optional) |
| `OPENROUTER_IMAGE_MODEL` | Image model override | Not set |
| `EVM_WALLET_PRIVATE_KEY` | EVM signing key | Not set |
| `SVM_WALLET_PRIVATE_KEY` | Solana signing key | Not set |
Source: [README.md](https://github.com/PrintrFi/printr-mcp/blob/main/README.md)
## Planned Architecture Evolution
### Epic B: Shared SDK Primitives (#104)
Extract MCP-internal logic into shared SDK subpaths:
- Signer primitive moved to `@printr/sdk/signer`
- Fee-routing and quote-flow architecture centralized
### Epic C: Agent Trading UX (#105)
Add trading capabilities beyond launch:
- Swap operations
- Buy/sell by ticker
- Cross-chain bridge tools (Base ↔ Solana)
### Epic A: Workers-Ready SDK (#103)
Refactor to enable edge runtime execution:
- Lazy-load `sharp` and `node:fs`
- Remove `createRequire` shim
- Lightweight balance queries via direct JSON-RPC
Source: [packages/sdk/package.json:1-60]()
## Engine Requirements
| Package | Node.js | Bun | Edge/Workers |
|---------|---------|-----|--------------|
| `@printr/sdk` | ≥18 | Supported | Planned (#103) |
| `@printr/mcp` | ≥18 | Supported | Not planned |
Source: [packages/sdk/package.json:16-18]()
## Summary
The printr-mcp architecture provides a two-tier system where the `@printr/sdk` handles API and blockchain communication while `@printr/mcp` exposes these capabilities as MCP tools for AI agents. The system supports multi-chain token operations across EVM and SVM ecosystems, with ongoing work to optimize bundle size for edge runtimes and extend functionality to include trading and bridging operations.
---
## SDK Package (@printr/sdk)
### Related Pages
Related topics: [Token Operations](#token-operations), [Chain Support](#chain-support), [System Architecture](#architecture-overview)
Related Source Files
The following source files were used to generate this page:
- [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/sdk/src/client.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/client.ts)
- [packages/sdk/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/index.ts)
- [packages/sdk/src/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/env.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/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.ts)
# SDK Package (@printr/sdk)
`@printr/sdk` is the official TypeScript SDK for [Printr](https://printr.money), enabling developers to create and manage tokens across EVM chains (Base, Ethereum) and Solana from any JavaScript or TypeScript environment. Source: [packages/sdk/README.md]()
## Overview
The SDK provides a unified interface for token operations, abstracting over multiple blockchain ecosystems and providing:
- **Multi-chain token creation** — Deploy ERC-20 and SPL tokens on Base, Ethereum, and Solana
- **Balance and transfer operations** — Query native and SPL token balances, execute transfers
- **Wallet management** — Encrypted keystore with AES-256-GCM for deployment wallets
- **Image generation** — AI-powered token avatar creation via OpenRouter
- **Type-safe API client** — Full TypeScript support with Zod schema validation
Source: [packages/sdk/README.md:1-15]()
## Package Exports
The SDK uses subpath exports for tree-shaking and selective imports. Each subpath exports only the relevant types and functions, reducing bundle size for consumers.
Source: [packages/sdk/package.json:5-40]()
### Export Map
| Export Subpath | Types | Description |
|----------------|-------|-------------|
| `@printr/sdk` | Barrel | Full SDK with all features |
| `@printr/sdk/client` | `PrintrClient`, `ClientConfig` | API client for Printr backend |
| `@printr/sdk/chains` | Chain configs, RPC URLs | Chain-specific configuration |
| `@printr/sdk/evm` | EVM utilities | Ethereum/Virtual Machine helpers |
| `@printr/sdk/svm` | SVM utilities | Solana Virtual Machine helpers |
| `@printr/sdk/schemas` | Zod schemas | Request/response validation |
| `@printr/sdk/caip` | CAIP types | Chain-agnostic account identification |
| `@printr/sdk/balance` | Balance functions | Full balance queries (heavy) |
| `@printr/sdk/balance-lite` | Balance functions | Lightweight RPC-based balances |
| `@printr/sdk/transfer` | Transfer functions | Cross-chain token transfers |
| `@printr/sdk/openapi` | OpenAPI types | Types-only re-exports |
Source: [packages/sdk/package.json:5-40]()
## Architecture
```mermaid
graph TD
subgraph "Client Layer"
A[PrintrClient] --> B[Protocol Buffers]
A --> C[ConnectRPC]
end
subgraph "Chain Abstraction"
D[CAIP Identifiers] --> E[EVM Module]
D --> F[SVM Module]
end
subgraph "Features"
G[Token Creation] --> H[buildToken]
I[Balance Queries] --> J[balance-lite]
K[Image Processing] --> L[sharp]
end
subgraph "Environment"
M[getConfigs] --> N[mainnet / testnet / devnet]
end
A --> D
E --> G
F --> G
C --> B
```
### Client Architecture
The SDK uses ConnectRPC for efficient binary serialization alongside REST/JSON transport via OpenAPI. The `PrintrClient` is the central entry point for all API interactions.
Source: [packages/sdk/src/client.ts]()
### Chain Abstraction (CAIP)
The SDK uses [Chain Agnostic Improvement Proposals (CAIP)](https://github.com/ChainAgnostic/CAIPs) for chain identification, enabling consistent account and asset representation across ecosystems:
```typescript
// CAIP-10 account format
"eip155:8453:0xYourAddress" // Base on EVM
"solana:5xKmd6epXHzDqE3MipG6D3tTEPCynPwVvQb2J8xRDWq7" // Solana
```
Source: [packages/sdk/src/caip.ts]()
### Environment Configuration
Per-environment URLs are centralized via `getConfigs()`:
```typescript
type Environment = "mainnet" | "testnet" | "devnet";
export const getConfigs = memoize((env: Environment) => ({
apiBaseUrl: "...", // API endpoint
appUrl: "...", // Web app URL
rpcUrls: { ... }, // Chain RPC URLs
}));
```
Source: [packages/sdk/src/env.ts]()
## Core Features
### Token Creation
The `buildToken` function creates and returns a token creation transaction payload:
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: process.env.PRINTR_API_BASE_URL ?? 'https://api-preview.printr.money',
});
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,
);
```
Source: [packages/sdk/README.md:28-48]()
### Balance Queries
The SDK provides two balance query implementations:
| Module | Bundle Size | Use Case |
|--------|-------------|----------|
| `@printr/sdk/balance` | ~600KB+ | Full viem + @solana/web3.js support |
| `@printr/sdk/balance-lite` | Lightweight | Direct JSON-RPC, edge/Workers compatible |
The `balance-lite` variant was added to address bundle size concerns for edge runtimes:
> `packages/sdk/src/balance.ts` currently pulls `@solana/web3.js` (~600KB minified) and `viem` for balance queries. For consumers that only need to read native or SPL balances, this is a heavy tax — especially on edge/Workers runtimes with bundle size limits.
Source: [packages/sdk/package.json:27-30]()
Community issue: [feat(sdk): lighter balance via direct JSON-RPC #101](https://github.com/PrintrFi/printr-mcp/issues/101)
### Image Processing
Token avatar generation via OpenRouter AI models. The SDK includes image optimization using `sharp` for Node.js environments:
```typescript
// Process image from path (Node.js only)
const processed = await processImagePath('/path/to/image.png', options);
// Process raw bytes (browser/edge compatible)
const bytes = await processImageBytes(imageBytes, options);
```
Source: [packages/sdk/README.md]()
> **Note:** Image processing with `sharp` and `node:fs/promises` are lazily loaded to support Workers compatibility. Importing the main barrel does not automatically pull these Node.js-specific dependencies.
Community issue: [fix(sdk): lazy-load sharp + node:fs in image.ts #96](https://github.com/PrintrFi/printr-mcp/issues/96)
## Protocol Buffers
The SDK uses Protocol Buffers generated from `printrfi.api` namespace for efficient API communication:
```typescript
// Generated protobuf classes
class CreateTokenRequest extends Message { ... }
class TokenContractDeployment extends Message { ... }
class XchainMsg extends Message { ... }
```
Source: [packages/sdk/src/proto/api/api_pb.ts]()
### Key Proto Messages
| Message | Purpose |
|---------|---------|
| `CreateTokenRequest` | Token creation parameters |
| `TokenContractDeployment` | Deployment info per chain |
| `XchainMsg` | Cross-chain message tracking |
| `PricedAsset` | Asset with USD pricing |
Source: [packages/sdk/src/proto/api/api_pb.ts]()
## EVM Module (`@printr/sdk/evm`)
Utilities for Ethereum Virtual Machine chain interactions:
- Account derivation from private keys
- Transaction signing and submission
- Contract interactions via viem
- Gas estimation and management
Source: [packages/sdk/src/evm.ts]()
### RPC Configuration
EVM chains use Alchemy RPC templates with the `ALCHEMY_RPC_TEMPLATES` export:
```typescript
import { ALCHEMY_RPC_TEMPLATES, rpcUrlsSchema } from "@printr/sdk";
```
Source: [packages/sdk/src/env.ts:1]()
## SVM Module (`@printr/sdk/svm`)
Utilities for Solana Virtual Machine chain interactions:
- Keypair generation and derivation
- SPL token operations
- Transaction building and signing
- Solana-specific RPC management
Source: [packages/sdk/src/svm.ts]()
## Dependencies
### Runtime Dependencies
| Package | Purpose |
|---------|---------|
| `@bufbuild/protobuf` | Protocol Buffer runtime |
| `@connectrpc/connect` | RPC framework |
| `@connectrpc/connect-web` | Web transport |
| `@solana/web3.js` | Solana SDK (~600KB) |
| `viem` | Ethereum SDK (~400KB) |
| `sharp` | Image processing (lazy) |
| `openapi-fetch` | REST client |
| `zod` ~4.3.6 | Schema validation |
| `neverthrow` | Result/Either types |
| `bs58` | Base58 encoding |
Source: [packages/sdk/package.json:43-55]()
### Workers Compatibility
The SDK is being refactored for Cloudflare Workers compatibility. Current blockers include:
1. Static imports of `sharp` and `node:fs` in image processing
2. `createRequire` shim in CJS interop
3. Heavy web3 dependencies in balance queries
Community issue: [Epic A: SDK Workers-ready #103](https://github.com/PrintrFi/printr-mcp/issues/103)
## Configuration
### Required Environment Variables
| Variable | Description |
|----------|-------------|
| `PRINTR_API_KEY` | Partner API key for Printr backend |
| `PRINTR_API_BASE_URL` | API endpoint (defaults to preview) |
### Optional Environment Variables
| Variable | Description |
|----------|-------------|
| `OPENROUTER_API_KEY` | For AI image generation |
| `OPENROUTER_IMAGE_MODEL` | Image model override |
| `ALCHEMY_API_KEY` | For EVM RPC (if not using default) |
| `RPC_URLS` | Custom RPC endpoint overrides |
| `PRINTR_WALLET_STORE` | Encrypted wallet keystore path |
Source: [packages/sdk/src/env.ts]()
### Client Configuration
```typescript
interface ClientConfig {
apiKey: string;
baseUrl: string;
logger?: Logger;
timeout?: number;
}
```
## Installation
```bash
npm install @printr/sdk
# or
bun add @printr/sdk
# or
yarn add @printr/sdk
```
Source: [packages/sdk/README.md:20-26]()
## Version History
| Version | Date | Changes |
|---------|------|---------|
| v0.6.1 | 2026-05-18 | Pin zod to ~4.3.6 for MCP SDK 1.29 compat |
| v0.6.0 | - | Major release with balance-lite, Workers fixes |
Source: [packages/sdk/package.json:2]() and community context
## Related Packages
| Package | Relationship |
|---------|--------------|
| `@printr/mcp` | MCP server using this SDK for token tools |
| `@printr/cli` | CLI tool for MCP setup |
| `example-sdk-basic` | Usage examples |
Source: [examples/sdk-basic/package.json]() and root [package.json]()
## Future Roadmap
### Epic A: Workers-Ready SDK
Goal: `@printr/sdk` evaluates and runs cleanly on Cloudflare Workers without vendoring.
Sub-issues:
- Drop `createRequire` shim (#97)
- Lazy-load sharp + node:fs (#96)
- Lighter balance via direct JSON-RPC (#101)
- Types-only OpenAPI entry (#98)
Source: [Epic A: SDK Workers-ready #103](https://github.com/PrintrFi/printr-mcp/issues/103)
### Epic B: Shared SDK Primitives
Extract MCP-internal signing logic into `@printr/sdk/signer` for reuse across clients.
Source: [Epic B: Shared SDK primitives #104](https://github.com/PrintrFi/printr-mcp/issues/104)
### Epic C: Agent Trading UX
Add swap, buy, sell, and bridge primitives to the SDK for full trading workflow support.
Source: [Epic C: Agent trading UX #105](https://github.com/PrintrFi/printr-mcp/issues/105)
---
## MCP Server (@printr/mcp)
### Related Pages
Related topics: [Token Operations](#token-operations), [Wallet Management](#wallet-management), [CLI Package (@printr/cli)](#cli-package)
Related Source Files
The following source files were used to generate this page:
- [packages/mcp/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
- [packages/mcp/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/README.md)
- [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/quote.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/quote.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/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/lib/env.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/env.ts)
- [packages/mcp/src/lib/test-helpers.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/test-helpers.ts)
# MCP Server (@printr/mcp)
## Overview
`@printr/mcp` is the Model Context Protocol (MCP) server implementation for [Printr](https://printr.money). It enables AI agents to create, discover, and track tokens across EVM-compatible chains and Solana through a standardized MCP tool interface. Source: [packages/mcp/package.json:2-3]()
The package exposes tools for token deployment, balance queries, transfers, fee claiming, and transaction signing. No API key is required—agents can use the default public integration key or provide their own `PRINTR_API_KEY`. Source: [packages/mcp/README.md:9]()
## Architecture
### System Components
```mermaid
graph TD
subgraph "MCP Server (@printr/mcp)"
T[Tool Registry]
S[Server Core]
E[Environment Config]
L[Logging]
end
subgraph "Tools"
TC[Token Tools]
TX[Transaction Tools]
B[Balance Tools]
F[Fee Tools]
end
subgraph "SDK (@printr/sdk)"
API[PrintrClient]
SIG[Signer]
ENV[Configs]
end
subgraph "External Services"
P[Printr API]
OR[OpenRouter]
RPC[Blockchain RPCs]
end
T --> TC
T --> TX
T --> B
T --> F
S --> T
S --> E
S --> L
TX --> SIG
SIG --> RPC
TC --> API
API --> P
API --> OR
B --> RPC
```
### Tool Registration Flow
All MCP tools are registered at server startup using the `@modelcontextprotocol/sdk` pattern. Each tool follows a consistent registration structure:
```typescript
server.registerTool(
"tool_name",
{
description: "...",
inputSchema: zodSchema,
outputSchema: zodSchema,
},
logToolExecution("tool_name", async (params) => {
// Implementation with error handling
}),
);
```
Source: [packages/mcp/src/tools/quote.ts:28-40]()
## Available Tools
### Token Creation & Deployment
| Tool | Description |
|------|-------------|
| `printr_quote` | Get cost estimates for token creation across chains |
| `printr_create_token` | Build unsigned token creation transaction payloads |
| `printr_launch_token` | Create and sign a token in one call |
| `printr_get_token` | Look up token details by ID or address |
| `printr_get_deployments` | Check deployment status across target chains |
Source: [README.md:1-20]()
### Transaction Signing & Submission
| Tool | Description |
|------|-------------|
| `printr_sign_and_submit_evm` | Sign and submit an EVM transaction payload |
| `printr_sign_and_submit_svm` | Sign and submit a Solana transaction payload |
| `printr_open_web_signer` | Start a browser signing session (MetaMask / Phantom) |
Source: [README.md:9-13]()
### Balance & Transfer
| Tool | Description |
|------|-------------|
| `printr_get_balance` | Query native token balance for any CAIP-10 address |
| `printr_transfer` | Transfer native tokens between addresses |
| `printr_transfer_token` | Transfer SPL/ERC-20 tokens |
Source: [packages/mcp/src/tools/get-balance.ts:1](), [packages/mcp/src/tools/transfer.ts:1](), [packages/mcp/src/tools/transfer-token.ts:1]()
### Fees & Rewards
| Tool | Description |
|------|-------------|
| `printr_claim_fees` | Claim protocol fees for a deployed token |
Source: [packages/mcp/src/tools/claim-fees.ts:1]()
### Utility
| Tool | Description |
|------|-------------|
| `printr_generate_image` | Generate token avatar via OpenRouter |
Source: [README.md:14]()
## Tool Schemas
### printr_quote
Returns itemized costs per chain, total cost in USD, and token amounts from the initial buy. Source: [packages/mcp/src/tools/quote.ts:24-26]()
**Input Schema:**
```typescript
{
chains: caip2ChainId[]; // min 1 chain required
initial_buy: {
spend_amount?: string; // Native token amount to spend
spend_amount_usd?: string; // USD equivalent
supply_percentage?: number; // % of total supply (0-100)
};
graduation_threshold_per_chain_usd?: string;
}
```
**Output Schema:**
```typescript
{
quote: {
total_cost_usd: string;
total_cost_native: Record;
items: Array<{
chain: string;
cost_usd: string;
cost_native: string;
tokens_from_buy: string;
}>;
};
}
```
### printr_get_balance
Queries native token balance using direct JSON-RPC calls. Source: [packages/mcp/src/tools/get-balance.ts:16-17]()
**Input Schema:**
```typescript
{
account: string; // CAIP-10 address
rpc_url?: string; // Optional RPC override
}
```
**Output Schema:**
```typescript
{
account: string;
chain: string; // CAIP-2 chain ID
chain_name: string;
balance_atomic: string; // Wei/lamports
balance_formatted: string;
symbol: string;
decimals: number;
}
```
### printr_transfer
Transfers native tokens across EVM and SVM chains. Source: [packages/mcp/src/tools/transfer.ts:4-7]()
**Wallet Resolution Priority:**
1. `private_key` parameter provided inline
2. Active wallet session from `printr_open_web_signer`
3. `EVM_WALLET_PRIVATE_KEY` / `SVM_WALLET_PRIVATE_KEY` environment variables
Source: [packages/mcp/src/tools/transfer.ts:19-22]()
### printr_transfer_token
Transfers SPL tokens (Solana) or ERC-20 tokens (EVM). Source: [packages/mcp/src/tools/transfer-token.ts:1]()
### printr_claim_fees
Claims accumulated protocol fees for a token across supported chains. Source: [packages/mcp/src/tools/claim-fees.ts:5]()
**Input Schema:**
```typescript
{
token_id: string; // Telecoin ID (hex) or CAIP-10 address
chain: string; // CAIP-2 chain ID
}
```
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `PRINTR_API_KEY` | No | Partner API key (uses default public key if omitted) |
| `PRINTR_API_BASE_URL` | No | Printr API base URL |
| `OPENROUTER_API_KEY` | No | Enables image generation |
| `OPENROUTER_IMAGE_MODEL` | No | Image model override |
| `EVM_WALLET_PRIVATE_KEY` | No | Default EVM signing key |
| `SVM_WALLET_PRIVATE_KEY` | No | Default Solana signing key |
| `PRINTR_DEPLOYMENT_PASSWORD` | No | Master password for encrypting deployment wallet keys |
| `ALCHEMY_API_KEY` | No | RPC provider for EVM chains |
| `RPC_URLS` | No | Custom RPC endpoints per chain |
| `AGENT_MODE` | No | Enable autonomous signing |
Source: [packages/mcp/src/lib/env.ts:12-28]()
### Inherited SDK Configuration
The MCP server extends SDK environment configuration with RPC templates from Alchemy:
```typescript
import { ALCHEMY_RPC_TEMPLATES, rpcUrlsSchema, env as sdkEnv } from "@printr/sdk";
```
Source: [packages/mcp/src/lib/env.ts:2-3]()
## Supported Chains
### EVM Chains
The server supports all EVM-compatible chains via CAIP-2 namespace `eip155`. Common chains include Base, Ethereum Mainnet, and testnets. Source: [packages/mcp/src/tools/get-balance.ts:3-10]()
```typescript
const CHAIN_META: Record = {
"eip155:8453": { name: "Base", symbol: "ETH", decimals: 18 },
// ... additional chains
};
```
### SVM (Solana)
Solana support via CAIP-2 namespace `solana`. Source: [packages/mcp/src/tools/get-balance.ts:6-7]()
```typescript
const SOL_META: ChainMeta = {
name: "Solana",
symbol: "SOL",
decimals: 9,
};
```
## CAIP Addressing
The server uses CAIP-10 for account addresses and CAIP-2 for chain identifiers throughout:
| Format | Example |
|--------|---------|
| CAIP-10 (Account) | `eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f1bD37` |
| CAIP-2 (Chain) | `eip155:8453` or `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
Source: [packages/mcp/src/tools/get-balance.ts:16-18]()
## Signing Workflow
### EVM Transaction Flow
```mermaid
sequenceDiagram
Agent->>MCP: printr_sign_and_submit_evm(payload, private_key?)
MCP->>SDK: signAndSubmitEvm(payload, key)
SDK->>Wallet: Sign with private key
Wallet-->>SDK: Signed transaction
SDK->>RPC: eth_sendRawTransaction
RPC-->>SDK: tx_hash
SDK-->>MCP: { tx_hash, block_number, ... }
MCP-->>Agent: ToolResponse
```
### Solana Transaction Flow
Solana transactions support instruction-based payloads with optional address lookup tables: Source: [packages/mcp/src/tools/sign-and-submit-svm.ts:10-20]()
```typescript
{
ixs: SvmInstruction[]; // Required, min 1 instruction
lookup_table?: string; // Base58 address lookup table
mint_address: string; // Expected mint (CAIP-10)
}
```
## Logging
The MCP server uses structured logging controlled by the `VERBOSE` environment variable:
```typescript
const verbose = env.VERBOSE === "1" || env.VERBOSE === "true";
export function logResult(label: string, result: Record) {
if (!verbose) return;
const payload = result["structuredContent"] ?? result["content"];
console.log(`[${label}]`, result["isError"] ? "ERROR" : "OK", JSON.stringify(payload, null, 2));
}
```
Source: [packages/mcp/src/lib/test-helpers.ts:10-20]()
All tool executions are logged via `logToolExecution` wrapper which captures:
- Tool name
- Execution timestamp
- Result status (OK/ERROR)
- Structured payload
## Error Handling
Tools use `neverthrow`'s `Result` and `ResultAsync` types for error handling:
```typescript
import { err, ok, type Result } from "neverthrow";
function validateInputs(params): Result {
// Return err({ message: "..." }) on validation failure
// Return ok(parsedInput) on success
}
```
Source: [packages/mcp/src/tools/transfer.ts:10-16]()
## Usage
### Quick Start with npx
```json
{
"mcpServers": {
"printr": {
"command": "npx",
"args": ["-y", "@printr/mcp@latest"]
}
}
}
```
Source: [packages/mcp/README.md:10-18]()
### Local Development
```bash
# Clone and install
git clone https://github.com/PrintrFi/printr-mcp
cd printr-mcp
bun install
# Run MCP server directly
bun src/index.ts
# Or build and run
bun run build
bun run start
```
Source: [packages/mcp/README.md:1]()
### Build Output
| File | Purpose |
|------|---------|
| `dist/index.js` | Entry point (bin) |
| `dist/index.d.ts` | TypeScript declarations |
| `dist/**/*.js` | Compiled modules |
| `certs/` | TLS certificates for local HTTPS |
Source: [packages/mcp/package.json:14-17]()
## Testing
The MCP package includes test helpers for mocking the server and tools:
```typescript
export function createMockServer(): MockMcpServer {
// Returns server with registerTool and getRegisteredTool
}
```
Source: [packages/mcp/src/lib/test-helpers.ts:47-55]()
```bash
# Run tests
bun test src/
# Type check
bun run typecheck
```
Source: [packages/mcp/package.json:25]()
## Related Epic Work
Community issues indicate active development in several areas:
### Epic A: SDK Workers-Ready (#103)
Making `@printr/sdk` compatible with Cloudflare Workers and edge runtimes. Sub-issues include:
- Dropping `createRequire` shim (issue #97)
- Lazy-loading Node-only dependencies like `sharp` and `node:fs` (issue #96)
- Lighter balance queries without heavy web3.js bundle (issue #101)
### Epic B: Shared SDK Primitives (#104)
Extracting signer primitives from MCP into `@printr/sdk/signer` for reuse across clients (issue #100).
### Epic C: Agent Trading UX (#105)
Adding swap, buy, sell, and bridge capabilities—currently agents can only launch tokens (issues #62, #63).
## Dependencies
### Core Dependencies
| Package | Purpose |
|---------|---------|
| `@modelcontextprotocol/sdk` ^1.29.0 | MCP protocol implementation |
| `@printr/sdk` workspace:* | Printr API client |
| `zod` ~4.3.6 | Schema validation |
| `neverthrow` | Result/Either error handling |
| `ts-pattern` | Pattern matching |
Source: [packages/mcp/package.json:30-45]()
### Peer Dependencies
| Package | Requirement |
|---------|-------------|
| `@modelcontextprotocol/sdk` | ^1.29.0 (pinned for compatibility) |
Source: [packages/mcp/README.md:8](), [packages/mcp/README.md:10]()
## Package Metadata
| Property | Value |
|----------|-------|
| Version | 0.16.1 |
| Node.js | >=18 |
| License | Apache-2.0 |
| MCP Name | `io.github.PrintrFi/printr` |
| Type | ESM (`"type": "module"`) |
---
## CLI Package (@printr/cli)
### Related Pages
Related topics: [Introduction](#introduction), [Quick Start Guide](#quickstart)
Related Source Files
The following source files were used to generate this page:
- [packages/cli/src/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/index.ts)
- [packages/cli/src/commands/setup/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/setup/index.ts)
- [packages/cli/src/commands/skill/index.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/skill/index.ts)
- [packages/cli/src/commands/setup/components/summary.tsx](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/setup/components/summary.tsx)
- [packages/cli/src/commands/skill/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)
- [packages/cli/src/commands/skill/components/banner.tsx](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/skill/components/banner.tsx)
- [packages/cli/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/package.json)
- [packages/cli/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/README.md)
- [packages/cli/skills/printr/SKILL.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/skills/printr/SKILL.md)
# CLI Package (@printr/cli)
The `@printr/cli` is a command-line interface tool designed to configure Printr MCP for AI clients and install agent skills. Built with [Ink](https://github.com/vadimdemedes/ink) for interactive terminal interfaces, it enables developers to quickly set up multi-chain token creation capabilities across various AI agent platforms.
## Overview
The CLI serves as the primary setup and configuration utility for the Printr ecosystem. It abstracts the complexity of configuring Model Context Protocol (MCP) servers across different AI clients, providing a unified interface for:
- **MCP Server Configuration** — Detects and configures supported AI clients automatically
- **Skill Installation** — Installs Printr agent skills that enhance AI client capabilities
- **Interactive Terminal UI** — Beautiful, colorful terminal output built with React-compatible components
Source: [packages/cli/package.json:1-20]()
## Architecture
### Package Structure
```
@printr/cli
├── src/
│ ├── index.ts # CLI entry point
│ └── commands/
│ ├── setup/ # MCP server configuration
│ │ ├── index.ts
│ │ └── components/
│ │ ├── banner.tsx # Header display
│ │ └── summary.tsx # Completion summary
│ └── skill/ # Skill installation
│ ├── index.ts
│ └── components/
│ ├── banner.tsx # Header display
│ └── summary.tsx # Completion summary
└── skills/
└── printr/
└── SKILL.md # Agent skill definition
```
### Component Architecture
```mermaid
graph TD
A[CLI Entry Point] --> B[Command Router]
B --> C[setup Command]
B --> D[skill Command]
C --> E[Client Detector]
C --> F[Config Writer]
C --> G[Summary Component]
D --> H[Skill Copier]
D --> I[Summary Component]
E --> J[Claude Desktop]
E --> K[Cursor]
E --> L[Windsurf]
E --> M[Gemini]
E --> N[Claude Code]
F --> J
F --> K
F --> L
F --> M
F --> N
```
### Supported AI Clients
The CLI automatically detects and configures the following AI clients:
| Client | Config Location |
|--------|-----------------|
| Claude Desktop | `~/.config/claude-desktop/` |
| Cursor | `.cursor/` |
| Windsurf | `.windsurf/` |
| Gemini | Agent configuration |
| Claude Code | Project/local config |
Source: [packages/cli/src/commands/setup/lib/clients.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/src/commands/setup/lib/clients.ts)()
## Commands
### `printr setup`
Configures Printr MCP server for detected AI clients. This is the primary onboarding command.
#### Usage
```bash
# Configure all detected clients
printr setup
# Configure specific client only
printr setup --client claude-desktop
# Configure multiple clients
printr setup --client claude-desktop --client cursor
```
#### Options
| Option | Description |
|--------|-------------|
| `--client ` | Target specific AI client (can be used multiple times) |
#### Workflow
```mermaid
sequenceDiagram
participant User
participant CLI
participant FileSystem
User->>CLI: printr setup
CLI->>CLI: Detect installed clients
CLI->>FileSystem: Create MCP config
FileSystem-->>CLI: Config created
CLI->>CLI: Configure environment vars
CLI->>User: Display success summary
Note over User: Restart client to activate
```
#### Output Example
```
Printr MCP — launch tokens from any AI client
✓ Installed for 2 clients.
Restart your clients to activate, then try:
"Quote me the cost of creating a token on Base"
Docs: https://github.com/PrintrFi/printr-mcp
```
Source: [packages/cli/src/commands/setup/components/summary.tsx:1-30]()
### `printr skill`
Installs Printr agent skills to enhance AI client capabilities with domain-specific knowledge and tool usage patterns.
#### Usage
```bash
# Install skill to all detected agents
printr skill
# Install to specific agent
printr skill --client claude-desktop
```
#### Output Example
```
Printr MCP — Install Agent Skill
Installed printr skill to 2 agents.
```
Source: [packages/cli/src/commands/skill/components/summary.tsx:1-25]()
## Terminal UI Components
The CLI uses Ink for building interactive terminal interfaces with React-like components.
### Banner Component
Displays the CLI header with branding and tagline.
**Setup Banner:**
```tsx
// packages/cli/src/commands/setup/components/banner.tsx
{" Printr MCP "}
{"— launch tokens from any AI client"}
```
**Skill Banner:**
```tsx
// packages/cli/src/commands/skill/components/banner.tsx
Printr MCP — Install Agent Skill
```
### Summary Component
Displays command completion status with contextual messaging.
```tsx
// Conditional output based on result count
if (configured === 0) {
// Display "Nothing to configure" message
} else {
// Display success with client count
}
```
Source: [packages/cli/src/commands/setup/components/summary.tsx:1-40]()
## Environment Variables
The MCP server requires certain environment variables for full functionality:
| Variable | Description | Required |
|----------|-------------|----------|
| `PRINTR_API_KEY` | Partner API key | Recommended |
| `OPENROUTER_API_KEY` | Enables image generation | Optional |
| `OPENROUTER_IMAGE_MODEL` | Image model override | Optional |
| `EVM_WALLET_PRIVATE_KEY` | Default EVM signer | Optional |
| `SVM_WALLET_PRIVATE_KEY` | Default Solana signer | Optional |
Source: [packages/mcp/src/lib/env.ts:1-35]()
## Installation
### Global Installation (Recommended)
```bash
npm install -g @printr/cli
bun add -g @printr/cli
yarn global add @printr/cli
```
### Run Without Installing
```bash
npx @printr/cli setup
bunx @printr/cli setup
```
### From Source
```bash
# Clone repository
git clone https://github.com/PrintrFi/printr-mcp.git
cd printr-mcp
# Install dependencies
bun install
# Build packages
bun run build
# Run CLI
bun run --cwd packages/cli dev
```
Source: [packages/cli/README.md:1-60]()
## Package Configuration
### Package Metadata
```json
{
"name": "@printr/cli",
"version": "0.3.2",
"type": "module",
"bin": {
"printr": "./dist/index.js"
},
"engines": {
"node": ">=18"
}
}
```
### Build Scripts
| Script | Purpose |
|--------|---------|
| `build` | Compiles TypeScript to JavaScript |
| `dev` | Watch mode for development |
| `start` | Run compiled CLI |
| `typecheck` | TypeScript type validation |
Source: [packages/cli/package.json:1-50]()
## Agent Skills
The CLI installs the Printr skill definition to AI clients, providing:
### Available Tools
| Tool | Description |
|------|-------------|
| `printr_quote` | Get cost estimates for token creation |
| `printr_create_token` | Generate unsigned token creation transaction |
| `printr_launch_token` | Create and sign a token in one call |
| `printr_get_token` | Look up token details by ID or address |
| `printr_get_deployments` | Check deployment status across chains |
| `printr_sign_and_submit_evm` | Sign and submit EVM transactions |
| `printr_sign_and_submit_svm` | Sign and submit Solana transactions |
| `printr_open_web_signer` | Start browser signing session |
| `printr_generate_image` | Generate token avatar via OpenRouter |
Source: [packages/cli/skills/printr/SKILL.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/cli/skills/printr/SKILL.md)()
### Skill Features
- **Token Creation** — Launch tokens on Base, Ethereum, Solana, and more
- **Transaction Signing** — Browser-based wallet integration (MetaMask, Phantom)
- **Balance Queries** — Native and SPL token balance checks
- **Transfer Support** — Move tokens across addresses
- **Fee Estimation** — Get cost estimates before transactions
- **Staking Operations** — Stake and unstake tokens
## Integration with MCP Server
The CLI configures AI clients to use `@printr/mcp` as an MCP server:
```json
{
"mcpServers": {
"printr": {
"command": "npx",
"args": ["-y", "@printr/mcp", "start"]
}
}
}
```
This enables AI agents to call Printr tools through the MCP protocol, providing natural language interfaces to token operations.
## Troubleshooting
### Client Not Detected
Ensure the AI client is properly installed and has been run at least once to initialize its configuration directory.
### Configuration Write Failure
Check write permissions to the client's configuration directory. Some setups may require admin privileges.
### Skill Not Active After Installation
Restart the AI client completely. Some clients cache their skill definitions and require a full restart to pick up new installations.
## Related Documentation
- [SDK Package Documentation](@printr/sdk) — TypeScript SDK for Printr API
- [MCP Server Documentation](@printr/mcp) — Model Context Protocol server implementation
- [Repository README](https://github.com/PrintrFi/printr-mcp) — Project overview
---
## Token Operations
### Related Pages
Related topics: [SDK Package (@printr/sdk)](#sdk-package), [Wallet Management](#wallet-management), [Chain Support](#chain-support)
Related Source Files
The following source files were used to generate this page:
- [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/sdk/src/token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/token.ts)
- [packages/sdk/src/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.ts)
- [packages/sdk/src/proto/api/payload_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/payload_pb.ts)
# Token Operations
Token Operations encompass the full lifecycle of creating, launching, and managing cross-chain tokens through the Printr MCP server and SDK. The system supports EVM chains (Base, Ethereum, BNB, AVAX) and Solana, enabling agents to create tokens with configurable parameters, track deployment status, and manage treasury operations.
## Overview
The Token Operations system is built on two primary layers:
| Layer | Package | Purpose |
|-------|---------|---------|
| MCP Tools | `@printr/mcp` | AI agent-facing tools exposed via Model Context Protocol |
| SDK | `@printr/sdk` | TypeScript library for programmatic token operations |
Token operations follow a workflow pattern: quote → create → launch → track → manage. Each operation is designed for composability, allowing agents to either execute a complete token launch in one call or handle individual steps manually.
Source: [packages/sdk/src/token.ts:1-50]()
## Token Creation Workflow
The token creation workflow consists of sequential operations that transform token parameters into deployed contracts across target chains.
```mermaid
graph TD
A[Agent requests quote] --> B[printr_quote]
B --> C[Returns cost estimate]
C --> D[Agent confirms parameters]
D --> E[printr_create_token]
E --> F[Returns unsigned tx payload]
F --> G[Agent signs locally or via browser]
G --> H[printr_launch_token]
H --> I[Tx submitted to chain]
I --> J[Track via printr_get_deployments]
J --> K[Token live on target chains]
```
### Step 1: Get Cost Quote
The `printr_quote` tool provides cost estimates before committing to token creation. It accepts token parameters and returns a breakdown of expected costs in USD and native tokens.
**Input Schema:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Token name (e.g., "My Token") |
| `symbol` | string | Yes | Token symbol (e.g., "TKN") |
| `chains` | string[] | Yes | Target chain CAIP-2 IDs |
| `initial_buy` | object | Yes | Initial buy configuration |
| `initial_buy.spend_usd` | number | No | USD amount to spend |
| `initial_buy.spend_native` | string | No | Native token amount (atomic units) |
| `initial_buy.supply_percent` | number | No | Percentage of total supply |
| `creator_accounts` | string[] | No | Creator addresses per chain |
| `graduation_threshold_per_chain_usd` | number | No | Threshold for graduation (default: 50000) |
**Output Schema:**
| Field | Type | Description |
|-------|------|-------------|
| `quote_id` | string | Unique quote identifier |
| `total_cost_usd` | number | Total estimated cost in USD |
| `cost_breakdown` | object | Per-chain cost breakdown |
| `expires_at` | number | Quote expiry timestamp |
Source: [packages/mcp/src/tools/quote.ts:1-80]()
### Step 2: Create Token Payload
The `printr_create_token` tool generates an unsigned transaction payload. The payload must be signed by the creator before submission.
**Key Input Parameters:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `creator_accounts` | string[] | Yes | Creator addresses as CAIP-10 (e.g., `eip155:8453:0x...`) |
| `name` | string | Yes | Token name |
| `symbol` | string | Yes | Token symbol (max 8 chars recommended) |
| `description` | string | No | Token description |
| `image` | string | No | Base64-encoded image or URL |
| `chains` | string[] | Yes | Target chain IDs |
| `initial_buy` | object | Yes | Initial buy configuration |
| `graduation_threshold_per_chain_usd` | number | No | Graduation threshold per chain |
The `initial_buy` object supports three modes:
| Mode | Field | Example |
|------|-------|---------|
| USD spend | `spend_usd` | `100` (spend $100) |
| Native spend | `spend_native` | `"1000000000000000000"` (1 ETH) |
| Supply percent | `supply_percent` | `10` (buy 10% of supply) |
Source: [packages/mcp/src/tools/create-token.ts:1-100]()
### Step 3: Launch Token
The `printr_launch_token` tool combines creation and submission in one call when the creator provides their private key. Without a private key, it returns a signing URL for browser-based signing.
**Output Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `token_id` | string | Cross-chain telecoin ID (hex) |
| `quote` | object | Full cost breakdown |
| `url` | string | Browser signing deep link (if not signed) |
| `session_token` | string | Ephemeral session token |
| `tx_hash` | string | EVM transaction hash |
| `signature` | string | Solana transaction signature |
| `drain_status` | enum | `ok`, `failed`, or `skipped` |
**Signing Options:**
1. **Browser signing** (default): Returns a URL to open in MetaMask/Phantom
2. **Private key** (via env vars): `EVM_WALLET_PRIVATE_KEY` or `SVM_WALLET_PRIVATE_KEY`
3. **Direct submission**: When unsigned tx is pre-signed
Source: [packages/mcp/src/tools/launch-token.ts:1-150]()
## Token Lookup
### Get Token by ID or Address
The `printr_get_token` tool retrieves token details by telecoin ID or contract address.
**Input Schema:**
```typescript
{
token_id?: string; // Telecoin ID (hex)
address?: string; // Contract address (CAIP-10)
chain_id?: string; // Filter by chain
}
```
**Output Schema:**
| Field | Type | Description |
|-------|------|-------------|
| `token_id` | string | Unique telecoin identifier |
| `name` | string | Token name |
| `symbol` | string | Token symbol |
| `description` | string | Token description |
| `image` | string | Token image URL |
| `chains` | string[] | Deployed chain IDs |
| `home_chain` | string | Home chain CAIP-2 ID |
| `deployments` | Deployment[] | Per-chain deployment info |
**Token Deployment Info:**
Each deployment contains:
| Field | Type | Description |
|-------|------|-------------|
| `contract_address` | string | Contract address on chain |
| `transaction_id` | string | Deployment transaction |
| `block_timestamp` | timestamp | Block confirmation time |
| `telecoin_initial_price` | object | Initial price (priced asset) |
| `telecoin_graduation_supply` | object | Graduation supply amount |
| `telecoin_max_supply` | object | Maximum supply |
| `quote_reserve_at_graduation` | object | Liquidity reserve at graduation |
Source: [packages/mcp/src/tools/get-token.ts:1-60]()
Source: [packages/sdk/src/proto/api/api_pb.ts:100-200]()
## Deployment Tracking
### Get Deployment Status
The `printr_get_deployments` tool monitors token deployment progress across all target chains.
**Input Schema:**
```typescript
{
token_id?: string; // Telecoin ID
creator_address?: string; // Filter by creator
chains?: string[]; // Filter by chains
page_number?: number; // Pagination
page_size?: number; // Results per page
has_deployments?: boolean; // Only tokens with deployments
has_liquidity_deployed?: boolean; // Only tokens with liquidity
}
```
**Output Schema:**
| Field | Type | Description |
|-------|------|-------------|
| `deployments` | Deployment[] | Array of deployment records |
| `total_count` | number | Total matching deployments |
| `page_info` | object | Pagination metadata |
**Deployment States:**
```mermaid
stateDiagram-v2
[*] --> Created: Token registered
Created --> Pending: Tx submitted
Pending --> Confirmed: Block confirmed
Confirmed --> Finalized: Finality reached
Pending --> Failed: Tx reverted
Failed --> [*]
Finalized --> [*]
```
Source: [packages/mcp/src/tools/get-deployments.ts:1-80]()
## SDK Token Interface
The `@printr/sdk` package exposes token operations through the `buildToken` function and related utilities.
### buildToken Function
```typescript
import { createPrintrClient, buildToken } from '@printr/sdk';
const client = createPrintrClient({
apiKey: process.env.PRINTR_API_KEY!,
baseUrl: 'https://api-preview.printr.money',
});
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,
);
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `input` | `BuildTokenInput` | Token configuration |
| `client` | `PrintrClient` | API client instance |
| `signal` | `AbortSignal` | Cancellation signal |
**Return Type:** `ResultAsync`
Source: [packages/sdk/src/token.ts:50-150]()
### Proto Message Types
The SDK uses Protocol Buffers for API communication. Key message types for token operations:
| Message Type | File | Purpose |
|--------------|------|---------|
| `CreateRequest` | api_pb.ts | Token creation request |
| `TokenInfo` | api_pb.ts | Token metadata |
| `TokenContractDeployment` | api_pb.ts | Per-chain deployment |
| `SpendRequest` | api_pb.ts | Spend/buy operations |
| `AccountMeta` | payload_pb.ts | Transaction account metadata |
**CAIP-10 Address Format:**
The system uses CAIP-10 for cross-chain address representation:
```
{namespace}:{chain_id}:{address}
```
Examples:
- EVM: `eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f1eB67`
- Solana: `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV`
Source: [packages/sdk/src/proto/api/api_pb.ts:200-350]()
Source: [packages/sdk/src/proto/api/payload_pb.ts:1-80]()
## Chain Support
Token operations support the following chains:
| Chain | Namespace | Chain ID | Native Token |
|-------|-----------|----------|--------------|
| Base | eip155 | 8453 | ETH |
| Ethereum | eip155 | 1 | ETH |
| Solana | solana | varies | SOL |
| BNB Chain | eip155 | 56 | BNB |
| Avalanche | eip155 | 43114 | AVAX |
### CAIP-2 Chain Identifiers
| Environment | Base URL |
|-------------|----------|
| Mainnet | `api.printr.money` |
| Preview | `api-preview.printr.money` |
## Environment Configuration
### Required Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `PRINTR_API_KEY` | Partner API key | Yes |
| `OPENROUTER_API_KEY` | For auto image generation | No |
### Optional Signing Variables
| Variable | Description | Use Case |
|----------|-------------|----------|
| `EVM_WALLET_PRIVATE_KEY` | Hex private key | EVM chain signing |
| `SVM_WALLET_PRIVATE_KEY` | Base58 keypair secret | Solana signing |
Source: [README.md:1-100]()
## Error Handling
Token operations use the `neverthrow` library for explicit error handling with `Result` and `ResultAsync` types.
```typescript
import { ResultAsync, ok, err } from 'neverthrow';
const result = await buildToken(input, client);
if (result.isOk()) {
console.log('Token created:', result.value.token_id);
} else {
console.error('Error:', result.error.message);
}
```
**Common Error Scenarios:**
| Error Type | Cause | Resolution |
|------------|-------|------------|
| `InsufficientBalance` | Not enough native tokens for gas | Fund wallet |
| `QuoteExpired` | Quote timestamp exceeded | Request new quote |
| `ChainUnsupported` | Chain not in supported list | Use supported chain |
| `InvalidAddress` | Malformed CAIP-10 address | Fix address format |
## Roadmap: Trading Operations
Future enhancements (see Epic C: Agent Trading UX) will add:
| Feature | Description | Issue |
|---------|-------------|-------|
| Swap | Exchange tokens via DEX | #62 |
| Buy/Sell | Trade by ticker symbol | #62 |
| Bridge | Cross-chain transfers (Base ↔ Solana) | #63 |
These operations will leverage the signer primitive extracted to `@printr/sdk/signer` as part of Epic B.
Source: [Community Context - Epic C #105]()
Source: [Community Context - Epic B #104]()
## See Also
- [SDK Documentation](packages/sdk/README.md)
- [CLI Setup](packages/cli/skills/printr/SKILL.md)
- [Balance Operations](packages/sdk/src/balance.ts)
- [Transfer Operations](packages/sdk/src/transfer.ts)
---
## Wallet Management
### Related Pages
Related topics: [MCP Server (@printr/mcp)](#mcp-server), [Chain Support](#chain-support)
Related Source Files
The following source files were used to generate this page:
- [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/wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/wallet.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/wallet-elicit.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/wallet-elicit.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/tools/fund-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/fund-deployment-wallet.ts)
- [packages/sdk/src/keystore.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/keystore.ts)
# Wallet Management
The printr-mcp system implements a comprehensive wallet management architecture that supports multi-chain operations across EVM (Ethereum Virtual Machine) and SVM (Solana Virtual Machine) chains. The wallet management layer provides secure key storage, signing session orchestration, deployment wallet lifecycle management, and balance-aware transaction submission.
## Architecture Overview
Wallet management in printr-mcp spans two packages: the `@printr/sdk` package provides core cryptographic operations and keystore functionality, while the `@printr/mcp` package orchestrates signing sessions, wallet resolution, and deployment wallet funding/draining operations.
```mermaid
graph TD
subgraph "SDK Layer"
KS[Keystore Module
keystore.ts]
NW[Network Utilities]
BC[Balance Checking]
end
subgraph "MCP Layer"
WS[Wallet Sessions
wallet-sessions.ts]
SS[Signing Sessions
sessions.ts]
WE[Wallet Elicit
wallet-elicit.ts]
Tools[MCP Tools]
end
subgraph "Signing Mechanisms"
EVM[EVM Signing
sign-and-submit-evm.ts]
SVM[SVM Signing
sign-and-submit-svm.ts]
Browser[Browser Signing
open-web-signer.ts]
end
KS --> WS
BC --> WE
NW --> WE
WE --> Tools
Tools --> SS
SS --> EVM
SS --> SVM
SS --> Browser
```
## Keystore Module
The SDK's keystore module provides encrypted storage for wallet private keys using AES-256-GCM encryption with scrypt key derivation. Source: [packages/sdk/src/keystore.ts:1-50]()
### Core Functions
| Function | Purpose |
|----------|---------|
| `encryptKey` | Encrypt a private key using a master password |
| `addWallet` | Persist a wallet entry to `~/.printr/wallets.json` |
| `listWallets` | List all stored wallets (addresses safe to read, keys encrypted) |
| `getWallet` | Retrieve a specific wallet by ID |
| `removeWallet` | Delete a wallet from the keystore |
### WalletEntry Data Model
```typescript
interface WalletEntry {
id: string; // UUID for wallet identification
label: string; // Human-readable label
chain: string; // CAIP-2 chain identifier (e.g., "eip155:8453")
address: string; // Public wallet address (safe to store in plaintext)
encryptedKey: string; // AES-256-GCM encrypted private key
iv: string; // Initialization vector for decryption
salt: string; // Scrypt salt for key derivation
createdAt: number; // Unix timestamp of creation
}
```
### Usage Example
```typescript
import { encryptKey, addWallet, listWallets, type WalletEntry } from '@printr/sdk/keystore';
import { randomUUID } from 'node:crypto';
// Encrypt a private key and build a WalletEntry
const password = process.env.PRINTR_DEPLOYMENT_PASSWORD!;
const encrypted = encryptKey('0x...', password);
const entry: WalletEntry = {
id: randomUUID(),
label: 'my-evm-wallet',
chain: 'eip155:8453',
address: '0xYourAddress',
...encrypted,
createdAt: Date.now(),
};
// Persist to ~/.printr/wallets.json
addWallet(entry);
// List all stored wallets
const wallets = listWallets();
```
## Wallet Sessions
The MCP server maintains active wallet sessions that track the currently selected wallet for operations. Source: [packages/mcp/src/server/wallet-sessions.ts:1-30]()
### Session State Management
```mermaid
stateDiagram-v2
[*] --> NoWallet: Initial State
NoWallet --> ActiveWallet: resolveWallet succeeds
ActiveWallet --> NoWallet: clearActiveWalletId()
ActiveWallet --> ActiveWallet: resolveWallet called again
[*] --> NoDeploymentWallet: No active deployment
NoDeploymentWallet --> DeploymentWalletActive: fundDeploymentWallet succeeds
DeploymentWalletActive --> NoDeploymentWallet: drainDeploymentWallet succeeds
DeploymentWalletActive --> NoDeploymentWallet: Error during drain
```
### ActiveWallet Interface
```typescript
export interface ActiveWallet {
id: string; // Wallet ID from keystore
address: string; // Derived public address
chain: ChainType; // 'evm' | 'svm'
privateKey: string; // Decrypted private key
}
```
### Environment Variables for Wallets
| Variable | Description |
|----------|-------------|
| `EVM_WALLET_PRIVATE_KEY` | Default EVM private key for signing |
| `SVM_WALLET_PRIVATE_KEY` | Default Solana keypair secret for signing |
| `PRINTR_DEPLOYMENT_PASSWORD` | Master password for encrypted keystore (min 16 chars) |
## Wallet Elicit
The `wallet-elicit.ts` module handles wallet resolution with balance checking. It ensures that a wallet has sufficient funds before attempting transactions. Source: [packages/mcp/src/lib/wallet-elicit.ts:1-60]()
### WalletResolution Result Types
```typescript
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 };
```
### TxContext for Balance Checks
```typescript
export type TxContext =
| { type: "evm"; caip10To: string; gasLimit: number; rpcUrl?: string }
| { type: "svm"; rpcUrl?: string };
```
### Chain Support
The system supports CAIP-2 chain identifiers for multi-chain operations:
| Chain | CAIP-2 ID | Chain Type |
|-------|-----------|------------|
| Ethereum | `eip155:1` | EVM |
| Base | `eip155:8453` | EVM |
| BNB Smart Chain | `eip155:56` | EVM |
| Solana | `solana:...` | SVM |
## Signing Mechanisms
### EVM Transaction Signing
The `sign-and-submit-evm.ts` tool handles Ethereum-compatible transaction signing. Source: [packages/mcp/src/tools/sign-and-submit-evm.ts:1-80]()
**Tool Input Schema:**
- `chain`: CAIP-2 chain identifier
- `to`: Recipient address
- `data`: Optional calldata (hex encoded)
- `value`: Optional native token value to send (in wei)
- `gas_limit`: Optional gas limit override
- `wallet_id`: Optional keystore wallet ID to use
**Tool Output Schema:**
- `tx_hash`: EVM transaction hash
- `block_number`: Block number where transaction was included
- `tx_status`: "success" or "reverted"
- `effective_gas_price`: Actual gas price paid
- `effective_gas_tip`: Actual gas tip (for EIP-1559)
### SVM Transaction Signing
The `sign-and-submit-svm.ts` tool handles Solana transaction signing. Source: [packages/mcp/src/tools/sign-and-submit-svm.ts:1-80]()
**Tool Input Schema:**
- `chain`: CAIP-2 chain identifier for Solana
- `wallet_id`: Optional keystore wallet ID to use
- `recent_blockhash`: Recent blockhash for transaction validity
- `instructions`: Array of compiled instructions
**Tool Output Schema:**
- `signature`: Base58 encoded transaction signature
- `slot`: Slot the transaction was confirmed in
- `confirmation_status`: "finalized", "confirmed", or "processed"
### Browser-Based Signing
The `open-web-signer.ts` tool initiates a browser signing session for wallet connections like MetaMask or Phantom. Source: [packages/mcp/src/tools/open-web-signer.ts:1-60]()
**Session Flow:**
1. Agent calls `printr_open_web_signer` tool
2. Server generates ephemeral session token and deep link URL
3. User approves signing in browser
4. Server receives callback with signed payload
5. Transaction is submitted to network
**Tool Output Schema:**
- `url`: Deep link to Printr web app signing page
- `session_token`: Ephemeral session token
- `api_port`: Local session API port
- `expires_at`: Session expiry timestamp (epoch ms)
## Deployment Wallet Lifecycle
Deployment wallets are temporary wallets used during token creation operations. They receive funds, pay for deployment gas/fees, and are then drained back to the treasury.
### Funding Deployment Wallet
The `fund-deployment-wallet.ts` tool transfers funds from the treasury to a deployment wallet. Source: [packages/mcp/src/tools/fund-deployment-wallet.ts:1-40]()
```mermaid
graph LR
A[Treasury Wallet] -->|transfer| B[Deployment Wallet]
B -->|deploy token| C[Token Contracts]
C -->|drain| A
```
**Tool Input Schema:**
- `chain`: CAIP-2 chain identifier
- `amount`: Amount to fund (in atomic units)
- `deployment_wallet_id`: Target deployment wallet ID
**Tool Output Schema:**
- `funded_amount`: Amount transferred
- `deployment_wallet_id`: Wallet that received funds
- `tx_hash` / `tx_signature`: Transaction proof
- `deployment_wallet_address`: Address that was funded
### Draining Deployment Wallet
The `drain-deployment-wallet.ts` tool returns unused funds from a deployment wallet to the treasury. Source: [packages/mcp/src/tools/drain-deployment-wallet.ts:1-100]()
**Tool Input Schema:**
- `chain`: CAIP-2 chain identifier
- `deployment_wallet_id`: Wallet to drain (optional, defaults to last active)
- `drain_to_address`: Custom destination address (optional)
**Tool Output Schema:**
- `drained_amount`: Amount returned to treasury
- `drain_fee`: Fee deducted for drain operation
- `drained_amount_minus_fee`: Net amount received
- `drained_symbol`: Native token symbol
- `from_address`: Deployment wallet address
- `to_address`: Treasury wallet address
- `tx_signature` / `tx_hash`: Transaction proof
- `drain_status`: "ok", "failed", or "skipped"
### DrainResult Data Model
```typescript
interface DrainResult {
drained_amount: string; // Formatted amount drained
drain_fee: string; // Fee charged for drain
drained_amount_minus_fee: string; // Net amount after fee
drained_atomic: string; // Atomic units drained
drain_fee_atomic: string; // Atomic units of fee
drained_symbol: string; // Native token symbol
from_address: string; // Deployment wallet
to_address: string; // Treasury address
tx_signature?: string; // Solana tx signature
tx_hash?: string; // EVM tx hash
remaining_balance: string; // Balance left in deployment wallet
wallet_id: string; // Wallet ID drained
}
```
## MCP Wallet Tools
The MCP package exposes wallet management as tools that agents can invoke. Source: [packages/mcp/src/tools/wallet.ts:1-100]()
### Available Wallet Tools
| Tool | Description |
|------|-------------|
| `printr_open_web_signer` | Start a browser signing session |
| `printr_sign_and_submit_evm` | Sign and submit an EVM transaction |
| `printr_sign_and_submit_svm` | Sign and submit a Solana transaction |
| `printr_fund_deployment_wallet` | Fund a deployment wallet from treasury |
| `printr_drain_deployment_wallet` | Return unused funds to treasury |
| `printr_get_deployment_wallet_address` | Get the active deployment wallet address |
### Environment Variables
| Variable | Description |
|----------|-------------|
| `PRINTR_API_KEY` | Partner API key |
| `EVM_WALLET_PRIVATE_KEY` | Default EVM private key |
| `SVM_WALLET_PRIVATE_KEY` | Default Solana keypair |
| `PRINTR_DEPLOYMENT_PASSWORD` | Master password for keystore |
## Future Considerations
### Epic B: Shared SDK Primitives
Issue #104 tracks the effort to lift wallet signing primitives from MCP into the SDK as a reusable `@printr/sdk/signer` subpath. This would allow other Printr clients to share the same signing session machinery. Source: [Epic B: Shared SDK primitives](https://github.com/PrintrFi/printr-mcp/issues/104)
### Epic C: Agent Trading UX
Issue #105 covers extending wallet management to support trading operations (swap, buy, sell, bridge) using the signer primitive from Epic B. Source: [Epic C: Agent trading UX](https://github.com/PrintrFi/printr-mcp/issues/105)
### Privy Agentic Wallet Support
Issue #7 requests integration with Privy agentic wallets for server-side wallet management, complementing the existing client-side React SDK usage. Source: [feat: Privy agentic wallet support](https://github.com/PrintrFi/printr-mcp/issues/7)
---
## Chain Support
### Related Pages
Related topics: [SDK Package (@printr/sdk)](#sdk-package), [Wallet Management](#wallet-management)
Related Source Files
The following source files were used to generate this page:
- [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/sdk/src/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.ts)
- [packages/mcp/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/README.md)
- [packages/mcp/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/package.json)
- [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/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
# Chain Support
The Printr SDK and MCP server provide comprehensive multi-chain support for token creation and management across EVM (Ethereum Virtual Machine) compatible chains and Solana (SVM). This documentation describes how the system abstracts chain differences, exposes chain-specific functionality through typed interfaces, and enables agents to operate seamlessly across supported networks.
## Overview
The `@printr/sdk` package implements a dual-chain architecture that separates EVM and SVM concerns while sharing common utilities. Chain identification uses the [CAIP-10](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIP-10.md) format for address-agnostic account representation across chains.
**Key characteristics:**
- Token creation and deployment across multiple chains in a single workflow
- Unified CAIP-10 address format (`eip155:8453:0xAddress` for EVM, `solana:5rJya:pubkey` for Solana)
- Chain-specific RPC URL configuration per environment
- Balance queries for both native tokens and SPL/ERC-20 tokens
- Cross-chain deployment wallet management (fund and drain operations)
Source: [packages/sdk/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/README.md)
## Architecture
The chain support system consists of three primary modules exposed through SDK subpath exports:
```mermaid
graph TD
subgraph "@printr/sdk"
A["./chains"] --> B[Shared chain utilities]
A --> C[CAIP address parsing]
C --> D["./evm"]
C --> E["./svm"]
F["./balance"] --> G[viem + @solana/web3.js]
H["./transfer"] --> D
H --> E
end
subgraph "@printr/mcp"
I[launch-token tool]
I --> A
J[get-balance tool] --> F
K[drain-deployment-wallet tool] --> D
K --> E
end
```
### SDK Export Structure
The SDK exposes chain-related functionality through typed subpath exports:
| Export Path | Purpose |
|-------------|---------|
| `@printr/sdk/chains` | Shared chain metadata, CAIP utilities, supported chain lists |
| `@printr/sdk/evm` | EVM-specific RPC clients, transaction signing, chain configs |
| `@printr/sdk/svm` | Solana RPC connections, transaction building, keypairs |
| `@printr/sdk/balance` | Native and token balance queries across chains |
| `@printr/sdk/transfer` | Token transfer operations |
Source: [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
## Supported Chains
The Printr system currently supports token operations on the following chains:
### EVM Chains
| Chain | Namespace | Chain ID | Native Token | Decimals |
|-------|-----------|----------|--------------|----------|
| Base | `eip155` | 8453 | ETH | 18 |
| Ethereum Mainnet | `eip155` | 1 | ETH | 18 |
| Testnet variants | `eip155` | varies | Test ETH | 18 |
### SVM Chains
| Chain | Namespace | Program ID | Native Token | Decimals |
|-------|-----------|------------|--------------|----------|
| Solana Mainnet | `solana` | 5rJya | SOL | 9 |
| Devnet | `solana` | Devnet | SOL | 9 |
The CAIP-2 chain identifier format is `namespace:reference`, where:
- EVM uses `eip155:{chainId}` (e.g., `eip155:8453` for Base)
- Solana uses `solana:{cluster}` (e.g., `solana:5rJya` for mainnet-beta)
Source: [packages/sdk/src/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.ts)
## CAIP Address System
All account and token addresses in the Printr system use the CAIP-10 format to ensure chain-agnostic portability:
### Address Format
```
{chain_namespace}:{chain_reference}:{account_address}
```
### Examples
| Chain | CAIP-10 Address |
|-------|-----------------|
| Base wallet | `eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f1D5a` |
| Solana wallet | `solana:5rJya:7xKXytqXCg5tZ3h3J7831q2k6qQxB2mKqPuZpL7fQrm` |
| Base ERC-20 | `eip155:8453:0xTokenAddress...` |
| Solana SPL | `solana:5rJya:TokenMint...` |
The system provides parsing utilities to extract chain namespace and reference from CAIP-10 strings:
```typescript
// Parse CAIP-10 address
const parsed = parseCaip10("eip155:8453:0x742d35Cc6634C0532925a3b844Bc9e7595f1D5a");
// { namespace: "eip155", chainId: "8453", address: "0x742d35..." }
// Extract chain ID from address
const chainId = toCaip2(parsed); // "eip155:8453"
```
Source: [packages/mcp/src/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
## Chain Metadata
Each supported chain maintains metadata used throughout the SDK:
### ChainMeta Interface
```typescript
interface ChainMeta {
id: string; // e.g., "eip155:8453"
name: string; // e.g., "Base"
rpcUrl: string; // RPC endpoint
explorerUrl: string; // Block explorer base URL
explorerTxPath: string; // Transaction path (e.g., "/tx/")
decimals: number; // Native token decimals
symbol: string; // Native token symbol (e.g., "ETH")
}
```
### RPC Configuration
RPC URLs are configured per-environment using the environment discriminant system. Each environment maps to a specific configuration object:
```typescript
type Environment = "mainnet" | "testnet" | "devnet";
const getConfigs = memoize((env: Environment) => ({
apiBaseUrl: "...",
appUrl: "...",
rpcUrls: {
"eip155:1": "https://eth-mainnet.g.alchemy.com/...",
"eip155:8453": "https://base-mainnet.g.alchemy.com/...",
"solana:5rJya": "https://api.mainnet-beta.solana.com",
},
}));
```
Source: [packages/sdk/src/rpc.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/rpc.ts)
## MCP Tools for Chain Operations
The MCP server exposes tools for chain-aware operations. All tools that accept wallet or token addresses support CAIP-10 format.
### Balance Tools
| Tool | Description | Supports |
|------|-------------|----------|
| `printr_get_balance` | Get native token balance | EVM + SVM |
| `printr_get_token_balance` | Get ERC-20/SPL token balance | EVM + SVM |
The `printr_get_token_balance` tool validates that token and wallet chains match:
```typescript
const tokenChain = toCaip2(tokenParsed);
const walletChain = toCaip2(walletParsed);
if (tokenChain !== walletChain) {
return toolError("Token and wallet must be on the same chain");
}
```
Source: [packages/mcp/src/tools/get-token-balance.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/get-token-balance.ts)
### Deployment Wallet Operations
Cross-chain deployment wallet management enables funding ephemeral wallets and reclaiming unused funds:
| Tool | Description | EVM | SVM |
|------|-------------|-----|-----|
| `printr_fund_deployment_wallet` | Create and fund deployment wallet | ✓ | ✓ |
| `printr_drain_deployment_wallet` | Return funds to treasury | ✓ | ✓ |
The drain operation returns metadata including:
```typescript
{
drained_amount: string; // Amount returned (human-readable)
symbol: string; // Native token symbol
from_address: string; // Deployment wallet
to_address: string; // Treasury wallet
tx_signature?: string; // Solana tx signature
tx_hash?: string; // EVM tx hash
remaining_balance: string; // Any remaining dust
wallet_id: string; // Keystore wallet ID
}
```
Source: [packages/mcp/src/tools/drain-deployment-wallet.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/drain-deployment-wallet.ts)
### Chain Information
| Tool | Description |
|------|-------------|
| `printr_get_supported_chains` | List all supported chains with metadata |
Returns chain details including:
- CAIP-2 identifiers
- RPC URLs
- Explorer URLs
- Native token info (symbol, decimals)
## Chain-Specific Transaction Handling
### EVM Transactions
EVM transactions use viem for client creation and transaction submission:
```typescript
const publicClient = createPublicClient({
chain: base,
transport: http(rpcUrl),
});
const walletClient = createWalletClient({
account: privateKeyToAccount(privateKey),
chain: base,
transport: http(rpcUrl),
});
const hash = await walletClient.sendTransaction({
to: recipient,
value: parseUnits(amount, 18),
});
```
### SVM Transactions
Solana transactions use `@solana/web3.js` for connection and transaction management:
```typescript
const connection = new Connection(rpcUrl, "confirmed");
const transaction = new Transaction().add(
SystemProgram.transfer({
fromPubkey: fromKeypair.publicKey,
toPubkey: toPublicKey,
lamports: LAMPORTS_PER_SOL * amount,
})
);
const signature = await sendAndConfirmTransaction(
connection,
transaction,
[fromKeypair]
);
```
## Future Enhancements
The community has expressed interest in expanded chain support:
### Cross-Chain Bridge Tools (Issue #63)
A planned feature would enable agents to move value between Base and Solana:
> Printr already supports launching tokens across EVM chains and Solana, but there's no way for an agent to move value between them. Bridging is table-stakes for any multi-chain agent UX — without it, "launch on Base, fund initial buy from Solana balance" requires the user to leave the chat.
### Additional EVM Chains
The system architecture supports adding new EVM chains through RPC URL and chain metadata configuration. Future releases may include:
- Optimism
- Arbitrum
- Polygon
## SDK Version Compatibility
The latest SDK release (v0.6.1) includes bug fixes for MCP SDK 1.29 compatibility and improved environment configuration.
For Workers-ready bundle requirements (Epic A), the SDK team is working on ensuring the chain utilities evaluate cleanly on Cloudflare Workers without Node.js-specific dependencies blocking evaluation.
Source: [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
---
## Epic Roadmap
### Related Pages
Related topics: [SDK Package (@printr/sdk)](#sdk-package), [Token Operations](#token-operations)
Related Source Files
The following source files were used to generate this page:
- [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/mcp/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/README.md)
- [packages/sdk/src/proto/api/api_pb.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/src/proto/api/api_pb.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/lib/drain.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/lib/drain.ts)
# Epic Roadmap
The printr-mcp Epic Roadmap defines the strategic development phases for the Printr SDK and MCP server, focusing on three major epics: SDK Workers-readiness, shared SDK primitives extraction, and agent trading UX. This roadmap addresses the gap between current token launch capabilities and full multi-chain trading workflows, while ensuring the SDK is optimized for modern edge and serverless runtime environments.
## Overview
The printr-mcp project consists of two primary packages:
| Package | Version | Purpose |
|---------|---------|---------|
| `@printr/sdk` | v0.6.1 | TypeScript SDK for the Printr API—create and manage tokens across EVM chains and Solana |
| `@printr/mcp` | v0.16.1 | MCP server library enabling AI agents to launch tokens across EVM chains and Solana |
Source: [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)
### Current State vs. Roadmap Goals
The current implementation supports token creation and deployment across chains, but has several capability gaps:
- Agents can **launch** tokens but cannot **swap, buy, sell, or bridge** them
- The SDK pulls heavy dependencies (`@solana/web3.js` ~600KB, `viem`) that prevent edge runtime usage
- Browser signing session logic is tightly coupled to MCP implementation
- Node-only dependencies (`sharp`, `node:fs`) are statically imported, affecting bundle size
Source: [Epic C: Agent trading UX #105](https://github.com/PrintrFi/printr-mcp/issues/105), [Epic A: SDK Workers-ready #103](https://github.com/PrintrFi/printr-mcp/issues/103)
## Epic A: SDK Workers-ready
**Issue**: [#103](https://github.com/PrintrFi/printr-mcp/issues/103)
**Goal**: `@printr/sdk` evaluates and runs cleanly on Cloudflare Workers / edge runtimes without vendoring.
### Acceptance Gate
All sub-issues share one acceptance criterion: "a Worker importing the SDK barrel evaluates without throwing."
### Sub-issues
#### #97 - Emit Workers-friendly bundle, drop createRequire shim
Every module in `@printr/sdk/dist/*` currently starts with:
```javascript
import { createRequire } from "node:module";
var __require = createRequire(import.meta.url);
```
This is Bun's bundler default for CJS interop with dependencies that ship CommonJS (e.g., `neverthrow`'s `.cjs.js`). Cloudflare Workers does not support `createRequire`.
**Solution**: Configure the build system to emit ESM-first bundles without the CJS shim.
Source: [fix(sdk): emit Workers-friendly bundle, drop createRequire shim #97](https://github.com/PrintrFi/printr-mcp/issues/97)
#### #96 - Lazy-load sharp + node:fs in image.ts
`packages/sdk/src/image.ts` statically imports `sharp` and `node:fs/promises` at module top level:
```typescript
import sharp from "sharp";
import { readFile } from "node:fs/promises";
```
Since the `@printr/sdk` barrel re-exports `buildToken` from `token.ts`, which transitively re-exports `image.ts`, importing **anything** from the SDK barrel pulls Node-only dependencies into consumers.
**Solution**: Implement lazy loading using dynamic `import()` to defer Node-only dependencies until runtime availability is confirmed.
Source: [fix(sdk): lazy-load sharp + node:fs in image.ts #96](https://github.com/PrintrFi/printr-mcp/issues/96)
#### #101 - Lighter balance via direct JSON-RPC
`packages/sdk/src/balance.ts` currently pulls `@solana/web3.js` (~600KB minified) and `viem` for balance queries. For consumers that only need to read native or SPL balances, this is a heavy tax—especially on edge/Workers runtimes with bundle size limits.
**Solution**: Add a lighter variant (`balance-lite.ts`) that hits Solana RPC directly via lightweight JSON-RPC calls, avoiding the full `@solana/web3.js` bundle.
The SDK package.json exports already include a separate entry point:
```json
"./balance-lite": {
"types": "./dist/balance-lite.d.ts",
"import": "./dist/balance-lite.js"
}
```
Source: [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json), [feat(sdk): lighter balance via direct JSON-RPC #101](https://github.com/PrintrFi/printr-mcp/issues/101)
#### #98 - Types-only @printr/sdk/openapi entry
Today, consumers wanting strict response types have to import from `@printr/sdk/client`, which now pulls runtime code.
**Solution**: Add a `./openapi` subpath export to `@printr/sdk` that re-exports **only** the generated OpenAPI types—`paths`, `components`, `operations`—from `api.gen.d.ts`. No runtime code.
Source: [feat(sdk): types-only @printr/sdk/openapi entry #98](https://github.com/PrintrFi/printr-mcp/issues/98)
### Epic A Architecture
```mermaid
graph TD
A[Consumer imports @printr/sdk] --> B{Is Edge Runtime?}
B -->|Yes| C[Load balance-lite]
B -->|No| D[Load full balance]
C --> E[Direct JSON-RPC calls]
D --> F[Full web3.js + viem]
G[Image processing] --> H{Lazy loaded?}
G --> I[Throws on import]
H -->|Dynamic import| J[Loads sharp + fs]
H -->|Static import| K[Node required]
```
## Epic B: Shared SDK primitives
**Issue**: [#104](https://github.com/PrintrFi/printr-mcp/issues/104)
**Goal**: Lift two pieces of MCP-internal logic into shared SDK subpaths so every Printr client reuses them.
### Sub-issues
#### #100 - Extract signer primitive to @printr/sdk/signer
Lift the browser-sign-by-URL session machinery out of `packages/mcp/src/server/{sessions,app}.ts` into a new `@printr/sdk/signer` subpath.
Every Printr client that needs non-custodial signing—MCP today, future apps tomorrow—wants the same primitive:
1. Mint a signing session
2. Hand the session URL to the user
3. Poll for the signed payload
**Unblocks**: Epic C signing flows.
Source: [feat(sdk): extract signer primitive to @printr/sdk/signer #100](https://github.com/PrintrFi/printr-mcp/issues/100)
#### #82 - Environment discriminant + memoized getConfigs(env)
Today, per-environment URLs (RPC, API, app, CDN) leak through `env.ts` as flat env vars. This needs centralization.
**Solution**:
```typescript
type Environment = "mainnet" | "testnet" | "devnet";
export const getConfigs = memoize((env: Environment) => ({
apiBaseUrl: ...,
appUrl: ...,
rpcUrls: { ... },
}));
```
Source: [Environment discriminant + memoized getConfigs(env) #82](https://github.com/PrintrFi/printr-mcp/issues/82)
### Epic B Pattern
Each extracted primitive follows the same review pattern:
| Step | Description |
|------|-------------|
| 1 | Define subpath export in `package.json` |
| 2 | Create interface for the primitive |
| 3 | Implement two reference implementations |
| 4 | Swap MCP implementation to use SDK subpath |
Source: [Epic B: Shared SDK primitives #104](https://github.com/PrintrFi/printr-mcp/issues/104)
## Epic C: Agent trading UX
**Issue**: [#105](https://github.com/PrintrFi/printr-mcp/issues/105)
**Goal**: Agents using `@printr/mcp` can swap, buy, sell, and bridge—not just launch.
### Scope
Agents using `@printr/mcp` can currently **launch** tokens but cannot **trade** them. To match the conversational UX of agents like Bankr (which is launch + trade + portfolio in one surface), first-class trading primitives are required.
### Sub-features
#### Trading tools (#62)
| Tool | Action | Description |
|------|--------|-------------|
| `swap` | Exchange token A for token B | Atomic swap on DEX |
| `buy` | Purchase token with native asset | Market or limit order |
| `sell` | Liquidate token holdings | Market or limit order |
**Key requirement**: Support trading by ticker symbol, not just contract address.
Source: [feat(sdk,mcp): trading tools — swap, buy, sell by ticker #62](https://github.com/PrintrFi/printr-mcp/issues/62)
#### Cross-chain bridge tools (#63)
Printr already supports launching tokens across EVM chains and Solana, but there's no way for an agent to move value between them. Bridging is table-stakes for any multi-chain agent UX.
**Use case**: "Launch on Base, fund initial buy from Solana balance" currently requires the user to leave the chat.
**Scope**: Base ↔ Solana bridge functionality.
Source: [feat(sdk,mcp): cross-chain bridge tools (Base ↔ Solana) #63](https://github.com/PrintrFi/printr-mcp/issues/63)
### Dependencies
Epic C requires Epic B (#100 signer primitive) to be completed first:
```mermaid
graph LR
A[Epic B: Shared SDK Primitives] --> B[#100: Signer primitive]
B --> C[Epic C: Agent Trading UX]
C --> D[Swap tools]
C --> E[Buy/Sell tools]
C --> F[Bridge tools]
```
### Architecture Requirements
Both sub-issues share common requirements:
- Need the signer primitive from Epic B / #100
- Ship MCP tools + SDK adapter pair
- Require provider choice + e2e fork tests
- Share fee-routing / quote-flow architecture decisions
Source: [Epic C: Agent trading UX #105](https://github.com/PrintrFi/printr-mcp/issues/105)
## Supporting Features
### Privy agentic wallet support (#7)
Integrate [Privy agentic wallets](https://docs.privy.io/recipes/agent-integrations/agentic-wallets) to enable server-side wallet management for the MCP package.
**Important distinction**: The printr web app uses Privy's **client-side React SDK** (`@privy-io/react-auth`) with embedded wallets for browser-based OAuth signing. The agentic wallet support targets server-side, non-custodial management.
Source: [feat: Privy agentic wallet support #7](https://github.com/PrintrFi/printr-mcp/issues/7)
### ABI codegen pipeline (#85)
Add a `scripts/codegen/` pipeline that emits:
- Typed `*.args.ts` encoders
- A read/write `*.Client` per Solidity ABI
**Pattern**:
- Input: `abis/*.json`
- Output: `packages/sdk/src/contracts//{index.ts, *.args.ts}`
- Generated client uses `PublicContractClient`
Source: [ABI codegen pipeline for printr contracts #85](https://github.com/PrintrFi/printr-mcp/issues/85)
### processImageBytes helper (#102)
Add `processImageBytes(bytes: Uint8Array, opts): ResultAsync` that takes raw bytes and returns processed bytes.
**Use cases**: Browsers / edge runtimes where filesystem access is unavailable.
Source: [feat(sdk): processImageBytes(bytes, opts) helper #102](https://github.com/PrintrFi/printr-mcp/issues/102)
## Implementation Order
| Phase | Epic | Issues | Blockers |
|-------|------|--------|----------|
| 1 | Epic A: Workers-ready | #97, #96, #101, #98 | None |
| 2 | Epic B: Shared SDK primitives | #100, #82 | Epic A |
| 3 | Epic C: Trading UX | #62, #63 | Epic B (#100) |
## SDK Export Structure
The SDK exposes multiple subpaths for optimal tree-shaking and runtime optimization:
| Export | Purpose | Bundle Impact |
|--------|---------|---------------|
| `./balance` | Full balance with web3.js + viem | Heavy (~600KB) |
| `./balance-lite` | Lightweight JSON-RPC calls | Minimal |
| `./client` | API client with runtime | Medium |
| `./chains` | Chain definitions | Light |
| `./evm` | EVM utilities | Medium |
| `./svm` | SVM utilities | Medium |
| `./schemas` | Zod validation schemas | Light |
| `./caip` | CAIP-2 chain identifiers | Minimal |
| `./openapi` | Types-only OpenAPI types | Zero runtime |
| `./transfer` | Token transfer operations | Medium |
Source: [packages/sdk/package.json](https://github.com/PrintrFi/printr-mcp/blob/main/packages/sdk/package.json)
## Current Toolset
### Core Token Operations
| Tool | File | Description |
|------|------|-------------|
| `printr_quote` | `packages/mcp/src/tools/quote.ts` | Get cost estimates for token creation |
| `printr_create_token` | `packages/mcp/src/tools/create-token.ts` | Generate unsigned token creation tx |
| `printr_launch_token` | `packages/mcp/src/tools/launch-token.ts` | Create and sign a token in one call |
| `printr_get_token` | `packages/mcp/src/tools/get-token.ts` | Look up token details by ID or address |
| `printr_get_deployments` | `packages/mcp/src/tools/get-deployments.ts` | Check deployment status across chains |
### Signing
| Tool | Description |
|------|-------------|
| `printr_sign_and_submit_evm` | Sign and submit EVM transaction payload |
| `printr_sign_and_submit_svm` | Sign and submit Solana transaction payload |
| `printr_open_web_signer` | Start browser signing session (MetaMask / Phantom) |
### Wallet Management
| Tool | Description |
|------|-------------|
| `printr_wallet_new` | Generate new encrypted wallet |
| `printr_wallet_import` | Import existing private key |
| `printr_wallet_unlock` | Activate stored wallet for signing |
| `printr_wallet_list` | List wallets in keystore |
| `printr_wallet_remove` | Remove wallet from keystore |
### Treasury & Deployment
| Tool | Description |
|------|-------------|
| `printr_set_treasury_wallet` | Unlock treasury wallet for funding |
| `printr_fund_deployment_wallet` | Create and fund ephemeral deployment wallet |
| `printr_drain_deployment_wallet` | Return unused funds from deployment wallet |
Source: [packages/mcp/README.md](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/README.md)
## Launch Token Response Model
When launching a token, the system returns comprehensive transaction and deployment information:
```typescript
interface LaunchTokenOutput {
// Acknowledgment
token_id: string; // Cross-chain telecoin ID (hex)
quote: QuoteOutput; // Full cost breakdown
// Browser signing
url?: string; // Deep link to Printr web app signing page
session_token?: string; // Ephemeral session token
api_port?: number; // Local session API port
expires_at?: number; // Session expiry timestamp
// EVM submission
tx_hash?: string; // EVM transaction hash
block_number?: string; // Block number
tx_status?: "success" | "reverted";
// SVM submission
signature?: string; // Solana transaction signature
slot?: number; // Confirmation slot
confirmation_status?: "finalized" | "confirmed" | "processed";
// Deployment wallet drain
drain_status?: "ok" | "failed" | "skipped";
drain_wallet_id?: string;
}
```
Source: [packages/mcp/src/tools/launch-token.ts](https://github.com/PrintrFi/printr-mcp/blob/main/packages/mcp/src/tools/launch-token.ts)
---
---
## Pitfall Log
Project: PrintrFi/printr-mcp
Summary: Found 19 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.
## 1. Installation risk - Installation risk requires verification
- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_29b9aed5d33e473983c9b6d2f328e9a3 | https://github.com/PrintrFi/printr-mcp/issues/103
## 2. Identity risk - Identity risk requires verification
- Severity: medium
- Evidence strength: runtime_trace
- Finding: Project evidence flags a identity risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Repro command: `npm install @printr/mcp`
- Evidence: identity.distribution | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 3. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_5d0a8de4311d400b8906158d86986f93 | https://github.com/PrintrFi/printr-mcp/issues/100
## 4. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_f67e8511c09a4830815ffe723906fb6e | https://github.com/PrintrFi/printr-mcp/issues/97
## 5. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_559212dc171940c4b45b5e0a598cefb2 | https://github.com/PrintrFi/printr-mcp/issues/82
## 6. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 8. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 9. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 10. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_1a90df3c69554032b209fe1f2740be23 | https://github.com/PrintrFi/printr-mcp/issues/85
## 11. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_a639b0c625d54d81a36e6c2a5748fee2 | https://github.com/PrintrFi/printr-mcp/issues/104
## 12. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_325628e3191e47fcb9eb5174d7adf1cc | https://github.com/PrintrFi/printr-mcp/issues/101
## 13. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_a51e6052cf214b6fbdc4a79113af79d5 | https://github.com/PrintrFi/printr-mcp/issues/98
## 14. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_be3c80140bee4db4a5894e0352aa9061 | https://github.com/PrintrFi/printr-mcp/issues/63
## 15. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_e0b064711428444693fdc8f1b799e8f5 | https://github.com/PrintrFi/printr-mcp/issues/62
## 16. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_5944b6734be44c1bb06310cbebfbf684 | https://github.com/PrintrFi/printr-mcp/issues/7
## 17. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_d19b09d9ce0d406c80390e54f4658131 | https://github.com/PrintrFi/printr-mcp/issues/96
## 18. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp
## 19. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1160348832 | https://github.com/PrintrFi/printr-mcp