{"_id":"@agentbadge/keeperhub","name":"@agentbadge/keeperhub","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agentbadge/keeperhub","version":"0.1.0","description":"KeeperHub MCP client, workflow templates, and tools for AgentBadge onchain trust integration","type":"module","main":"dist/index.js","types":"dist/index.d.ts","author":{"name":"AgentBadge"},"license":"MIT","keywords":["keeperhub","mcp","model-context-protocol","agent","onchain","base"],"publishConfig":{"access":"public"},"engines":{"node":">=18"},"scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"vitest run --run","provision":"tsx scripts/provision.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","zod":"^4.0.0"},"devDependencies":{"@vitest/coverage-v8":"^2.0.0","bun-types":"^1.3.14","typescript":"^5.9.0","vitest":"^2.0.0","tsx":"^4.19.0"},"_id":"@agentbadge/keeperhub@0.1.0","gitHead":"b962f813f79aca6f97e07b1d2746f50bd00077a4","_nodeVersion":"23.3.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-Iwr7iaWZWT+W8MlyX5NLJtu8OqULGApT5d0x8SMhB8lhT3OPEhLBL0fdFIyMKN2jTsLHAn7EPlnYeUAv0qzosA==","shasum":"954381cad9fe04f13a2d6b1a9783be71d2ce5487","tarball":"https://registry.npmjs.org/@agentbadge/keeperhub/-/keeperhub-0.1.0.tgz","fileCount":32,"unpackedSize":51877,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBRg8KsqaIirXdsT+R7/l4Ao/IYbumINJoZH/GRSjsjUAiEAmOn2H0ahV7A+HA9xtfiVyG70au+cRpJzpTPasR8sRas="}]},"_npmUser":{"name":"spread-paul","email":"spread2009@gmail.com"},"directories":{},"maintainers":[{"name":"spread-paul","email":"spread2009@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/keeperhub_0.1.0_1789032112851_0.05808753201156591"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-10T09:21:52.556Z","0.1.0":"2026-09-10T09:21:52.979Z","modified":"2026-09-10T09:21:53.402Z"},"maintainers":[{"name":"spread-paul","email":"spread2009@gmail.com"}],"description":"KeeperHub MCP client, workflow templates, and tools for AgentBadge onchain trust integration","keywords":["keeperhub","mcp","model-context-protocol","agent","onchain","base"],"author":{"name":"AgentBadge"},"license":"MIT","readme":"# @agentbadge/keeperhub\n\n> KeeperHub MCP client, workflow templates, and MCP tools for AgentBadge onchain trust integration on Base Sepolia.\n\n## Overview\n\n`@agentbadge/keeperhub` is the SDK that connects [AgentBadge](https://agentbadge.xyz) to [KeeperHub](https://app.keeperhub.com) — a workflow automation platform that executes onchain transactions via MCP (Model Context Protocol).\n\nThe package provides three layers:\n\n1. **Client** — typed MCP client for KeeperHub's workflow API (`connect`, `executeWorkflow`, `pollExecution`, `listWorkflows`)\n2. **Workflow Templates** — pre-built workflow specs for `recordScan`, `mintPassport`, and `notify`\n3. **MCP Tools** — 4 tool definitions (`keeperhub-record-scan`, `keeperhub-mint-trust-badge`, `keeperhub-workflow-status`, `keeperhub-audit`) that register into any MCP server\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        AgentBadge Server                             │\n│                                                                     │\n│  ┌──────────┐   ┌──────────────┐   ┌─────────────┐   ┌───────────┐  │\n│  │  Hono    │   │ KeeperHub   │   │ AuditStore  │   │  SSE      │  │\n│  │  Routes   │──▶│ Trigger     │──▶│ (in-memory) │──▶│  Stream   │  │\n│  │          │   │ (MCP/webhook)│   │             │   │           │  │\n│  └──────────┘   └──────┬───────┘   └─────────────┘   └───────────┘  │\n│                        │                                            │\n│                        ▼                                            │\n│              ┌─────────────────┐                                    │\n│              │ KeeperHubClient │  ◀── @agentbadge/keeperhub          │\n│              │  (this package) │                                    │\n│              └────────┬────────┘                                    │\n└───────────────────────┼─────────────────────────────────────────────┘\n                        │ MCP (Streamable HTTP)\n                        ▼\n              ┌─────────────────┐\n              │  KeeperHub MCP  │\n              │  app.keeperhub  │\n              │  .com/mcp       │\n              └────────┬────────┘\n                       │ executes workflow\n                       ▼\n              ┌─────────────────┐\n              │  Base Sepolia   │\n              │  Chain ID 84532 │\n              │                 │\n              │  TrustRegistry  │──▶ recordScan(siteUrl, score, ...)\n              │  TrustBadge     │──▶ mint(to, siteUrl, score, uri)\n              │  AgentPassport  │──▶ mint(to, uri, tier)\n              └─────────────────┘\n```\n\n## Installation\n\n```bash\nnpm install @agentbadge/keeperhub\n# or\nbun add @agentbadge/keeperhub\n```\n\n## Quick Start\n\n### 1. Connect to KeeperHub MCP\n\n```typescript\nimport { KeeperHubClient } from \"@agentbadge/keeperhub\";\n\nconst client = new KeeperHubClient({\n  serverUrl: \"https://app.keeperhub.com/mcp\",\n  apiKey: process.env.KEEPERHUB_API_KEY!,\n});\n\nawait client.connect();\nconst workflows = await client.listWorkflows();\n```\n\n### 2. Provision Workflows\n\n```typescript\nimport { buildAllWorkflows } from \"@agentbadge/keeperhub\";\n\nconst specs = buildAllWorkflows({\n  network: \"84532\",                    // Base Sepolia\n  trustRegistryAddress: \"0x...\",\n  trustBadgeAddress: \"0x...\",\n  passportNftAddress: \"0x...\",\n  auditCallbackUrl: \"https://agentbadge.xyz/api/keeperhub/audit/webhook\",\n  auditCallbackSecret: process.env.KEEPERHUB_AUDIT_SECRET!,\n  notifyUrl: \"https://discord.com/api/webhooks/...\",\n  notifySecret: process.env.NOTIFY_SECRET,\n});\n\nfor (const spec of specs) {\n  const { workflowId } = await client.createWorkflow(spec);\n  console.log(`Created: ${spec.name} → ${workflowId}`);\n}\n```\n\n### 3. Execute a Workflow (record scan onchain)\n\n```typescript\nconst { executionId } = await client.executeWorkflow(workflowId, {\n  siteUrl: \"https://example.com\",\n  score: 92,\n  rulesPassed: 139,\n  rulesTotal: 151,\n});\n\n// Poll until terminal\nconst result = await client.pollExecution(executionId);\nconsole.log(\"Status:\", result.status);\nconsole.log(\"Tx hashes:\", client.txHashes(result));\n```\n\n### 4. Register MCP Tools\n\n```typescript\nimport { allKeeperhubTools } from \"@agentbadge/keeperhub\";\n\nconst ctx = {\n  client: connectedClient,\n  apiBaseUrl: \"https://agentbadge.xyz\",\n  workflowIds: { recordScan: \"wf_...\", mintPassport: \"wf_...\" },\n};\n\nfor (const tool of allKeeperhubTools) {\n  const handler = tool.createHandler(ctx);\n  server.registerTool(tool.name, tool.description, tool.inputSchema, handler);\n}\n```\n\n## API Reference\n\n### KeeperHubClient\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `connect()` | Establish MCP session | `Promise<void>` |\n| `ping()` | Test connectivity via `list_workflows` | `Promise<boolean>` |\n| `listWorkflows()` | List all workflows | `Promise<unknown[]>` |\n| `createWorkflow(spec, opts?)` | Create a new workflow | `Promise<{ workflowId }>` |\n| `executeWorkflow(workflowId, inputs?, opts?)` | Execute a workflow | `Promise<{ executionId }>` |\n| `getExecution(executionId)` | Get execution status | `Promise<ExecutionResult>` |\n| `pollExecution(executionId, opts?)` | Poll until terminal state | `Promise<ExecutionResult>` |\n| `txHashes(exec)` | Extract tx hashes from execution | `string[]` |\n| `listActionSchemas(category?)` | List available action schemas | `Promise<unknown>` |\n| `getWalletIntegration()` | Get wallet integration info | `Promise<unknown>` |\n| `listWorkflow(workflowId, metadata)` | List on marketplace | `Promise<unknown>` |\n| `getWorkflowListing(slug)` | Get marketplace listing | `Promise<unknown>` |\n\n### Workflow Templates\n\n#### `buildRecordScanWorkflow(opts)` — `agentbadge-record-scan`\n\nRecords a site scan result onchain via `TrustRegistry.recordScan(siteUrl, score, rulesPassed, rulesTotal)`.\n\n```\nTrigger (Webhook) ──▶ write-contract (TrustRegistry.recordScan) ──▶ webhook (audit callback)\n```\n\n#### `buildMintPassportWorkflow(opts)` — `agentbadge-mint-passport`\n\nMints an AgentPassport NFT + TrustBadge (soulbound) onchain, then sends audit callback.\n\n```\nTrigger (Webhook) ──▶ write-contract (AgentPassportNFT.mint) ──▶ write-contract (TrustBadge.mint) ──▶ webhook (audit callback)\n```\n\n#### `buildNotifyWorkflow(opts)` — `agentbadge-notify`\n\nSends a notification (Discord/Slack/external) on scan events.\n\n```\nTrigger (Webhook) ──▶ webhook (send notification)\n```\n\n### MCP Tools\n\n| Tool | Read-only | Description |\n|------|-----------|-------------|\n| `keeperhub-record-scan` | No | Dry-run preview or trigger onchain record-scan workflow |\n| `keeperhub-mint-trust-badge` | No | Dry-run preview or trigger onchain mint (passport + badge) workflow |\n| `keeperhub-workflow-status` | Yes | Read execution status by ID — returns state, tx hashes, errors |\n| `keeperhub-audit` | Yes | Fetch onchain audit records from AgentBadge API |\n\n### Validation\n\n```typescript\nimport { validateWorkflowSpec } from \"@agentbadge/keeperhub\";\n\nconst errors = validateWorkflowSpec(spec);\nif (errors.length) throw new Error(`Invalid workflow: ${errors.map(e => e.message).join(\", \")}`);\n```\n\nChecks: unique node IDs, exactly one trigger, edge references, required config fields, ABI format.\n\n## Flow Diagrams\n\n### Dry-Run Scan Flow\n\n```\n┌────────┐     POST /scan      ┌─────────┐    scanDomain()    ┌──────────┐\n│ Browser│─────────────────────▶│  Hono   │──────────────────▶│  Scanner │\n│        │  {url, confirm:false}│  Route  │                   │ (fetch + │\n│        │                      │         │◀──────────────────│  rules)  │\n│        │◀─────────────────────│         │   score, grade    └──────────┘\n│        │  {mode:\"dry-run\",    │         │\n│        │   scan, wouldExecute}│         │\n└────────┘                      └─────────┘\n```\n\n### Confirm → Onchain Record Flow\n\n```\n┌────────┐  POST /scan        ┌─────────┐  executeWorkflow()  ┌────────────┐\n│ Browser│──{url,confirm:true}▶│  Hono   │───────────────────▶│ KeeperHub  │\n│        │                     │  Route  │                    │ MCP Client │\n│        │                     │         │  pollExecution()   │            │\n│        │                     │         │◀──────────────────│            │\n│        │                     │         │  ExecutionResult  └─────┬──────┘\n│        │                     │         │                        │ MCP\n│        │                     │         │                        ▼\n│        │                     │         │                 ┌──────────────┐\n│        │                     │  audit  │                 │ KeeperHub    │\n│        │                     │  Store  │◀──webhook──────│ Server        │\n│        │                     │  .add() │                 │ (executes    │\n│        │                     │         │                 │  onchain tx) │\n│        │◀─────────────────────│         │                 └──────┬───────┘\n│        │ {mode:\"executed\",   │         │                        │\n│        │  txHashes, execId}  │         │                        ▼\n│        │                     └─────────┘                 ┌──────────────┐\n│        │                                                 │ Base Sepolia │\n│        │                                                 │ TrustRegistry│\n│        │                          SSE audit event         │              │\n│        │◀─────────────────────────────────────────────────│              │\n│        │                                                 └──────────────┘\n└────────┘\n```\n\n### SSE Live Audit Trail\n\n```\n┌────────────┐    GET /audit/stream    ┌───────────────┐\n│  Browser   │────────────────────────▶│  Hono Route   │\n│  EventSource│                        │               │\n│            │◀────event:snapshot──────│  send initial │\n│            │◀────event:audit─────────│  then live     │\n│            │     (on new event)      │  events        │\n└────────────┘                         └───────┬───────┘\n                                               │\n                                       ┌───────▼───────┐\n                                       │  AuditStore   │\n                                       │  (EventEmitter)│\n                                       │               │\n                                       │  .add() ──▶ emit('event') ──▶ SSE push\n                                       └───────────────┘\n```\n\n### Webhook Receiver Flow\n\n```\n┌──────────────┐  POST /audit/webhook     ┌───────────────┐\n│ KeeperHub    │──{Authorization:Bearer}─▶│  Hono Route   │\n│ Server       │  {source, siteUrl,       │               │\n│ (audit-cb    │   score, executionId}    │  validate     │\n│  node)       │                          │  secret       │\n└──────────────┘                          │       │       │\n                                          │       ▼       │\n                                          │  AuditStore   │\n                                          │  .add()       │\n                                          │  → emit SSE   │\n                                          └───────────────┘\n```\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `KEEPERHUB_ENABLED` | No | `false` | Feature flag |\n| `KEEPERHUB_API_KEY` | Yes | — | Org API key from KeeperHub dashboard |\n| `KEEPERHUB_SERVER_URL` | No | `https://app.keeperhub.com/mcp` | MCP endpoint |\n| `KEEPERHUB_WEBHOOK_KEY` | Yes | — | Must start with `wfb_` |\n| `KEEPERHUB_AUDIT_SECRET` | Yes | — | Bearer secret for webhook auth |\n| `KEEPERHUB_WORKFLOW_RECORD_SCAN` | Yes | — | Provisioned workflow ID |\n| `KEEPERHUB_WORKFLOW_MINT_PASSPORT` | Yes | — | Provisioned workflow ID |\n| `KEEPERHUB_WORKFLOW_NOTIFY` | No | — | Provisioned workflow ID |\n| `KEEPERHUB_TRIGGER_MODE` | No | `mcp` | `mcp` or `webhook` |\n| `KEEPERHUB_X402_ENABLED` | No | `false` | Enable x402 premium scans |\n\n## Smart Contracts (Base Sepolia)\n\n| Contract | Purpose | Key Function |\n|----------|---------|--------------|\n| `TrustRegistry` | Records scan results onchain | `recordScan(siteUrl, score, rulesPassed, rulesTotal)` |\n| `TrustBadge` | Soulbound badge for verified sites | `mint(to, siteUrl, score, uri)` |\n| `AgentPassportNFT` | Agent identity NFT | `mint(to, uri, tier)` |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-ac2db069ac583572303c6f47ab70aa5a"}