@agentbadge/keeperhub
Advanced tools
KeeperHub MCP client, workflow templates, and tools for AgentBadge onchain trust integration
KeeperHub MCP client, workflow templates, and MCP tools for AgentBadge onchain trust integration on Base Sepolia.
@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:
connect, executeWorkflow, pollExecution, listWorkflows)recordScan, mintPassport, and notifykeeperhub-record-scan, keeperhub-mint-trust-badge, keeperhub-workflow-status, keeperhub-audit) that register into any MCP server┌─────────────────────────────────────────────────────────────────────┐
│ 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)
└─────────────────┘
npm install @agentbadge/keeperhub
# or
bun add @agentbadge/keeperhub
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();
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}`);
}
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));
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);
}
| 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> |
buildRecordScanWorkflow(opts) — agentbadge-record-scanRecords 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-passportMints 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-notifySends a notification (Discord/Slack/external) on scan events.
Trigger (Webhook) ──▶ webhook (send notification)
| 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 |
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.
┌────────┐ POST /scan ┌─────────┐ scanDomain() ┌──────────┐
│ Browser│─────────────────────▶│ Hono │──────────────────▶│ Scanner │
│ │ {url, confirm:false}│ Route │ │ (fetch + │
│ │ │ │◀──────────────────│ rules) │
│ │◀─────────────────────│ │ score, grade └──────────┘
│ │ {mode:"dry-run", │ │
│ │ scan, wouldExecute}│ │
└────────┘ └─────────┘
┌────────┐ 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 │ │
│ │◀─────────────────────────────────────────────────│ │
│ │ └──────────────┘
└────────┘
┌────────────┐ 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
└───────────────┘
┌──────────────┐ POST /audit/webhook ┌───────────────┐
│ KeeperHub │──{Authorization:Bearer}─▶│ Hono Route │
│ Server │ {source, siteUrl, │ │
│ (audit-cb │ score, executionId} │ validate │
│ node) │ │ secret │
└──────────────┘ │ │ │
│ ▼ │
│ AuditStore │
│ .add() │
│ → emit SSE │
└───────────────┘
| 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 |
| 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) |
MIT
FAQs
KeeperHub MCP client, workflow templates, and tools for AgentBadge onchain trust integration
We found that @agentbadge/keeperhub demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Agent Baseline’s new reference architecture shows how to secure software factories with four boundaries enforced outside the AI agent.
Security News
arXiv now limits authors to two submissions a month as AI slop overwhelms moderators, delays good papers, and sparks debate over applying the limit to everyone.
Research
/Security News
A new GhostAction wave hits hundreds of GitHub repos, expanding CI/CD secret theft to cloud and AI credentials in source code and git history.