# 📜 letters-mcp

[![CI](https://github.com/yappermoar-boop/letters-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/yappermoar-boop/letters-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Network: Base Mainnet](https://img.shields.io/badge/Network-Base%20Mainnet%20(8453)-0052ff.svg)](https://basescan.org)
[![Standard: Model Context Protocol](https://img.shields.io/badge/Standard-MCP-8b5cf6.svg)](https://modelcontextprotocol.io)

An official **Model Context Protocol (MCP)** server that lets AI clients (**Claude Desktop, Cursor, Antigravity, OpenCode**) interact directly with [Letters to the Future](https://base.org) — a decentralized application on **Base mainnet** where anyone can post time-locked messages into the future or mint them as permanent on-chain SVG NFTs via natural language.

---

## 🌟 Natural Language Prompt Examples

With this MCP server connected to your AI assistant, you can simply type:

> *"Post a message for the year 2100: I hope humanity figured out sustainable energy."*  
> *"Leave an anonymous note that unlocks in 50 years: we were trying our best."*  
> *"Show me the latest 20 letters left by others on Base."*  
> *"Mint an on-chain SVG NFT: to whoever finds this — hello from 2026."*  
> *"How many letters have been posted so far to date?"*  

---

## 📦 Installation & Setup

### Option 1: Claude Desktop Integration
Add the following to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "letters": {
      "command": "node",
      "args": ["C:/Users/ad/.gemini/antigravity/scratch/letters-mcp/bin/letters-mcp.js"],
      "env": {
        "PRIVATE_KEY": "0xyour_base_private_key_here"
      }
    }
  }
}
```

### Option 2: Cursor Integration
In Cursor Settings > Features > MCP:
- **Name**: `letters`
- **Type**: `command`
- **Command**: `node C:/Users/ad/.gemini/antigravity/scratch/letters-mcp/bin/letters-mcp.js`

---

## 🛠️ MCP Tools Reference

| Tool | Description | Parameters |
|---|---|---|
| `post_message` | Post an on-chain letter to the future. | `content` (string, req), `unlockYears` (number, opt), `anonymous` (boolean, opt) |
| `list_messages` | Fetch recent on-chain letters. Locked ones show unlock date. | `limit` (number, opt), `offset` (number, opt) |
| `get_message_count` | Query total number of letters posted to date. | None |
| `get_message_by_id` | Query a specific message by numerical ID. | `id` (number, req) |
| `mint_letter_nft` | Mint an on-chain SVG Letter NFT (0.001 ETH). | `content` (string, req) |
| `get_my_nfts` | List all Letter NFTs owned by a wallet. | `address` (string, opt) |
| `get_wallet_info` | Check configured agent wallet address and Base ETH balance. | None |

---

## ⛓️ Base Network Contracts

- **Network**: Base Mainnet (Chain ID: `8453`)
- **Letters V2 Contract**: [`0x8FeF460431Ae853fA74fA53f9B005de5cb9Df0EF`](https://basescan.org/address/0x8FeF460431Ae853fA74fA53f9B005de5cb9Df0EF)
- **Letter NFT Contract**: [`0x3C01937B5d7a800C960170F9AF47aBB4237CB6C6`](https://basescan.org/address/0x3C01937B5d7a800C960170F9AF47aBB4237CB6C6)
- **RPC Endpoints**: `https://mainnet.base.org`, `https://base.llamarpc.com`

---

## ⌨️ CLI Usage

```bash
# Query total letters on Base
node bin/letters-cli.js count

# Browse recent letters
node bin/letters-cli.js list 10

# Post a letter time-locked for 50 years
node bin/letters-cli.js post "Hello from 2026!" 50 false

# Mint an on-chain SVG Letter NFT (0.001 ETH)
node bin/letters-cli.js mint "A digital time capsule in SVG."

# Launch Interactive Web Studio
npm run studio
# Open http://localhost:3403
```

---

## 🔒 Security
Your private key is loaded strictly from the `PRIVATE_KEY` environment variable and is used only to sign transactions locally via Ethers.js. It is never transmitted anywhere other than directly to the Base RPC endpoint as a signed raw transaction.

---

## 🚀 How to Publish to GitHub

```bash
git init
git add .
git commit -m "feat: initial commit for letters-mcp on Base"
git branch -M main
git remote add origin https://github.com/yappermoar-boop/letters-mcp.git
git push -u origin main
```

---

## 📄 License
MIT License. Open source software.