# 🤖 YAMO Chain MCP Server [![npm version](https://img.shields.io/npm/v/@yamo/mcp-server?style=flat-square)](https://www.npmjs.com/package/@yamo/mcp-server)

This MCP Server acts as a bridge, allowing LLMs to interact with the YAMO Blockchain. It is now powered by `@yamo/core` for robust IPFS handling.

## 📦 Installation

```bash
# Global installation (recommended)
npm install -g @yamo/mcp-server

# Or use npx (no installation needed)
npx @yamo/mcp-server
```

## 🧰 Tools Provided

### `yamo_recall_lessons`
Recalls past `LessonLearned` constraints stored by YAMO agents — **Ghost Protection**.

Call this at the start of each session to restore institutional memory and avoid repeating past mistakes. Returns raw YAMO block content strings; the calling LLM interprets and applies them as active constraints.

*   **Input**: `limit` (optional, default: 5, max: 20)
*   **Output**: Raw YAMO block strings joined with double newline
*   **Env**: `YAMO_MEMORY_PATH` — path to LanceDB directory (default: `./data/memories.lance`)

> **Architectural note:** This server accesses memory in **read-only mode**. If a future
> requirement needs MCP sessions to store lessons, route writes through yamo-bridge via
> `memory:shared` — do not open the LanceDB store for direct writes from MCP.

### `yamo_submit_block`
Submits a new reasoning block.
*   **Input**: `blockId`, `contentHash`, etc.
*   **New Feature**: `content` (string) and `files` (array). If provided, the server handles IPFS uploading and Deep Bundling automatically before signing.
*   **Encryption**: Optional `encryptionKey` (string). If provided, the bundle is encrypted (AES-256-GCM) before upload, ensuring privacy for sensitive reasoning chains.

### `yamo_get_block`
Retrieves full block data from the YAMO blockchain by its unique ID.
Returns metadata including `blockId`, `previousBlock`, `agentAddress`, `contentHash`, `timestamp`, `consensusType`, `ledger`, and `ipfsCID`.

### `yamo_get_latest_block`
Retrieves the most recently submitted YAMO block from the blockchain. Useful for automatically getting the chain tip to use as `previousBlock` for the next submission.

### `yamo_audit_block`
Performs a cryptographic integrity audit of a block.
1.  Fetches block metadata from blockchain.
2.  Downloads content from IPFS.
3.  Re-hashes the content locally.
4.  Asserts `LocalHash === ChainHash`.
Requires `encryptionKey` if the bundle is encrypted.

### `yamo_verify_block`
Quickly verifies if a specific hash matches the immutable on-chain record for a block ID.

### `yamo_anchor_event`
Anchors a YAMO provenance event on-chain (Phase 3). Submits a `blockId` and `contentHash` pair to the registry without IPFS content.

### `yamo_bridge_*`
Tools for interacting with the YAMO bridge cluster (requires `YAMO_BRIDGE_URL`):
- `yamo_bridge_list_kernels`: Lists connected kernels and their skills.
- `yamo_bridge_cluster_status`: Shows bridge cluster status (Raft leader, members).
- `yamo_bridge_invoke_skill`: Invokes a skill on a capable kernel.

## ⚙️ Configuration

### Option 1: Claude Desktop Integration (Recommended)

Add to your Claude Desktop config (`claude_desktop_config.json`):

**With Global Installation:**
```json
{
  "mcpServers": {
    "yamo-chain": {
      "command": "yamo-mcp-server",
      "env": {
        "CONTRACT_ADDRESS": "0x3c9440fa8d604E732233ea17095e14be1a53b015",
        "RPC_URL": "https://ethereum-sepolia-rpc.publicnode.com",
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "USE_REAL_IPFS": "false",
        "PINATA_JWT": "optional_if_using_real_ipfs"
      }
    }
  }
}
```

**With npx (no installation):**
```json
{
  "mcpServers": {
    "yamo-chain": {
      "command": "npx",
      "args": ["@yamo/mcp-server"],
      "env": {
        "CONTRACT_ADDRESS": "0x3c9440fa8d604E732233ea17095e14be1a53b015",
        "RPC_URL": "https://ethereum-sepolia-rpc.publicnode.com",
        "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "USE_REAL_IPFS": "false"
      }
    }
  }
}
```

### Option 2: Standalone Usage

Set environment variables and run:

```bash
export CONTRACT_ADDRESS=0x3c9440fa8d604E732233ea17095e14be1a53b015
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export PRIVATE_KEY=0xYOUR_PRIVATE_KEY

# With global install
yamo-mcp-server

# Or with npx
npx @yamo/mcp-server
```

## 🌐 Networks

### Sepolia Testnet (Production - Recommended)

**Configuration:**
- Contract: `0x3c9440fa8d604E732233ea17095e14be1a53b015`
- RPC: `https://ethereum-sepolia-rpc.publicnode.com`

**Requirements:**
- ✅ Wallet with Sepolia ETH for gas
- ✅ Public RPC endpoint (no API key needed)

### Local Development

**Configuration:**
- Contract: Deploy using `@yamo/contracts`
- RPC: `http://127.0.0.1:8545`

**Requirements:**
- ⚠️ Local Hardhat node must be running: `npx hardhat node`
- ⚠️ Contract must be deployed locally
- ⚠️ Wallet must be funded with local ETH

## 💰 Wallet Setup

### 1. Generate a Wallet

If you don't have a private key:
```bash
node -e "const ethers = require('ethers'); const w = ethers.Wallet.createRandom(); console.log('Address:', w.address); console.log('Private Key:', w.privateKey);"
```

### 2. Get Sepolia ETH (Testnet Only)

Your wallet needs Sepolia ETH for gas. Use your **wallet address** (not private key) with these faucets:

**Alchemy Faucet** (Fastest - 0.5 ETH):
- https://www.alchemy.com/faucets/ethereum-sepolia
- Sign in with Google/GitHub

**PoW Faucet** (No login - 0.05-0.1 ETH):
- https://sepolia-faucet.pk910.de/
- Mine for ~5 minutes

**Google Cloud Faucet** (0.05 ETH):
- https://cloud.google.com/application/web3/faucet/ethereum/sepolia

### 3. Check Your Balance

```bash
# Replace with your wallet address
curl -X POST https://ethereum-sepolia-rpc.publicnode.com \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0xYOUR_ADDRESS","latest"],"id":1}'
```

If result is `"0x0"`, you need more ETH!

## ⚠️ Common Issues

### "Sender doesn't have enough funds"

**Problem:** Your wallet has 0 ETH or insufficient balance

**Solution:**
1. Check you're using **Sepolia RPC**, not localhost
2. Verify your wallet address has Sepolia ETH (see faucets above)
3. Make sure `PRIVATE_KEY` matches the funded wallet

### "Connection refused" or "ECONNREFUSED"

**Problem:** RPC_URL points to `http://127.0.0.1:8545` but no local node running

**Solution:**
- **For Sepolia:** Change RPC to `https://ethereum-sepolia-rpc.publicnode.com`
- **For Local:** Start Hardhat node: `cd packages/contracts && npx hardhat node`

### Balance shows 0 but I have ETH

**Problem:** Wrong network - you might have mainnet ETH, not Sepolia ETH

**Solution:**
1. Verify RPC is Sepolia: `https://ethereum-sepolia-rpc.publicnode.com`
2. Check balance on Sepolia: https://sepolia.etherscan.io/
3. Get Sepolia testnet ETH from faucets (see above)