@rickydata/agent0-mcp 0.1.0

package/src/tools/registration.ts

@@ -0,0 +1,389 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import {
+  getAuthenticatedSDK,
+  hasAuthentication,
+  getAuthStatus,
+  setDerivedKey,
+  setChainId,
+} from "../auth/sdk-client.js";
+import {
+  getDerivationMessage,
+  deriveWalletFromSignature,
+  verifyDerivationSignature,
+} from "../auth/wallet-derivation.js";
+import { getChainName } from "../utils/chains.js";
+
+export const registrationTools: Tool[] = [
+  {
+    name: "configure_wallet",
+    description:
+      "Configure wallet for ERC-8004 write operations (register, feedback, etc.). " +
+      "Provide either a private key directly OR a wallet signature for key derivation. " +
+      "Also sets the target chain. Must be called before any write operation.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        privateKey: {
+          type: "string",
+          description:
+            "Hex private key (0x-prefixed). Use this if you have a dedicated agent key.",
+        },
+        signature: {
+          type: "string",
+          description:
+            "Wallet signature of the derivation message (from personal_sign). " +
+            "Use get_derivation_message first, then sign it with your wallet.",
+        },
+        signerAddress: {
+          type: "string",
+          description:
+            "The wallet address that produced the signature (for verification).",
+        },
+        chainId: {
+          type: "number",
+          description:
+            "Target chain ID (default: 11155111 Sepolia). Use 1 for Ethereum Mainnet, 8453 for Base.",
+        },
+      },
+    },
+  },
+  {
+    name: "get_derivation_message",
+    description:
+      "Get the message that must be signed with your wallet to derive an ERC-8004 agent key. " +
+      "Sign this message with personal_sign, then pass the signature to configure_wallet.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {},
+    },
+  },
+  {
+    name: "get_auth_status",
+    description:
+      "Check if a wallet is configured for write operations. " +
+      "Shows key source, chain ID, and whether the SDK is in read-only mode.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {},
+    },
+  },
+  {
+    name: "register_agent",
+    description:
+      "Register a new AI agent on-chain via ERC-8004. Requires configured wallet. " +
+      "Creates the agent with name, description, endpoints, and capabilities. " +
+      "Returns the on-chain agent ID and URI.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        name: {
+          type: "string",
+          description: "Agent name",
+        },
+        description: {
+          type: "string",
+          description: "Agent description",
+        },
+        image: {
+          type: "string",
+          description: "Agent image URL (optional)",
+        },
+        mcpEndpoint: {
+          type: "string",
+          description: "MCP server endpoint URL (optional)",
+        },
+        a2aEndpoint: {
+          type: "string",
+          description: "A2A agent card URL (optional)",
+        },
+        active: {
+          type: "boolean",
+          description: "Set agent as active (default: true)",
+        },
+        x402support: {
+          type: "boolean",
+          description: "Agent supports x402 payments (default: false)",
+        },
+        trustReputation: {
+          type: "boolean",
+          description: "Enable reputation trust model (default: true)",
+        },
+        trustCryptoEconomic: {
+          type: "boolean",
+          description: "Enable crypto-economic trust model (default: false)",
+        },
+        trustTEE: {
+          type: "boolean",
+          description: "Enable TEE attestation trust model (default: false)",
+        },
+        metadata: {
+          type: "object",
+          description: "Additional metadata key-value pairs",
+        },
+        registrationMethod: {
+          type: "string",
+          enum: ["ipfs", "onchain"],
+          description:
+            "Registration method: 'ipfs' (default, stores on IPFS) or 'onchain' (data URI, higher gas)",
+        },
+      },
+      required: ["name", "description"],
+    },
+  },
+  {
+    name: "update_agent",
+    description:
+      "Update an existing agent's properties (description, endpoints, metadata). " +
+      "Requires configured wallet and agent ownership.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agentId: {
+          type: "string",
+          description: "Agent ID in chainId:tokenId format",
+        },
+        description: {
+          type: "string",
+          description: "Updated description",
+        },
+        image: {
+          type: "string",
+          description: "Updated image URL",
+        },
+        mcpEndpoint: {
+          type: "string",
+          description: "Updated MCP endpoint",
+        },
+        a2aEndpoint: {
+          type: "string",
+          description: "Updated A2A endpoint",
+        },
+        active: {
+          type: "boolean",
+          description: "Set agent active/inactive",
+        },
+        metadata: {
+          type: "object",
+          description: "Metadata to merge (key-value pairs)",
+        },
+      },
+      required: ["agentId"],
+    },
+  },
+];
+
+// ============================================================================
+// HANDLERS
+// ============================================================================
+
+function requireAuth(): { sdk: ReturnType<typeof getAuthenticatedSDK>; error?: string } {
+  if (!hasAuthentication()) {
+    return {
+      sdk: null,
+      error:
+        "No wallet configured. Call configure_wallet first with a private key or signature.",
+    };
+  }
+  const sdk = getAuthenticatedSDK();
+  if (!sdk) {
+    return { sdk: null, error: "Failed to initialize authenticated SDK." };
+  }
+  return { sdk };
+}
+
+async function handleConfigureWallet(
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  // Set chain if provided
+  if (args.chainId) {
+    setChainId(args.chainId as number);
+  }
+
+  if (args.privateKey) {
+    // Direct private key
+    const key = args.privateKey as string;
+    if (!key.startsWith("0x") || key.length !== 66) {
+      return { error: "Invalid private key format. Must be 0x-prefixed 32-byte hex." };
+    }
+    setDerivedKey(key);
+    const status = getAuthStatus();
+    return {
+      success: true,
+      method: "direct_key",
+      chainId: status.chainId,
+      chain: getChainName(status.chainId),
+    };
+  }
+
+  if (args.signature) {
+    const signature = args.signature as string;
+    const signerAddress = args.signerAddress as string | undefined;
+
+    // Verify signature if address provided
+    if (signerAddress) {
+      const valid = verifyDerivationSignature(signature, signerAddress);
+      if (!valid) {
+        return {
+          error: `Signature verification failed. The signature was not produced by ${signerAddress}.`,
+        };
+      }
+    }
+
+    // Derive key from signature
+    const derived = deriveWalletFromSignature(signature);
+    setDerivedKey(derived.privateKey);
+
+    const status = getAuthStatus();
+    return {
+      success: true,
+      method: "derived_from_signature",
+      derivedAddress: derived.address,
+      chainId: status.chainId,
+      chain: getChainName(status.chainId),
+      note: "Derived address is your ERC-8004 agent identity. It is deterministic from your wallet signature.",
+    };
+  }
+
+  // No key or signature — just set chain
+  if (args.chainId) {
+    return {
+      success: true,
+      method: "chain_only",
+      chainId: args.chainId,
+      chain: getChainName(args.chainId as number),
+      note: "Chain updated. No signing key configured — read-only mode.",
+    };
+  }
+
+  return {
+    error:
+      "Provide either privateKey or signature. Use get_derivation_message to get the message to sign.",
+  };
+}
+
+async function handleRegisterAgent(
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const { sdk, error } = requireAuth();
+  if (error || !sdk) return { error };
+
+  const agent = sdk.createAgent(
+    args.name as string,
+    args.description as string,
+    (args.image as string) ?? undefined,
+  );
+
+  // Configure endpoints
+  if (args.mcpEndpoint) {
+    await agent.setMCP(args.mcpEndpoint as string);
+  }
+  if (args.a2aEndpoint) {
+    await agent.setA2A(args.a2aEndpoint as string);
+  }
+
+  // Trust models
+  agent.setTrust(
+    (args.trustReputation as boolean) ?? true,
+    (args.trustCryptoEconomic as boolean) ?? false,
+    (args.trustTEE as boolean) ?? false,
+  );
+
+  // Active status
+  agent.setActive((args.active as boolean) ?? true);
+
+  // Metadata
+  if (args.metadata) {
+    agent.setMetadata(args.metadata as Record<string, unknown>);
+  }
+
+  // Register
+  const method = (args.registrationMethod as string) ?? "ipfs";
+  const tx =
+    method === "onchain"
+      ? await agent.registerOnChain()
+      : await agent.registerIPFS();
+  const mined = await tx.waitConfirmed({ timeoutMs: 180_000 });
+  const regFile = mined.result;
+
+  return {
+    success: true,
+    agentId: regFile.agentId,
+    agentURI: regFile.agentURI,
+    txHash: mined.receipt.transactionHash,
+    method,
+    chain: getChainName(await sdk.chainId()),
+  };
+}
+
+async function handleUpdateAgent(
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const { sdk, error } = requireAuth();
+  if (error || !sdk) return { error };
+
+  const agentId = args.agentId as string;
+  if (!agentId) return { error: "agentId is required" };
+
+  const agent = await sdk.loadAgent(agentId);
+
+  if (args.description !== undefined) {
+    agent.updateInfo(undefined, args.description as string, undefined);
+  }
+  if (args.image !== undefined) {
+    agent.updateInfo(undefined, undefined, args.image as string);
+  }
+  if (args.mcpEndpoint) {
+    await agent.setMCP(args.mcpEndpoint as string);
+  }
+  if (args.a2aEndpoint) {
+    await agent.setA2A(args.a2aEndpoint as string);
+  }
+  if (args.active !== undefined) {
+    agent.setActive(args.active as boolean);
+  }
+  if (args.metadata) {
+    agent.setMetadata(args.metadata as Record<string, unknown>);
+  }
+
+  // Re-register to update
+  const tx = await agent.registerIPFS();
+  const mined = await tx.waitConfirmed({ timeoutMs: 180_000 });
+  const regFile = mined.result;
+
+  return {
+    success: true,
+    agentId,
+    agentURI: regFile.agentURI,
+    txHash: mined.receipt.transactionHash,
+    chain: getChainName(await sdk.chainId()),
+  };
+}
+
+// ============================================================================
+// DISPATCH
+// ============================================================================
+
+export async function handleRegistrationTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  switch (name) {
+    case "configure_wallet":
+      return handleConfigureWallet(args);
+    case "get_derivation_message":
+      return {
+        message: getDerivationMessage(),
+        instructions:
+          "Sign this message with personal_sign using your wallet, " +
+          "then pass the signature to configure_wallet.",
+      };
+    case "get_auth_status":
+      return getAuthStatus();
+    case "register_agent":
+      return handleRegisterAgent(args);
+    case "update_agent":
+      return handleUpdateAgent(args);
+    default:
+      return { error: `Unknown registration tool: ${name}` };
+  }
+}

