@yamo/mcp-server 1.0.4 → 1.3.0

package/README.md

@@ -1,4 +1,4 @@
-# 🤖 YAMO Chain MCP Server (v1.0.1 - Protocol v0.4)
+# 🤖 YAMO Chain MCP Server [![npm version](https://badge.fury.io/js/@yamo%2Fmcp-server.svg)](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.
 
@@ -37,7 +37,7 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
       "command": "yamo-mcp-server",
       "env": {
         "CONTRACT_ADDRESS": "0x3c9440fa8d604E732233ea17095e14be1a53b015",
-        "RPC_URL": "https://rpc.sepolia.org",
+        "RPC_URL": "https://ethereum-sepolia-rpc.publicnode.com",
         "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
         "USE_REAL_IPFS": "false",
         "PINATA_JWT": "optional_if_using_real_ipfs"
@@ -56,7 +56,7 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
       "args": ["@yamo/mcp-server"],
       "env": {
         "CONTRACT_ADDRESS": "0x3c9440fa8d604E732233ea17095e14be1a53b015",
-        "RPC_URL": "https://rpc.sepolia.org",
+        "RPC_URL": "https://ethereum-sepolia-rpc.publicnode.com",
         "PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
         "USE_REAL_IPFS": "false"
       }
@@ -71,7 +71,7 @@ Set environment variables and run:
 
 ```bash
 export CONTRACT_ADDRESS=0x3c9440fa8d604E732233ea17095e14be1a53b015
-export RPC_URL=https://rpc.sepolia.org
+export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
 export PRIVATE_KEY=0xYOUR_PRIVATE_KEY
 
 # With global install
@@ -87,7 +87,7 @@ npx @yamo/mcp-server
 
 **Configuration:**
 - Contract: `0x3c9440fa8d604E732233ea17095e14be1a53b015`
-- RPC: `https://rpc.sepolia.org` or `https://ethereum-sepolia-rpc.publicnode.com`
+- RPC: `https://ethereum-sepolia-rpc.publicnode.com`
 
 **Requirements:**
 - ✅ Wallet with Sepolia ETH for gas
@@ -155,7 +155,7 @@ If result is `"0x0"`, you need more ETH!
 **Problem:** RPC_URL points to `http://127.0.0.1:8545` but no local node running
 
 **Solution:**
-- **For Sepolia:** Change RPC to `https://rpc.sepolia.org`
+- **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
@@ -163,6 +163,6 @@ If result is `"0x0"`, you need more ETH!
 **Problem:** Wrong network - you might have mainnet ETH, not Sepolia ETH
 
 **Solution:**
-1. Verify RPC is Sepolia: `https://rpc.sepolia.org`
+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)

package/dist/index.js

