@agentbadge/keeperhub

KeeperHub MCP client, workflow templates, and MCP tools for AgentBadge onchain trust integration on Base Sepolia.

Overview

@agentbadge/keeperhub is the SDK that connects AgentBadge to KeeperHub — a workflow automation platform that executes onchain transactions via MCP (Model Context Protocol).

The package provides three layers:

1. Client — typed MCP client for KeeperHub's workflow API (connect, executeWorkflow, pollExecution, listWorkflows)
2. Workflow Templates — pre-built workflow specs for recordScan, mintPassport, and notify
3. MCP Tools — 4 tool definitions (keeperhub-record-scan, keeperhub-mint-trust-badge, keeperhub-workflow-status, keeperhub-audit) that register into any MCP server

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        AgentBadge Server                             │
│                                                                     │
│  ┌──────────┐   ┌──────────────┐   ┌─────────────┐   ┌───────────┐  │
│  │  Hono    │   │ KeeperHub   │   │ AuditStore  │   │  SSE      │  │
│  │  Routes   │──▶│ Trigger     │──▶│ (in-memory) │──▶│  Stream   │  │
│  │          │   │ (MCP/webhook)│   │             │   │           │  │
│  └──────────┘   └──────┬───────┘   └─────────────┘   └───────────┘  │
│                        │                                            │
│                        ▼                                            │
│              ┌─────────────────┐                                    │
│              │ KeeperHubClient │  ◀── @agentbadge/keeperhub          │
│              │  (this package) │                                    │
│              └────────┬────────┘                                    │
└───────────────────────┼─────────────────────────────────────────────┘
                        │ MCP (Streamable HTTP)
                        ▼
              ┌─────────────────┐
              │  KeeperHub MCP  │
              │  app.keeperhub  │
              │  .com/mcp       │
              └────────┬────────┘
                       │ executes workflow
                       ▼
              ┌─────────────────┐
              │  Base Sepolia   │
              │  Chain ID 84532 │
              │                 │
              │  TrustRegistry  │──▶ recordScan(siteUrl, score, ...)
              │  TrustBadge     │──▶ mint(to, siteUrl, score, uri)
              │  AgentPassport  │──▶ mint(to, uri, tier)
              └─────────────────┘

Installation

npm install @agentbadge/keeperhub
# or
bun add @agentbadge/keeperhub

Quick Start

1. Connect to KeeperHub MCP

import { KeeperHubClient } from "@agentbadge/keeperhub";

const client = new KeeperHubClient({
  serverUrl: "https://app.keeperhub.com/mcp",
  apiKey: process.env.KEEPERHUB_API_KEY!,
});

await client.connect();
const workflows = await client.listWorkflows();

2. Provision Workflows

import { buildAllWorkflows } from "@agentbadge/keeperhub";

const specs = buildAllWorkflows({
  network: "84532",                    // Base Sepolia
  trustRegistryAddress: "0x...",
  trustBadgeAddress: "0x...",
  passportNftAddress: "0x...",
  auditCallbackUrl: "https://agentbadge.xyz/api/keeperhub/audit/webhook",
  auditCallbackSecret: process.env.KEEPERHUB_AUDIT_SECRET!,
  notifyUrl: "https://discord.com/api/webhooks/...",
  notifySecret: process.env.NOTIFY_SECRET,
});

for (const spec of specs) {
  const { workflowId } = await client.createWorkflow(spec);
  console.log(`Created: ${spec.name} → ${workflowId}`);
}

3. Execute a Workflow (record scan onchain)

const { executionId } = await client.executeWorkflow(workflowId, {
  siteUrl: "https://example.com",
  score: 92,
  rulesPassed: 139,
  rulesTotal: 151,
});

// Poll until terminal
const result = await client.pollExecution(executionId);
console.log("Status:", result.status);
console.log("Tx hashes:", client.txHashes(result));

4. Register MCP Tools

import { allKeeperhubTools } from "@agentbadge/keeperhub";

const ctx = {
  client: connectedClient,
  apiBaseUrl: "https://agentbadge.xyz",
  workflowIds: { recordScan: "wf_...", mintPassport: "wf_..." },
};

for (const tool of allKeeperhubTools) {
  const handler = tool.createHandler(ctx);
  server.registerTool(tool.name, tool.description, tool.inputSchema, handler);
}

API Reference

KeeperHubClient

| Method | Description | Returns | |--------|-------------|---------| | connect() | Establish MCP session | Promise<void> | | ping() | Test connectivity via list_workflows | Promise<boolean> | | listWorkflows() | List all workflows | Promise<unknown[]> | | createWorkflow(spec, opts?) | Create a new workflow | Promise<{ workflowId }> | | executeWorkflow(workflowId, inputs?, opts?) | Execute a workflow | Promise<{ executionId }> | | getExecution(executionId) | Get execution status | Promise<ExecutionResult> | | pollExecution(executionId, opts?) | Poll until terminal state | Promise<ExecutionResult> | | txHashes(exec) | Extract tx hashes from execution | string[] | | listActionSchemas(category?) | List available action schemas | Promise<unknown> | | getWalletIntegration() | Get wallet integration info | Promise<unknown> | | listWorkflow(workflowId, metadata) | List on marketplace | Promise<unknown> | | getWorkflowListing(slug) | Get marketplace listing | Promise<unknown> |

Workflow Templates

buildRecordScanWorkflow(opts) — agentbadge-record-scan

Records a site scan result onchain via TrustRegistry.recordScan(siteUrl, score, rulesPassed, rulesTotal).

Trigger (Webhook) ──▶ write-contract (TrustRegistry.recordScan) ──▶ webhook (audit callback)