package/src/tools/reputation.ts

@@ -0,0 +1,183 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { FeedbackFileInput } from "agent0-sdk";
+import {
+  getAuthenticatedSDK,
+  hasAuthentication,
+} from "../auth/sdk-client.js";
+import { getChainName } from "../utils/chains.js";
+
+export const reputationTools: Tool[] = [
+  {
+    name: "give_feedback",
+    description:
+      "Submit on-chain feedback/review for an ERC-8004 agent. Requires configured wallet. " +
+      "Creates a permanent, verifiable review with a score (0-100), tags, and optional text.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agentId: {
+          type: "string",
+          description: "Agent ID in chainId:tokenId format (e.g. '11155111:42')",
+        },
+        value: {
+          type: "number",
+          description: "Feedback score from 0 (worst) to 100 (best)",
+        },
+        tag1: {
+          type: "string",
+          description: "Primary tag (e.g. 'quality', 'reliability', 'enterprise')",
+        },
+        tag2: {
+          type: "string",
+          description: "Secondary tag (optional)",
+        },
+        endpoint: {
+          type: "string",
+          description: "Specific endpoint being reviewed (optional)",
+        },
+        text: {
+          type: "string",
+          description: "Free-text review content (stored off-chain via IPFS)",
+        },
+        mcpTool: {
+          type: "string",
+          description: "Specific MCP tool being reviewed (optional)",
+        },
+        a2aSkills: {
+          type: "array",
+          items: { type: "string" },
+          description: "A2A skills being reviewed (optional)",
+        },
+      },
+      required: ["agentId", "value"],
+    },
+  },
+  {
+    name: "revoke_feedback",
+    description:
+      "Revoke previously submitted feedback. Only the original reviewer can revoke. " +
+      "Requires configured wallet.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        agentId: {
+          type: "string",
+          description: "Agent ID in chainId:tokenId format",
+        },
+        feedbackIndex: {
+          type: "number",
+          description: "The feedback index to revoke (from the reviewer's feedback list)",
+        },
+      },
+      required: ["agentId", "feedbackIndex"],
+    },
+  },
+];
+
+// ============================================================================
+// HANDLERS
+// ============================================================================
+
+function requireAuth() {
+  if (!hasAuthentication()) {
+    return {
+      sdk: null as ReturnType<typeof getAuthenticatedSDK>,
+      error: "No wallet configured. Call configure_wallet first.",
+    };
+  }
+  const sdk = getAuthenticatedSDK();
+  if (!sdk) {
+    return { sdk: null as ReturnType<typeof getAuthenticatedSDK>, error: "Failed to initialize authenticated SDK." };
+  }
+  return { sdk, error: undefined };
+}
+
+async function handleGiveFeedback(
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const { sdk, error } = requireAuth();
+  if (error || !sdk) return { error };
+
+  const agentId = args.agentId as string;
+  const value = args.value as number;
+
+  if (value < 0 || value > 100) {
+    return { error: "Feedback value must be between 0 and 100" };
+  }
+
+  // Build off-chain feedback file if rich fields provided
+  let feedbackFile: FeedbackFileInput | undefined;
+  if (args.text || args.mcpTool || args.a2aSkills) {
+    feedbackFile = sdk.prepareFeedbackFile({
+      text: args.text as string | undefined,
+      mcpTool: args.mcpTool as string | undefined,
+      a2aSkills: args.a2aSkills as string[] | undefined,
+    });
+  }
+
+  const tx = await sdk.giveFeedback(
+    agentId,
+    value,
+    (args.tag1 as string) ?? undefined,
+    (args.tag2 as string) ?? undefined,
+    (args.endpoint as string) ?? undefined,
+    feedbackFile,
+  );
+
+  const mined = await tx.waitConfirmed({ timeoutMs: 120_000 });
+
+  const parts = agentId.split(":");
+  const chainId = parts.length === 2 ? parseInt(parts[0], 10) : await sdk.chainId();
+
+  return {
+    success: true,
+    agentId,
+    value,
+    tags: [args.tag1, args.tag2].filter(Boolean),
+    txHash: mined.receipt.transactionHash,
+    chain: getChainName(chainId),
+  };
+}
+
+async function handleRevokeFeedback(
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const { sdk, error } = requireAuth();
+  if (error || !sdk) return { error };
+
+  const agentId = args.agentId as string;
+  const feedbackIndex = args.feedbackIndex as number;
+
+  const tx = await sdk.revokeFeedback(agentId, feedbackIndex);
+  const mined = await tx.waitConfirmed({ timeoutMs: 120_000 });
+
+  const parts = agentId.split(":");
+  const chainId = parts.length === 2 ? parseInt(parts[0], 10) : await sdk.chainId();
+
+  return {
+    success: true,
+    agentId,
+    feedbackIndex,
+    txHash: mined.receipt.transactionHash,
+    isRevoked: true,
+    chain: getChainName(chainId),
+  };
+}
+
+// ============================================================================
+// DISPATCH
+// ============================================================================
+
+export async function handleReputationTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  switch (name) {
+    case "give_feedback":
+      return handleGiveFeedback(args);
+    case "revoke_feedback":
+      return handleRevokeFeedback(args);
+    default:
+      return { error: `Unknown reputation tool: ${name}` };
+  }
+}