@@ -43,37 +43,167 @@ const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const core_1 = require("@yamo/core");
 const dotenv = __importStar(require("dotenv"));
 const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '../package.json'), 'utf8'));
 dotenv.config();
 const SUBMIT_BLOCK_TOOL = {
     name: "yamo_submit_block",
-    description: "Submits a YAMO block to the YAMORegistry smart contract.",
+    description: `Submits a YAMO block to the YAMORegistry smart contract.
+
+**IMPORTANT FORMAT REQUIREMENTS:**
+- blockId: Must follow YAMO naming convention: {origin}_{workflow}
+  • Examples: "claude_chain", "aurora_weave", "document_translation"
+  • Do NOT use sequence numbers (001, 002)
+- contentHash: Must be a valid bytes32 hash (32 bytes = 64 hex characters)
+  • Format: "0x" followed by exactly 64 hexadecimal characters
+  • Do NOT include algorithm prefixes (e.g., "sha256:")
+- previousBlock: For genesis block use: 0x0000000000000000000000000000000000000000000000000000000000000000
+
+**Transaction Flow:**
+1. Content and files are uploaded to IPFS (if provided)
+2. Block is submitted to smart contract with hash reference
+3. Returns transaction hash and IPFS CID`,
     inputSchema: {
         type: "object",
         properties: {
-            blockId: { type: "string" },
-            previousBlock: { type: "string" },
-            contentHash: { type: "string" },
-            consensusType: { type: "string" },
-            ledger: { type: "string" },
-            content: { type: "string", description: "Optional: Full YAMO text content for IPFS anchoring." },
-            encryptionKey: { type: "string", description: "Optional: Key to encrypt the IPFS bundle." },
+            blockId: {
+                type: "string",
+                description: "Unique block identifier following YAMO naming: {origin}_{workflow} (e.g., 'claude_chain')"
+            },
+            previousBlock: {
+                type: "string",
+                pattern: "^0x[a-fA-F0-9]{64}$",
+                description: "Content hash of parent block. Genesis: 0x0000...0000"
+            },
+            contentHash: {
+                type: "string",
+                pattern: "^0x[a-fA-F0-9]{64}$",
+                description: "32-byte hash (0x + 64 hex chars). No algorithm prefixes."
+            },
+            consensusType: {
+                type: "string",
+                enum: ["agent_vote", "PoW", "PoS", "cli_manual", "mcp_generated"],
+                description: "Consensus mechanism"
+            },
+            ledger: {
+                type: "string",
+                description: "Distributed storage reference (e.g., 'ipfs', 'arweave')"
+            },
+            content: {
+                type: "string",
+                description: "Optional: Full YAMO text content for IPFS anchoring."
+            },
+            encryptionKey: {
+                type: "string",
+                description: "Optional: Strong key (12+ chars, mixed types) for IPFS encryption."
+            },
             files: {
                 type: "array",
-                items: { type: "object", properties: { name: { type: "string" }, content: { type: "string" } } },
-                description: "Optional: Array of output files to bundle. Each file's 'content' can be either the actual file content (string) or a file path (will be auto-read)."
+                items: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string" },
+                        content: { type: "string" }
+                    },
+                    required: ["name", "content"]
+                },
+                description: "Optional: Output files to bundle. Content can be file path (auto-read) or actual content."
             }
         },
         required: ["blockId", "previousBlock", "contentHash", "consensusType", "ledger"],
     },
 };
+const GET_BLOCK_TOOL = {
+    name: "yamo_get_block",
+    description: `Retrieves full block data from the YAMO blockchain.
+
+Returns:
+- blockId: Unique block identifier
+- previousBlock: Content hash of parent block
+- agentAddress: Ethereum address of submitter
+- contentHash: 32-byte hash stored on-chain
+- timestamp: Block submission timestamp (Unix epoch)
+- consensusType: Consensus mechanism used
+- ledger: Distributed storage reference
+- ipfsCID: IPFS CID if content was anchored
+
+Use for:
+- Verifying block existence before submission
+- Getting previousBlock hash for chain continuation
+- Auditing block metadata
+- Exploring chain history`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            blockId: {
+                type: "string",
+                description: "Block ID to retrieve (e.g., 'aurora_weave', 'claude_chain')"
+            }
+        },
+        required: ["blockId"],
+    },
+};
+const AUDIT_BLOCK_TOOL = {
+    name: "yamo_audit_block",
+    description: `Performs cryptographic integrity audit of a block.
+
+**Audit Process:**
+1. Fetches block metadata from blockchain
+2. Downloads content from IPFS (if CID exists)
+3. Re-computes SHA-256 hash of downloaded content
+4. Compares computed hash vs on-chain hash
+5. Returns verification result with details
+
+**For Encrypted Blocks:**
+- Provide encryptionKey to decrypt before verification
+
+Returns detailed audit report including:
+- verified: true/false integrity check result
+- onChainHash: Hash stored on blockchain
+- computedHash: Hash computed from IPFS content
+- ipfsCID: IPFS content identifier
+- agentAddress: Submitter's Ethereum address
+- contentPreview: First 500 chars of content`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            blockId: {
+                type: "string",
+                description: "Block ID to audit (e.g., 'aurora_weave', 'claude_chain')"
+            },
+            encryptionKey: {
+                type: "string",
+                description: "Optional: Decryption key for encrypted bundles"
+            }
+        },
+        required: ["blockId"],
+    },
+};
 const VERIFY_BLOCK_TOOL = {
     name: "yamo_verify_block",
-    description: "Verifies a block's content hash.",
+    description: `Quick hash verification against on-chain record.
+
+**IMPORTANT:** This is a SIMPLE hash comparison, NOT a full content audit.
+It only checks if a provided hash matches what's stored on-chain.
+
+For full integrity verification (including IPFS content), use 'yamo_audit_block'.
+
+Returns:
+- "VERIFIED" if hash matches on-chain record
+- "FAILED" if hash does not match`,
     inputSchema: {
         type: "object",
         properties: {
-            blockId: { type: "string" },
-            contentHash: { type: "string" },
+            blockId: {
+                type: "string",
+                description: "Block ID to verify"
+            },
+            contentHash: {
+                type: "string",
+                pattern: "^0x[a-fA-F0-9]{64}$",
+                description: "32-byte hash to verify (0x + 64 hex chars)"
+            }
         },
         required: ["blockId", "contentHash"],
     },
@@ -83,14 +213,14 @@ class YamoMcpServer {
     ipfs;
     chain;
     constructor() {
-        this.server = new index_js_1.Server({ name: "yamo", version: "1.0.0" }, { capabilities: { tools: {} } });
+        this.server = new index_js_1.Server({ name: "yamo", version: pkg.version }, { capabilities: { tools: {} } });
         this.ipfs = new core_1.IpfsManager();
         this.chain = new core_1.YamoChainClient();
         this.setupHandlers();
     }
     setupHandlers() {
         this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
-            tools: [SUBMIT_BLOCK_TOOL, VERIFY_BLOCK_TOOL],
+            tools: [SUBMIT_BLOCK_TOOL, GET_BLOCK_TOOL, AUDIT_BLOCK_TOOL, VERIFY_BLOCK_TOOL],
         }));
         this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
