@upoch/guard 0.1.0 → 0.1.2

package/README.md

@@ -6,9 +6,15 @@ Upoch Guard saves verifiable checkpoints of an agent's work on Robinhood Chain.
 prompt or makes a bad trade, it restores the last good state, checked against the chain, or rolls back to the
 checkpoint before the mistake and keeps going. It also knows which of its actions already happened.
 
-This package is the `upoch` command you set Upoch up with, and the engine behind the Upoch framework plugins:
+This package is the `upoch` command you set Upoch up with, an MCP server, and the engine behind the Upoch
+framework plugins:
 
-- **ElizaOS**: [@upoch/plugin-elizaos](https://www.npmjs.com/package/@upoch/plugin-elizaos)
+| Agent | One line |
+|---|---|
+| Claude Code | `claude mcp add upoch -- upoch mcp` |
+| Cursor, Codex, Claude Desktop, any MCP client | an MCP server with the command `upoch mcp` (stdio) |
+| ElizaOS | `plugins: ["@upoch/plugin-elizaos"]` in your character ([@upoch/plugin-elizaos](https://www.npmjs.com/package/@upoch/plugin-elizaos)) |
+| LangChain / LangGraph | `callbacks: [new UpochCallbackHandler()]` ([@upoch/langchain](https://www.npmjs.com/package/@upoch/langchain)) |
 
 Website and debugger: https://upoch.tech. Contract (Robinhood Chain, 4663): `0x6179d9123c3c1f9e82f948101a4350cb55aa8c27`
 
@@ -22,8 +28,8 @@ upoch setup
 ```
 
 `upoch setup` creates your keys in `~/.upoch`, shows the owner address, and waits while you send it a little ETH on
-Robinhood Chain (0.001 ETH is plenty). Then it registers your agent. After that, connecting an agent is one line,
-for example `plugins: ["@upoch/plugin-elizaos"]` in an ElizaOS character.
+Robinhood Chain (0.001 ETH is plenty). Then it registers your agent and, if Claude Code is installed, offers to
+add the MCP server to it. After that, connecting an agent is one line (table above).
 
 Prefer separate steps? Run `upoch init`, then `upoch register`.
 
@@ -42,10 +48,28 @@ Two keys are created on your machine and never leave it:
 A rollback restores the agent's state and memory. It cannot reverse transactions that already happened on-chain;
 those are listed so the agent can account for them.
 
+## MCP tools
+
+| Tool | What it does | On-chain |
+|---|---|---|
+| `upoch_restore` | Restores the latest checkpoint after verifying it: state, note, completed and unresolved actions | read |
+| `upoch_checkpoint` | Saves the current state as a checkpoint (`progress`, `before_action`, `after_action`, `manual`) | 1 transaction |
+| `upoch_record_action` | Records an external action (planned, submitted, confirmed, failed) with its transaction hash | no (goes into the next checkpoint) |
+| `upoch_rollback` | Goes back to an earlier checkpoint (e.g. before a bad trade) and continues from it; lists actions since then that were not undone on-chain | 1 transaction |
+| `upoch_complete` | Saves a final checkpoint and marks the run finished | 1 transaction |
+| `upoch_history` | Lists recent checkpoints | read |
+| `upoch_verify` | Verifies one checkpoint without restoring it | read |
+| `upoch_status` | Shows the workflow, executor funds and today's usage | read |
+
+The server tells the agent when to use them: restore at the start, checkpoint after meaningful progress and before
+consequential actions, record each action as planned and then as confirmed, roll back when something went wrong,
+and complete at the end.
+
 ## Commands
 
 ```sh
 upoch setup          # keys, funding, registration, in one go
+upoch mcp            # run the MCP server (stdio); your MCP client starts it
 upoch status         # workflow, funds and today's usage
 upoch key            # print the checkpoint key, to open checkpoints in the debugger
 upoch export-owner   # print the owner private key, to import it into a wallet

package/dist/cli.js

@@ -4,7 +4,7 @@
 //   upoch init           create keys and settings (your terminal only)
 //   upoch register       register the agent's workflow on-chain and fund its executor (your terminal only)
 //   upoch status         show the workflow, funds and usage
-//   upoch mcp            run the MCP server (stdio) for Claude Code, Cursor, Codex and other MCP clients (see LAUNCHED)
+//   upoch mcp            run the MCP server (stdio) for Claude Code, Cursor, Codex and other MCP clients
 //   upoch key            print the checkpoint key, to open checkpoints in the debugger (your terminal only)
 //   upoch export-owner   print the owner private key, to import it into a wallet (your terminal only)
 import { spawnSync } from "node:child_process";
@@ -16,11 +16,8 @@ import { hasSetup, loadConfig, loadSecrets, networkInfo, upochHome } from "./con
 import { Guard } from "./guard.js";
 import { createServer, VERSION } from "./server.js";
 import { initialize, register, registrationPlan } from "./setup.js";
-/**
- * Integrations announced so far. The MCP server (`upoch mcp`) and LangChain already work; help and setup output list
- * them only once they launch. Flip these at launch.
- */
-const LAUNCHED = { mcp: false, langchain: false };
+/** Integrations listed in help and setup output. */
+const LAUNCHED = { mcp: true, langchain: true };
 const CONNECT = [
     ...(LAUNCHED.mcp ? ["  Claude Code     claude mcp add upoch -- upoch mcp", "  Cursor, Codex   add an MCP server with the command: upoch mcp"] : []),
     '  ElizaOS         plugins: ["@upoch/plugin-elizaos"] in your character',

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { Guard } from "./guard.ts";
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.1.2";
 export declare const INSTRUCTIONS = "Upoch Guard saves verifiable checkpoints of your work on Robinhood Chain, so a crash, a bad prompt or a bad trade can be recovered from the last good state.\n\nWhen to use it:\n- At the start of a task, call upoch_restore. If a run was interrupted, continue from the returned state and do not repeat its completed actions.\n- After meaningful progress, call upoch_checkpoint with the state you would need to continue (plan, step, positions, results so far). Not after every small step: each checkpoint is an on-chain transaction.\n- Before a consequential external action (a swap, a transfer, a deployment), call upoch_record_action with status \"planned\" and then upoch_checkpoint with kind \"before_action\". After it settles, record it again as \"confirmed\" (with its transaction hash) or \"failed\".\n- If something went wrong (a bad trade, a bad instruction, corrupted state), use upoch_history to find the last good checkpoint and upoch_rollback to go back to it and continue. Rolling back restores your state; it does not undo on-chain transactions, so check the actions it lists.\n- When the task is finished, call upoch_complete.\n\nNever put private keys, seed phrases, passwords or API tokens in the state, notes or actions: checkpoints are permanent. Upoch refuses state that looks like it contains them. Setup (keys, registration, funding) is done by the user in their own terminal with the upoch command; never run \"upoch init\", \"upoch register\", \"upoch key\" or \"upoch export-owner\" yourself.";
 export declare function createServer(guard: Guard | (() => Guard)): McpServer;

package/dist/server.js

@@ -3,7 +3,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { Guard, GuardError } from "./guard.js";
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.2";
 export const INSTRUCTIONS = `Upoch Guard saves verifiable checkpoints of your work on Robinhood Chain, so a crash, a bad prompt or a bad trade can be recovered from the last good state.
 
 When to use it:

package/dist/setup.js

@@ -46,7 +46,7 @@ function clients(config, key, provider) {
     return { n, account, pub: createPublicClient({ chain, transport }), wallet: createWalletClient({ chain, transport, account }) };
 }
 function metadataURI(config) {
-    const json = JSON.stringify({ name: config.agentName, agentType: "MCP agent (Upoch Guard)", description: `Checkpointed with Upoch Guard. Agent id ${config.agentId}.` });
+    const json = JSON.stringify({ name: config.agentName, agentType: "AI agent (Upoch Guard)", description: `Checkpointed with Upoch Guard. Agent id ${config.agentId}.` });
     const uri = `data:application/json;base64,${Buffer.from(json).toString("base64")}`;
     if (uri.length > 512)
         throw new Error("the agent name is too long for the on-chain metadata (512 bytes)");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@upoch/guard",
-  "version": "0.1.0",
-  "description": "Upoch Guard: verifiable checkpoints, recovery and rollback for AI agents on Robinhood Chain. The upoch command and the engine behind the Upoch framework plugins.",
+  "version": "0.1.2",
+  "description": "Upoch Guard: verifiable checkpoints, recovery and rollback for AI agents on Robinhood Chain. The upoch command, an MCP server for Claude Code, Cursor and Codex, and the engine behind the Upoch plugins for ElizaOS and LangChain.",
   "keywords": [
     "upoch",
     "ai-agents",
@@ -9,13 +9,16 @@
     "recovery",
     "rollback",
     "robinhood-chain",
-    "elizaos"
+    "elizaos",
+    "langchain",
+    "mcp",
+    "model-context-protocol"
   ],
   "homepage": "https://upoch.tech/docs",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "upoch": "./dist/cli.js"
+    "upoch": "dist/cli.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",