package/src/utils/chains.ts

@@ -0,0 +1,42 @@
+/** Known chain configurations for ERC-8004 agent registry lookups. */
+export interface ChainConfig {
+  chainId: number;
+  name: string;
+  rpcUrl: string;
+  explorerUrl: string;
+}
+
+export const CHAINS: Record<number, ChainConfig> = {
+  1: {
+    chainId: 1,
+    name: "Ethereum Mainnet",
+    rpcUrl: "https://eth.llamarpc.com",
+    explorerUrl: "https://etherscan.io",
+  },
+  8453: {
+    chainId: 8453,
+    name: "Base",
+    rpcUrl: "https://mainnet.base.org",
+    explorerUrl: "https://basescan.org",
+  },
+  42161: {
+    chainId: 42161,
+    name: "Arbitrum One",
+    rpcUrl: "https://arb1.arbitrum.io/rpc",
+    explorerUrl: "https://arbiscan.io",
+  },
+  10: {
+    chainId: 10,
+    name: "Optimism",
+    rpcUrl: "https://mainnet.optimism.io",
+    explorerUrl: "https://optimistic.etherscan.io",
+  },
+};
+
+export function getChain(chainId: number): ChainConfig | undefined {
+  return CHAINS[chainId];
+}
+
+export function getChainName(chainId: number): string {
+  return CHAINS[chainId]?.name ?? `Chain ${chainId}`;
+}