@@ -103,7 +233,7 @@ class YamoMcpServer {
                         processedFiles = files.map((file) => {
                             // Check if content is a file path that exists
                             if (typeof file.content === 'string' && fs_1.default.existsSync(file.content)) {
-                                console.error(`Auto-reading file from path: ${file.content}`);
+                                console.error(`[DEBUG] Auto-reading file from path: ${file.content}`);
                                 return {
                                     name: file.name,
                                     content: fs_1.default.readFileSync(file.content, 'utf8')
@@ -123,9 +253,126 @@ class YamoMcpServer {
                     }
                     const txHash = await this.chain.submitBlock(blockId, previousBlock, contentHash, consensusType, ledger, ipfsCID);
                     return {
-                        content: [{ type: "text", text: `Block ${blockId} anchored. Tx: ${txHash}. IPFS: ${ipfsCID || "None"}` }],
+                        content: [{ type: "text", text: JSON.stringify({
+                                    success: true,
+                                    blockId,
+                                    transactionHash: txHash,
+                                    ipfsCID: ipfsCID || null
+                                }, null, 2) }],
+                    };
+                }
+                if (name === "yamo_get_block") {
+                    const { blockId } = args;
+                    const block = await this.chain.getBlock(blockId);
+                    if (!block) {
+                        return {
+                            content: [{ type: "text", text: JSON.stringify({
+                                        success: false,
+                                        error: "Block not found on-chain",
+                                        blockId,
+                                        hint: "Verify the blockId or check if the block was submitted"
+                                    }, null, 2) }],
+                            isError: false,
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({
+                                    success: true,
+                                    block: {
+                                        blockId: block.blockId,
+                                        previousBlock: block.previousBlock,
+                                        agentAddress: block.agentAddress,
+                                        contentHash: block.contentHash,
+                                        timestamp: block.timestamp,
+                                        timestampISO: new Date(block.timestamp * 1000).toISOString(),
+                                        consensusType: block.consensusType,
+                                        ledger: block.ledger,
+                                        ipfsCID: block.ipfsCID || null
+                                    }
+                                }, null, 2) }],
                     };
                 }
+                if (name === "yamo_audit_block") {
+                    const { blockId, encryptionKey } = args;
+                    // Get block from chain
+                    const block = await this.chain.getBlock(blockId);
+                    if (!block) {
+                        return {
+                            content: [{ type: "text", text: JSON.stringify({
+                                        verified: false,
+                                        error: "Block not found on-chain",
+                                        blockId,
+                                        hint: "Cannot audit non-existent block"
+                                    }, null, 2) }],
+                            isError: false,
+                        };
+                    }
+                    // If no IPFS CID, can't audit content
+                    if (!block.ipfsCID) {
+                        return {
+                            content: [{ type: "text", text: JSON.stringify({
+                                        verified: null, // Cannot verify without IPFS
+                                        onChainHash: block.contentHash,
+                                        ipfsCID: null,
+                                        note: "V1 block with no IPFS CID - cannot audit actual content",
+                                        blockId,
+                                        agentAddress: block.agentAddress,
+                                        timestamp: block.timestamp
+                                    }, null, 2) }],
+                        };
+                    }
+                    // Download and verify from IPFS
+                    try {
+                        const bundle = await this.ipfs.downloadBundle(block.ipfsCID, encryptionKey);
+                        const computedHash = "0x" + crypto_1.default.createHash("sha256").update(bundle.block).digest("hex");
+                        const verified = computedHash === block.contentHash;
+                        return {
+                            content: [{ type: "text", text: JSON.stringify({
+                                        verified,
+                                        blockId,
+                                        onChainHash: block.contentHash,
+                                        computedHash,
+                                        ipfsCID: block.ipfsCID,
+                                        agentAddress: block.agentAddress,
+                                        timestamp: block.timestamp,
+                                        timestampISO: new Date(block.timestamp * 1000).toISOString(),
+                                        consensusType: block.consensusType,
+                                        ledger: block.ledger,
+                                        contentPreview: bundle.block.substring(0, 500) + (bundle.block.length > 500 ? "..." : ""),
+                                        contentLength: bundle.block.length,
+                                        artifactFiles: Object.keys(bundle.files),
+                                        wasEncrypted: !!encryptionKey
+                                    }, null, 2) }],
+                        };
+                    }
+                    catch (error) {
+                        // Enhanced error messages
+                        let errorType = "unknown";
+                        let hint = "";
+                        if (error.message.includes("encrypted") && !encryptionKey) {
+                            errorType = "missing_key";
+                            hint = "This bundle is encrypted. Provide encryptionKey to audit.";
+                        }
+                        else if (error.message.includes("Decryption failed") || error.message.includes("decrypt")) {
+                            errorType = "decryption_failed";
+                            hint = "The provided encryption key may be incorrect.";
+                        }
+                        else if (error.message.includes("not found on-chain")) {
+                            errorType = "block_not_found";
+                            hint = "Verify the blockId was submitted correctly.";
+                        }
+                        return {
+                            content: [{ type: "text", text: JSON.stringify({
+                                        verified: false,
+                                        error: error.message,
+                                        errorType,
+                                        hint,
+                                        blockId
+                                    }, null, 2) }],
+                            isError: true,
+                        };
+                    }
+                }
                 if (name === "yamo_verify_block") {
                     const { blockId, contentHash } = args;
                     const contract = this.chain.getContract(false);
@@ -139,7 +386,12 @@ class YamoMcpServer {
             }
             catch (error) {
                 return {
-                    content: [{ type: "text", text: `Error: ${error.message}` }],
+                    content: [{ type: "text", text: JSON.stringify({
+                                success: false,
+                                error: error.message,
+                                tool: name,
+                                timestamp: new Date().toISOString()
+                            }, null, 2) }],
                     isError: true,
                 };
             }
@@ -148,7 +400,7 @@ class YamoMcpServer {
     async run() {
         const transport = new stdio_js_1.StdioServerTransport();
         await this.server.connect(transport);
-        console.error("YAMO MCP Server v1.0.0 running on stdio");
+        console.error(`YAMO MCP Server v${pkg.version} running on stdio`);
     }
 }
 const server = new YamoMcpServer();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamo/mcp-server",
-  "version": "1.0.4",
+  "version": "1.3.0",
   "description": "YAMO Protocol v0.4 - Model Context Protocol server for AI agents",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/",
+    "package.json",
     "README.md",
     "LICENSE"
   ],
@@ -42,7 +43,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@yamo/core": "^1.0.0",
+    "@yamo/core": "^1.1.0",
     "axios": "^1.13.2",
     "dotenv": "^17.2.3",
     "form-data": "^4.0.5"