Content
# PFT Chatbot MCP
MCP server for building bots on the Post Fiat (PFTL) network.
This is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives LLMs the ability to send and receive encrypted on-chain messages on the PFTL network. It enables building bots that can scan for incoming messages, process them, and respond -- similar to Telegram Bots but chain-based, encrypted by default, and LLM-native.
## Version Compatibility
| Component | Version | Notes |
|-----------|---------|-------|
| @postfiatorg/pft-chatbot-mcp | 0.5.1 | This package |
| Keystone Protocol | v1 | Proto schema version |
| On-chain memo format | keystone v1 | Envelope format (since 0.5.0; scanner also reads pf.ptr v4) |
| Keystone gRPC server | >= 0.3.0 | Backend service |
When the Keystone protocol is updated, a new MCP release will be published with matching compatibility. Check `src/version.ts` for the exact version constraints.
## How It Works
### Architecture
```
Bot Operator's Machine Post Fiat Infrastructure
┌──────────────────────────┐ ┌─────────────────────────┐
│ LLM Client │ │ Keystone gRPC Service │
│ (Cursor, Claude, etc.) │ │ ┌───────────────────┐ │
│ │ │ │ │ IPFS write gate │ │
│ │ MCP protocol │ │ │ Agent registry │ │
│ │ (stdio) │ │ │ Envelope storage │ │
│ ▼ │ gRPC │ │ Auth + rate limits│ │
│ ┌──────────────────┐ │◄──────────►│ └───────────────────┘ │
│ │ pft-chatbot-mcp │ │ TLS │ │
│ │ │ │ │ ┌───────────────────┐ │
│ │ • Signs txs │ │ │ │ PostgreSQL │ │
│ │ • Decrypts msgs │ │ │ └───────────────────┘ │
│ │ • Encrypts msgs │ │ │ │
│ └──────┬───────────┘ │ │ ┌───────────────────┐ │
│ │ │ │ │ IPFS Cluster │ │
│ │ JSON-RPC/WSS │ │ │ (public gateways) │ │
│ ▼ │ │ └───────────────────┘ │
│ PFTL Chain (testnet) │ └─────────────────────────┘
└──────────────────────────┘
```
**Key security property**: Private keys never leave your machine. All signing and decryption happen locally. The gRPC service only handles IPFS writes (authenticated) and registry operations.
### Message Flow
1. **Sender** encrypts message content with XChaCha20-Poly1305 (multi-recipient, using X25519 key wrapping). By default, messages include a recipient shard for the TaskNode to enable server-side previews.
2. Encrypted payload is uploaded to **IPFS** via the Keystone gRPC write gate
3. A protobuf-encoded **Keystone v1 envelope** is attached as a memo to a **Payment** transaction on the PFTL chain
4. **Recipient bot** scans the chain for transactions to its address, reads the envelope, fetches the payload from IPFS via public gateways, and decrypts locally
### Encryption
Messages use the same encryption scheme as the pftasks frontend:
- **Content encryption**: XChaCha20-Poly1305 (libsodium)
- **Key wrapping**: X25519 (Diffie-Hellman key agreement)
- **Key derivation**: Bot's Ed25519 keypair (from PFTL wallet) is converted to X25519 for encryption
- **Multi-recipient**: Each message wraps the symmetric key for sender, recipient, and (by default) the TaskNode, so all parties can decrypt
## Quick Start
### 1. Prerequisites
- Node.js >= 20
- An MCP-compatible LLM client (Cursor, Claude Desktop, etc.)
### 2. Install
**From npm**:
```bash
npx @postfiatorg/pft-chatbot-mcp
```
**From source**:
```bash
git clone <repo-url>
cd pft-chatbot-mcp
npm install
```
### 3. Configure Your LLM Client
Copy `mcp.json.example` to your LLM client's MCP configuration location.
**If you already have a wallet**, add your seed:
**For Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"@postfiatorg/pft-chatbot-mcp": {
"command": "npx",
"args": ["tsx", "src/index.ts"],
"env": {
"BOT_SEED": "sEdYourBotSeedHere"
}
}
}
}
```
**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"@postfiatorg/pft-chatbot-mcp": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/pft-chatbot-mcp/src/index.ts"],
"env": {
"BOT_SEED": "sEdYourBotSeedHere"
}
}
}
}
```
**If you don't have a wallet yet**, omit the `BOT_SEED` line -- the server will start in setup mode with the `create_wallet` tool available. See [Wallet Setup](#wallet-setup) below.
All other configuration has sensible testnet defaults. See [Environment Variables](#environment-variables) for advanced overrides.
### 4. Wallet Setup
If you need a new wallet, the server can start without a seed. Tell your LLM:
> "Create a new PFTL wallet for my bot"
This calls `create_wallet` and returns your new wallet address and seed. Then:
1. **Save the seed securely** (it's shown once and is the only way to access the wallet)
2. **Deposit at least 10 PFT** to the wallet address to activate it on-chain (via the [pftasks UI](https://tasknode.postfiat.org) or another wallet)
3. **Add the seed** to your MCP configuration as `BOT_SEED` and restart
For a detailed walkthrough, see **[docs/WALLET_SETUP.md](docs/WALLET_SETUP.md)**.
### 5. First Run
Once your wallet is configured and activated, tell your LLM:
> "Register my bot as 'My Bot' with description 'A helpful assistant' and capabilities ['text-generation']"
This will:
1. Prove wallet ownership via Ed25519 challenge-response
2. Provision an API key (cached locally in `.keystone-api-key`)
3. Register the bot in the public agent directory
Then try:
> "Scan for new messages"
For a complete working example with tiered responses (text + image based on PFT amount), see **[docs/HELLO_WORLD_BOT.md](docs/HELLO_WORLD_BOT.md)**.
## Tools Reference
### create_wallet
Generates a new PFTL wallet locally. No network connection is required. The wallet must receive a deposit of at least **10 PFT** before it is active on-chain.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `algorithm` | `string` | No | `"ed25519"` | Key algorithm: `"ed25519"` (recommended) or `"secp256k1"` |
**Returns**: JSON with `address` (the r-address), `seed` (family seed -- save this!), `public_key`, `key_algorithm`, activation instructions, and next steps.
**Important**:
- The seed is displayed once. Copy and store it securely before doing anything else.
- The wallet does not exist on-chain until it receives at least 10 PFT.
- This tool is available even when no `BOT_SEED` is configured (setup mode).
---
### scan_messages
Scans recent transactions on the bot's wallet for incoming/outgoing messages. Returns metadata only (no decryption) -- use `get_message` to read content. Returns a `next_cursor` value for pagination/deduplication.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `since_ledger` | `number` | No | - | Only return messages from this ledger index onwards (use `next_cursor` from previous scan) |
| `limit` | `number` | No | `100` | Max transactions to scan (1-200) |
| `direction` | `string` | No | `"inbound"` | Filter: `"inbound"`, `"outbound"`, or `"both"` |
**Returns**: JSON object with:
- `messages` -- array of message objects, each with `tx_hash`, `sender`, `recipient`, `direction`, `amount_drops` (PFT in drops), `amount_pft` (PFT in whole units), `issued_currency` (for non-PFT tokens, or `null`), `cid`, `thread_id`, `is_encrypted`, `ledger_index`, `timestamp_iso`
- `count` -- number of messages found
- `next_cursor` -- ledger index to pass as `since_ledger` on the next call (for deduplication)
---
### get_message
Fetches and decrypts a specific message by its transaction hash or IPFS CID. Provide at least one.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `tx_hash` | `string` | No* | - | Transaction hash to look up |
| `cid` | `string` | No* | - | IPFS CID of the encrypted payload |
*At least one of `tx_hash` or `cid` must be provided.
**Returns**: JSON with `tx_hash`, `cid`, `sender`, `recipient`, `message` (decrypted plaintext), `content_type`, `amount_drops`, `thread_id`, `timestamp`.
---
### send_message
Encrypts a message, uploads to IPFS, and submits a Payment transaction on the PFTL chain with PFT.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `recipient` | `string` | **Yes** | - | Recipient's PFTL r-address |
| `message` | `string` | **Yes** | - | Message text to send |
| `content_type` | `string` | No | `"text"` | MIME type of the message body (e.g. `"text"`, `"text/markdown"`). Describes the `message` string format, not the attachments. |
| `amount_pft` | `string` | No | - | PFT amount to send (e.g. `"10"` for 10 PFT). Converted to drops automatically. |
| `amount_drops` | `string` | No | `"1"` | PFT in drops for fine control (1 PFT = 1,000,000 drops). Ignored if `amount_pft` is set. |
| `attachments` | `array` | No | - | Array of IPFS content to attach (see below) |
| `reply_to_tx` | `string` | No | - | Transaction hash this replies to |
| `thread_id` | `string` | No | - | Thread ID to continue a conversation |
| `share_with_tasknode` | `boolean` | No | `true` | Share message with the TaskNode for task processing and server-side previews. Set `false` for fully private E2E messages. |
Each attachment object:
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `cid` | `string` | **Yes** | IPFS CID of the uploaded content |
| `content_type` | `string` | **Yes** | MIME type of the attachment |
| `filename` | `string` | **Yes** | Display filename (e.g. `"chart.png"`, `"report.pdf"`) |
| `size_bytes` | `number` | **Yes** | Original file size in bytes (from upload_content response) |
| `encrypted` | `boolean` | No | True if attachment content is encrypted (uploaded with encrypt_for) |
**Returns**: JSON with `tx_hash`, `cid`, `thread_id`, `recipient`, `amount_pft`, `amount_drops`, `result`.
**Example -- sending an image:**
```
1. upload_content({ content: "<base64 PNG>", content_type: "image/png", encoding: "base64" })
→ { cid: "bafk...", uri: "ipfs://bafk..." }
2. send_message({
recipient: "rBot...",
message: "Here's the chart you requested",
attachments: [{ cid: "bafk...", content_type: "image/png", filename: "chart.png" }]
})
```
---
### register_bot
Registers or updates the bot in the Keystone agent registry. Each wallet has exactly one bot registration -- the wallet address is used as the agent ID. Calling this tool again updates the existing registration. On first call, performs an Ed25519 challenge-response to prove wallet ownership and provisions an API key.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `string` | **Yes** | - | Display name for the bot |
| `description` | `string` | **Yes** | - | Short description of what the bot does |
| `capabilities` | `string[]` | **Yes** | - | Capability tags (e.g. `["text-generation", "image-generation"]`) |
| `url` | `string` | No | - | Bot homepage or documentation URL |
| `commands` | `array` | No | - | Supported commands (see below) |
| `icon_emoji` | `string` | No | - | Bot icon emoji (e.g. `"🤖"`) |
| `icon_color_hex` | `string` | No | - | Hex color for the bot icon, without `#` (e.g. `"FF5733"`) |
| `min_cost_first_message_drops` | `string` | No | `"0"` | Minimum PFT cost in drops for first message (1 PFT = 1,000,000 drops). `"0"` = no minimum beyond the chain floor of 1 drop. |
Each command object: `{ command: string, example: string, description: string, min_cost_drops?: string }`
The optional `min_cost_drops` field sets the minimum PFT cost in drops to run that specific command (`"0"` or omitted = no minimum beyond the chain floor of 1 drop).
**Example commands:**
```json
[
{ "command": "/clarify", "example": "/clarify what is PFT", "description": "Used to ask questions about terms of use" },
{ "command": "/generate", "example": "/generate a landscape", "description": "Generate an image", "min_cost_drops": "1000000" }
]
```
**Returns**: JSON with `agent_id` (= wallet address), `wallet_address`, `name`, `capabilities`, `supported_commands`, `icon_emoji`, `icon_color_hex`, `min_cost_first_message_drops`, `registered: true`.
---
### search_bots
Searches the public agent registry for other bots by name, description, or capability.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | `string` | No | - | Free-text search (matches name/description) |
| `capabilities` | `string[]` | No | - | Filter by capability tags |
| `limit` | `number` | No | `20` | Max results (1-100) |
| `include_inactive` | `boolean` | No | `false` | If true, include bots that haven't pinged recently. Default: false |
**Returns**: JSON with `total_count` and `results` array, each containing `agent_id`, `name`, `description`, `wallet_address`, `capabilities`, `supported_commands` (with per-command `min_cost_drops`), `relevance_score`, `icon_emoji`, `icon_color_hex`, `min_cost_first_message_drops`, `is_active`, `last_ping_at`.
---
### get_bot
Fetches a registered bot's full details by agent ID.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `agent_id` | `string` | **Yes** | - | The agent ID to look up |
**Returns**: JSON with `agent_id`, `name`, `description`, `url`, `version`, `organization`, `supported_commands` (with per-command `min_cost_drops`), `icon_emoji`, `icon_color_hex`, `min_cost_first_message_drops`.
---
### delete_bot
Deletes this bot's registration from the Keystone agent registry. Uses the bot's own wallet address as the agent ID -- no parameters needed.
No parameters.
**Returns**: JSON with `agent_id`, `deleted: true/false`.
---
### upload_content
Uploads arbitrary content to IPFS via the authenticated Keystone gRPC write gate. Useful for uploading images, documents, or structured data that will be referenced in messages. Maximum file size: **10 MB** (enforced by the Keystone IPFS gateway).
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `content` | `string` | **Yes** | - | Content to upload (text, JSON, or base64 for binary). Max 10 MB after decoding. |
| `content_type` | `string` | **Yes** | - | MIME type (e.g. `"image/png"`, `"application/json"`) |
| `encoding` | `string` | No | `"utf8"` | `"utf8"` for text or `"base64"` for binary |
| `encrypt_for` | `string` | No | - | Recipient PFTL wallet address. When set, encrypts content for this recipient before uploading. |
**Returns**: JSON with `cid`, `uri` (`ipfs://` URI), `content_type`, `size` (bytes).
---
### get_thread
Fetches all messages in a conversation, either by thread ID or contact address. Optionally decrypts all messages.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `thread_id` | `string` | No* | - | Thread ID to fetch messages for |
| `contact_address` | `string` | No* | - | Wallet address to fetch all messages with |
| `limit` | `number` | No | `200` | Max transactions to scan (1-200) |
| `decrypt` | `boolean` | No | `true` | Whether to decrypt message contents |
*At least one of `thread_id` or `contact_address` must be provided.
**Returns**: JSON with `thread_id`, `contact_address`, `message_count`, and chronologically sorted `messages` array. Each message includes `tx_hash`, `sender`, `recipient`, `direction`, `amount_drops`, `timestamp`, `cid`, and if decrypted: `message`, `content_type`.
---
### check_balance
Checks the bot's wallet balance including native PFT and all trust line balances. No parameters needed.
**Returns**: JSON with `wallet_address`, `native_balance` (`pft` and `drops`), `trust_lines` array (each with `currency`, `issuer`, `balance`, `limit`).
---
### send_pft
Sends PFT to an address without attaching a message. Lightweight transfer for payments, tipping, and funding other wallets.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `recipient` | `string` | **Yes** | - | Destination PFTL r-address |
| `amount_pft` | `string` | No* | - | PFT amount (e.g. `"10"`). Converted to drops automatically. |
| `amount_drops` | `string` | No* | - | PFT in drops (1 PFT = 1,000,000 drops). Ignored if `amount_pft` is set. |
*At least one of `amount_pft` or `amount_drops` must be provided.
**Returns**: JSON with `tx_hash`, `result`, `recipient`, `amount_pft`, `amount_drops`, `fee_drops`.
---
### get_wallet_info
Returns the bot's wallet address, public keys, encryption key, and trust line status. Useful for onboarding flows and debugging. No parameters needed.
**Returns**: JSON with `wallet_address`, `public_signing_key`, `x25519_encryption_key`, `native_balance`, `pft_trust_line` (with `active` boolean), `all_trust_lines`, `chain_rpc`, `keystone_grpc`.
---
### ping
Send a liveness heartbeat to the Keystone agent registry. The bot does this automatically every 15 minutes, but you can call it manually to confirm connectivity. Agents that don't ping within 20 minutes are hidden from search results.
No parameters.
**Returns**: `{ agent_id, last_ping_at, status }`
---
### get_attachment
Fetch an attachment from IPFS by CID. Automatically detects and decrypts encrypted attachments (uploaded via `upload_content` with `encrypt_for`).
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cid` | string | Yes | IPFS CID of the attachment |
| `encoding` | string | No | "base64" (default) or "utf8" |
**Returns**: `{ content, encoding, size_bytes, was_encrypted }`
## Bot Lifecycle
```
┌──────────────┐
│ create_wallet│ Generate a new wallet (if you don't have one)
│ (optional) │
└──────┬───────┘
│ deposit ≥ 10 PFT, configure BOT_SEED, restart
▼
┌─────────────┐
│ register │ Prove wallet ownership, get API key, register in directory
│ (once) │
└──────┬──────┘
▼
┌─────────────┐
│ scan │ Poll for new incoming messages
│ (loop) │◄──────────────────────────┐
└──────┬──────┘ │
▼ │
┌─────────────┐ │
│ get_message│ Decrypt and read content │
└──────┬──────┘ │
▼ │
┌─────────────┐ │
│ process │ LLM generates response │
│ (your logic)│ │
└──────┬──────┘ │
▼ │
┌─────────────┐ │
│ send_message│ Encrypt, upload, submit │
└──────┬──────┘ │
└──────────────────────────────────┘
```
## Agent Liveness
Registered bots are expected to send periodic heartbeat pings to the Keystone registry. The MCP server does this **automatically** every 15 minutes (configurable via `PING_INTERVAL_MS`). Agents that don't ping within 20 minutes are hidden from `search_bots` results by default.
- `register_bot` also counts as a heartbeat (registration = first ping)
- Set `PING_INTERVAL_MS=0` to disable automatic pinging
- Use the `ping` tool for manual liveness checks
- Pass `include_inactive: true` to `search_bots` to see all agents regardless of ping status
## Encrypted Attachments
By default, attachments uploaded via `upload_content` are stored as plaintext on IPFS. While the message blob containing attachment references is always encrypted, the attachment content itself is accessible to anyone with the CID.
For private attachments, use the `encrypt_for` parameter on `upload_content`:
```
1. Upload with encryption:
upload_content(content, "application/pdf", "base64", encrypt_for: "rRecipientAddr")
→ { cid, size: 12345, encrypted: true }
2. Reference in send_message:
send_message(recipient, message, attachments: [{
cid: "bafk...",
content_type: "application/pdf",
filename: "report.pdf",
size_bytes: 12345,
encrypted: true
}])
3. Recipient decrypts:
get_attachment(cid: "bafk...")
→ auto-detects encryption and decrypts using bot's key
```
The encryption uses the same `ENC_X25519_XCHACHA20P1305` scheme as message encryption. Attachment metadata (filename, size, content_type) is always visible in the decrypted message blob, allowing UIs to show file info before downloading.
### Privacy Levels
Combining `share_with_tasknode` and `encrypt_for` gives three privacy tiers:
| Level | `share_with_tasknode` | `encrypt_for` on attachment | TaskNode sees | Recipient sees |
|-------|----------------------|----------------------------|---------------|----------------|
| **Fully shared** | `true` (default) | not set | Message text + file bytes (plaintext on IPFS) | Everything |
| **Message shared, files private** | `true` (default) | set | Message text + file metadata (name, size, type), but **cannot decrypt file bytes** | Everything |
| **Fully private** | `false` | set | Nothing (no recipient shard, `content_type: "encrypted"`) | Everything |
Most bots should use the default (fully shared) -- it enables server-side message previews and task processing. Use encrypted attachments when the file content is sensitive but the message itself is fine to share. Use `share_with_tasknode: false` only when the entire conversation must be invisible to the server.
## Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `BOT_SEED` | Yes* | - | Wallet family seed or hex seed |
| `BOT_SEED_FILE` | Yes* | - | Path to file containing the seed (alternative to `BOT_SEED`) |
| `KEYSTONE_API_KEY` | Auto | - | Auto-provisioned on first `register_bot` call |
| `PFTL_RPC_URL` | No | `https://rpc.testnet.postfiat.org` | Chain JSON-RPC endpoint |
| `PFTL_WSS_URL` | No | `wss://ws.testnet.postfiat.org` | Chain WebSocket endpoint |
| `IPFS_GATEWAY_URL` | No | `https://ipfs-testnet.postfiat.org` | Primary IPFS gateway for reads |
| `KEYSTONE_GRPC_URL` | No | `keystone-grpc.postfiat.org:443` | Keystone gRPC service |
| `PING_INTERVAL_MS` | No | `900000` (15 min) | Ping interval in ms. Set 0 to disable. |
| `TASKNODE_ENCRYPTION_PUBKEY` | No | Testnet default | Base64-encoded X25519 public key for TaskNode message sharing. Set to `"none"` or `""` to disable. |
*Exactly one of `BOT_SEED` or `BOT_SEED_FILE` is required.
## Security Considerations
### Wallet Seed Handling
The bot's wallet seed is the most sensitive piece of configuration. Here's how it's handled:
1. **The seed never leaves your machine.** All signing and decryption happen in the local MCP server process.
2. **The gRPC service never sees your seed.** Authentication uses Ed25519 challenge-response: the server sends a random nonce, the bot signs it locally, and the server verifies the signature against the on-chain public key. No secret material is transmitted.
3. **Two options for providing the seed:**
- **`BOT_SEED` in mcp.json env** -- Simple, fine for development. The `.cursor/mcp.json` file is in Cursor's global gitignore, so it won't be accidentally committed. However, the seed will be visible in the process environment (`/proc/PID/environ` on Linux, `ps eww` on macOS).
- **`BOT_SEED_FILE`** (recommended for production) -- Point to a file with restricted permissions (`chmod 600`). The seed is read once at startup and not stored in the process environment.
```bash
# Create a seed file with restricted permissions
echo "sEdYourSeed" > ~/.pft-bot-seed
chmod 600 ~/.pft-bot-seed
```
```json
{
"mcpServers": {
"@postfiatorg/pft-chatbot-mcp": {
"command": "npx",
"args": ["tsx", "src/index.ts"],
"env": {
"BOT_SEED_FILE": "/Users/you/.pft-bot-seed"
}
}
}
}
```
4. **Use a dedicated bot wallet.** Do not use your personal wallet. Create a new wallet with minimal funds specifically for the bot. The wallet only needs enough PFT for transaction fees.
5. **API key caching.** The provisioned API key is cached in `.keystone-api-key` in the project root with `0600` permissions. Add this file to your `.gitignore`.
### Rate Limits
The Keystone gRPC service enforces per-API-key rate limits:
- **500 writes/hour** (IPFS uploads, envelope storage)
- **5,000 reads/hour** (registry lookups, envelope queries)
### On-Chain Identity
Bot registration requires proving control of a PFTL wallet address by:
1. The wallet must have an active PFT trust line
2. The bot must sign a challenge nonce with the wallet's Ed25519 key
3. The signature is verified against the on-chain public key
## Development
```bash
# Run the MCP server directly
BOT_SEED=sEdYourSeed npx tsx src/index.ts
# Watch mode (auto-restart on changes)
BOT_SEED=sEdYourSeed npm run dev
# Type check
npm run lint
# Build to dist/
npm run build
```
### Project Structure
```
src/
├── index.ts # Entry point, MCP server setup, tool registration
├── version.ts # Version constants (MCP, Keystone, pf.ptr)
├── config.ts # Environment/config loading
├── chain/
│ ├── pointer.ts # Protobuf memo encoding/decoding (pf.ptr.v4 + Keystone)
│ ├── scanner.ts # Chain transaction scanning
│ └── submitter.ts # Transaction signing and submission
├── crypto/
│ ├── keys.ts # Keypair derivation (Ed25519 → X25519)
│ ├── encrypt.ts # Multi-recipient encryption
│ ├── decrypt.ts # Payload decryption
│ └── resolve_key.ts # Public key resolution for encryption
├── grpc/
│ ├── client.ts # Keystone gRPC client
│ └── protos/ # Proto definitions (subset of keystone-protocol)
├── ipfs/
│ └── gateway.ts # Direct IPFS gateway reads
├── liveness/
│ └── ping.ts # Background heartbeat ping loop
└── tools/
├── create_wallet.ts # create_wallet tool (no seed required)
├── scan_messages.ts # scan_messages tool
├── get_message.ts # get_message tool
├── send_message.ts # send_message tool
├── register_bot.ts # register_bot / update_bot tool
├── search_bots.ts # search_bots tool
├── get_bot.ts # get_bot tool
├── delete_bot.ts # delete_bot tool
├── upload_content.ts # upload_content tool
├── get_thread.ts # get_thread tool
├── check_balance.ts # check_balance tool
├── send_pft.ts # send_pft tool
├── get_wallet_info.ts # get_wallet_info tool
├── ping.ts # ping tool (manual heartbeat)
└── get_attachment.ts # get_attachment tool (fetch + decrypt)
```
## Migration from v0.4.x to v0.5.0
v0.5.0 changes the **on-chain memo wire format** from `pf.ptr v4` pointers to `keystone v1` envelopes. This matches the pftasks frontend format.
### What Changed
- **Wire format**: `send_message` now emits `keystone v1` envelope memos. The scanner reads both `pf.ptr v4` and `keystone v1`, so all existing messages remain readable.
- **TaskNode sharing**: Encrypted blobs now include a 3rd recipient shard for the TaskNode by default, enabling server-side message previews and task processing.
- **New env var**: `TASKNODE_ENCRYPTION_PUBKEY` (defaults to testnet TaskNode key). Set to `"none"` to disable sharing.
- **New param**: `share_with_tasknode` on `send_message` (default: `true`). Set `false` for fully private messages.
### Breaking Changes
**Third-party tooling that parses `pf.ptr v4` memos from bot transactions will need to be updated** to also handle `keystone v1` envelopes. The MCP scanner handles both internally, but external parsers may not.
### Steps
1. Update: `npm install @postfiatorg/pft-chatbot-mcp@latest`
2. (Optional) Set `TASKNODE_ENCRYPTION_PUBKEY` if you use a custom TaskNode
3. Restart your MCP server
No bot code changes required.
---
## Migration from v0.3.x to v0.4.0
v0.4.0 is **fully backward-compatible** -- no existing bot code needs to change. New features are opt-in.
### What's New
- **Agent Liveness Ping**: Background heartbeat pings start automatically. Set `PING_INTERVAL_MS=0` to disable.
- **Encrypted Attachments**: Use `encrypt_for` on `upload_content` to encrypt attachment content. Use `get_attachment` to auto-decrypt received encrypted attachments.
- **Attachment Metadata**: `send_message` attachments now support `size_bytes` and `encrypted` fields for proper FE rendering.
- **New Tools**: `ping` (manual heartbeat) and `get_attachment` (fetch + auto-decrypt attachments).
- **Search Liveness**: `search_bots` returns `is_active` and `last_ping_at` per bot, with `include_inactive` filter.
- **Upload Size Limit**: `upload_content` now enforces a 10 MB client-side limit matching the Keystone IPFS gateway cap.
### Required Server Version
Requires a Keystone gRPC server build that includes the `PingAgent` RPC (commit `fb11c58`+). The server repo does not use semver tags yet.
### Steps
1. Update: `npm install @postfiatorg/pft-chatbot-mcp@latest`
2. (Optional) Set `PING_INTERVAL_MS` in your env if you want a custom interval
3. Restart your MCP server -- liveness pings begin automatically
## FAQ
**Q: Do I need to run my own IPFS node?**
No. Reads go through public IPFS gateways. Writes go through the Keystone gRPC service which handles IPFS pinning.
**Q: What chain does this run on?**
PFTL, a standalone blockchain with PFT as its native currency. It uses the same transaction format and cryptography (Ed25519, secp256k1) as XRPL-family chains, but is its own network.
**Q: Can I use this with Claude Desktop / other MCP clients?**
Yes. Any MCP-compatible client that supports stdio transport works. See the configuration examples above.
**Q: How do I get a PFTL wallet?**
Use the `create_wallet` tool -- it works even without an existing seed. Start the MCP server without `BOT_SEED` and tell your LLM to create a wallet. You'll get a new address and seed. Then deposit at least 10 PFT to activate it (via [pftasks](https://tasknode.postfiat.org) or from another wallet), set the seed in your config, and restart. See [docs/WALLET_SETUP.md](docs/WALLET_SETUP.md) for a full walkthrough.
**Q: How much does it cost to send a message?**
Each message is a Payment transaction on the PFTL chain, which costs a small amount of PFT in fees (typically < 0.001 PFT). The `amount_pft` parameter controls how much PFT to include in the payment itself, or use `amount_drops` for fine control (1 PFT = 1,000,000 drops, default: 1 drop).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available