buildMintPassportWorkflow(opts) — agentbadge-mint-passport

Mints an AgentPassport NFT + TrustBadge (soulbound) onchain, then sends audit callback.

Trigger (Webhook) ──▶ write-contract (AgentPassportNFT.mint) ──▶ write-contract (TrustBadge.mint) ──▶ webhook (audit callback)

buildNotifyWorkflow(opts) — agentbadge-notify

Sends a notification (Discord/Slack/external) on scan events.

Trigger (Webhook) ──▶ webhook (send notification)

MCP Tools

| Tool | Read-only | Description | |------|-----------|-------------| | keeperhub-record-scan | No | Dry-run preview or trigger onchain record-scan workflow | | keeperhub-mint-trust-badge | No | Dry-run preview or trigger onchain mint (passport + badge) workflow | | keeperhub-workflow-status | Yes | Read execution status by ID — returns state, tx hashes, errors | | keeperhub-audit | Yes | Fetch onchain audit records from AgentBadge API |

Validation

import { validateWorkflowSpec } from "@agentbadge/keeperhub";

const errors = validateWorkflowSpec(spec);
if (errors.length) throw new Error(`Invalid workflow: ${errors.map(e => e.message).join(", ")}`);

Checks: unique node IDs, exactly one trigger, edge references, required config fields, ABI format.

Flow Diagrams

Dry-Run Scan Flow

┌────────┐     POST /scan      ┌─────────┐    scanDomain()    ┌──────────┐
│ Browser│─────────────────────▶│  Hono   │──────────────────▶│  Scanner │
│        │  {url, confirm:false}│  Route  │                   │ (fetch + │
│        │                      │         │◀──────────────────│  rules)  │
│        │◀─────────────────────│         │   score, grade    └──────────┘
│        │  {mode:"dry-run",    │         │
│        │   scan, wouldExecute}│         │
└────────┘                      └─────────┘

Confirm → Onchain Record Flow

┌────────┐  POST /scan        ┌─────────┐  executeWorkflow()  ┌────────────┐
│ Browser│──{url,confirm:true}▶│  Hono   │───────────────────▶│ KeeperHub  │
│        │                     │  Route  │                    │ MCP Client │
│        │                     │         │  pollExecution()   │            │
│        │                     │         │◀──────────────────│            │
│        │                     │         │  ExecutionResult  └─────┬──────┘
│        │                     │         │                        │ MCP
│        │                     │         │                        ▼
│        │                     │         │                 ┌──────────────┐
│        │                     │  audit  │                 │ KeeperHub    │
│        │                     │  Store  │◀──webhook──────│ Server        │
│        │                     │  .add() │                 │ (executes    │
│        │                     │         │                 │  onchain tx) │
│        │◀─────────────────────│         │                 └──────┬───────┘
│        │ {mode:"executed",   │         │                        │
│        │  txHashes, execId}  │         │                        ▼
│        │                     └─────────┘                 ┌──────────────┐
│        │                                                 │ Base Sepolia │
│        │                                                 │ TrustRegistry│
│        │                          SSE audit event         │              │
│        │◀─────────────────────────────────────────────────│              │
│        │                                                 └──────────────┘
└────────┘

SSE Live Audit Trail

┌────────────┐    GET /audit/stream    ┌───────────────┐
│  Browser   │────────────────────────▶│  Hono Route   │
│  EventSource│                        │               │
│            │◀────event:snapshot──────│  send initial │
│            │◀────event:audit─────────│  then live     │
│            │     (on new event)      │  events        │
└────────────┘                         └───────┬───────┘
                                               │
                                       ┌───────▼───────┐
                                       │  AuditStore   │
                                       │  (EventEmitter)│
                                       │               │
                                       │  .add() ──▶ emit('event') ──▶ SSE push
                                       └───────────────┘

Webhook Receiver Flow

┌──────────────┐  POST /audit/webhook     ┌───────────────┐
│ KeeperHub    │──{Authorization:Bearer}─▶│  Hono Route   │
│ Server       │  {source, siteUrl,       │               │
│ (audit-cb    │   score, executionId}    │  validate     │
│  node)       │                          │  secret       │
└──────────────┘                          │       │       │
                                          │       ▼       │
                                          │  AuditStore   │
                                          │  .add()       │
                                          │  → emit SSE   │
                                          └───────────────┘

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | KEEPERHUB_ENABLED | No | false | Feature flag | | KEEPERHUB_API_KEY | Yes | — | Org API key from KeeperHub dashboard | | KEEPERHUB_SERVER_URL | No | https://app.keeperhub.com/mcp | MCP endpoint | | KEEPERHUB_WEBHOOK_KEY | Yes | — | Must start with wfb_ | | KEEPERHUB_AUDIT_SECRET | Yes | — | Bearer secret for webhook auth | | KEEPERHUB_WORKFLOW_RECORD_SCAN | Yes | — | Provisioned workflow ID | | KEEPERHUB_WORKFLOW_MINT_PASSPORT | Yes | — | Provisioned workflow ID | | KEEPERHUB_WORKFLOW_NOTIFY | No | — | Provisioned workflow ID | | KEEPERHUB_TRIGGER_MODE | No | mcp | mcp or webhook | | KEEPERHUB_X402_ENABLED | No | false | Enable x402 premium scans |

Smart Contracts (Base Sepolia)

| Contract | Purpose | Key Function | |----------|---------|--------------| | TrustRegistry | Records scan results onchain | recordScan(siteUrl, score, rulesPassed, rulesTotal) | | TrustBadge | Soulbound badge for verified sites | mint(to, siteUrl, score, uri) | | AgentPassportNFT | Agent identity NFT | mint(to, uri, tier) |

License

MIT