package/src/utils/trust-labels.ts

@@ -0,0 +1,53 @@
+export interface TrustLabel {
+  emoji: string;
+  label: string;
+  display: string;
+}
+
+/**
+ * Compute a human-readable trust label from review count and average score.
+ * First-match-wins rules (order matters).
+ */
+export function computeTrustLabel(count: number, avg: number): TrustLabel {
+  if (count >= 5 && avg < -50)
+    return {
+      emoji: "\u{1F534}",
+      label: "Untrusted",
+      display: `\u{1F534} Untrusted -- ${avg}/100 (${count} reviews)`,
+    };
+  if (avg < 0)
+    return {
+      emoji: "\u{1F7E0}",
+      label: "Caution",
+      display: `\u{1F7E0} Caution -- ${avg}/100 (${count} reviews)`,
+    };
+  if (count >= 20 && avg >= 80)
+    return {
+      emoji: "\u2B50",
+      label: "Highly Trusted",
+      display: `\u2B50 Highly Trusted -- ${avg}/100 (${count} reviews)`,
+    };
+  if (count >= 10 && avg >= 70)
+    return {
+      emoji: "\u{1F7E2}",
+      label: "Trusted",
+      display: `\u{1F7E2} Trusted -- ${avg}/100 (${count} reviews)`,
+    };
+  if (count >= 5 && avg >= 50)
+    return {
+      emoji: "\u{1F7E2}",
+      label: "Established",
+      display: `\u{1F7E2} Established -- ${avg}/100 (${count} reviews)`,
+    };
+  if (count > 0)
+    return {
+      emoji: "\u{1F535}",
+      label: "Emerging",
+      display: `\u{1F535} Emerging -- ${avg}/100 (${count} reviews)`,
+    };
+  return {
+    emoji: "\u26AA",
+    label: "No Data",
+    display: "\u26AA No Data -- 0/100 (0 reviews)",
+  };
+}

package/src/utils/validation.ts

@@ -0,0 +1,20 @@
+/**
+ * Validate an Ethereum address (basic checksum-agnostic check).
+ */
+export function isValidAddress(address: string): boolean {
+  return /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+
+/**
+ * Validate a bytes32 hex string (e.g., agent ID).
+ */
+export function isValidBytes32(hex: string): boolean {
+  return /^0x[0-9a-fA-F]{64}$/.test(hex);
+}
+
+/**
+ * Validate a positive integer chain ID.
+ */
+export function isValidChainId(chainId: number): boolean {
+  return Number.isInteger(chainId) && chainId > 0;
+}