PFT Chatbot MCP

MCP server for building bots on the Post Fiat (PFTL) network.

This is a Model Context Protocol 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

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:

npx @postfiatorg/pft-chatbot-mcp

From source:

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):

{
  "mcpServers": {
    "@postfiatorg/pft-chatbot-mcp": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "env": {
        "BOT_SEED": "sEdYourBotSeedHere"
      }
    }
  }
}

For Claude Desktop (claude_desktop_config.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 below.

All other configuration has sensible testnet defaults. See 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 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.

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.

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.

*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.

Each attachment object:

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.

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:

[
  { "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.

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.

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).

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.

*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.

*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).

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:

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

*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.

1. 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.

1. 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.

     # Create a seed file with restricted permissions
     echo "sEdYourSeed" > ~/.pft-bot-seed
     chmod 600 ~/.pft-bot-seed

     {
       "mcpServers": {
         "@postfiatorg/pft-chatbot-mcp": {
           "command": "npx",
           "args": ["tsx", "src/index.ts"],
           "env": {
             "BOT_SEED_FILE": "/Users/you/.pft-bot-seed"
           }
         }
       }
     }

1. 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.

1. 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

# 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 or from another wallet), set the seed in your config, and restart. See 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).