kompass-sdk 0.1.0

package/src/sources/mcp-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * MCP Registry Source Adapter
+ * Crawls registry.modelcontextprotocol.io for MCP servers
+ * No auth required. Public REST API with cursor pagination.
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const BASE_URL = "https://registry.modelcontextprotocol.io";
+
+interface McpServer {
+  name: string;
+  description?: string;
+  version?: string;
+  repo?: string;
+  website?: string;
+  packages?: { registry: string; name: string }[];
+  remotes?: { transport: string; url: string }[];
+}
+
+export const mcpRegistryAdapter: SourceAdapter = {
+  name: "mcp-registry",
+  displayName: "MCP Registry (Anthropic)",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const limit = options?.limit ?? 50;
+    const timeout = options?.timeout ?? 10000;
+
+    try {
+      const url = new URL("/v0.1/servers", BASE_URL);
+      url.searchParams.set("limit", String(Math.min(limit, 96)));
+      if (query) url.searchParams.set("search", query);
+      url.searchParams.set("version", "latest");
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeout);
+
+      const res = await fetch(url.toString(), { signal: controller.signal });
+      clearTimeout(timer);
+
+      if (!res.ok) return [];
+
+      const data = await res.json();
+      const rawServers = data.servers ?? data.data ?? [];
+      // MCP registry wraps in { server: {...} } objects
+      const servers: McpServer[] = rawServers.map((item: any) => item.server ?? item);
+
+      return servers.slice(0, limit).map((server) => mapMcpServer(server));
+    } catch {
+      return [];
+    }
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(`${BASE_URL}/v0.1/servers?limit=1`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+};
+
+function mapMcpServer(server: McpServer): UnifiedAgent {
+  const remoteUrl = server.remotes?.[0]?.url;
+  const categories = extractCategories(server.description ?? server.name);
+
+  return {
+    id: `mcp-registry:${server.name}`,
+    nativeId: server.name,
+    name: server.name,
+    description: server.description ?? "",
+    categories,
+    capabilities: [server.description ?? server.name],
+    source: "mcp-registry",
+    protocol: "mcp",
+    endpoints: {
+      mcp: remoteUrl,
+      http: server.website ?? server.repo,
+    },
+    pricing: { model: "free" },
+    verified: !!server.repo,
+    raw: server,
+  };
+}
+
+function extractCategories(text: string): string[] {
+  const lower = text.toLowerCase();
+  const cats: string[] = [];
+  const keywords: Record<string, string> = {
+    defi: "defi", yield: "defi", swap: "defi", token: "defi", blockchain: "defi",
+    data: "data", analytics: "data", database: "data", search: "data",
+    code: "development", github: "development", git: "development",
+    file: "tools", browser: "tools", web: "tools",
+    ai: "ai", llm: "ai", model: "ai",
+    image: "media", video: "media", audio: "media",
+  };
+  for (const [keyword, cat] of Object.entries(keywords)) {
+    if (lower.includes(keyword) && !cats.includes(cat)) cats.push(cat);
+  }
+  return cats.length > 0 ? cats : ["general"];
+}

package/src/sources/skills.ts

@@ -0,0 +1,161 @@
+/**
+ * Skills Source Adapter
+ * Searches skills.sh (Vercel) and ClawHub registries for agent skills
+ * 13,700+ capabilities indexed across both registries
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const SKILLS_SH_API = "https://skills.sh";
+const CLAWHUB_API = "https://clawhub.ai";
+
+export const skillsAdapter: SourceAdapter = {
+  name: "skills-registry",
+  displayName: "Skills Registry (skills.sh + ClawHub)",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const limit = options?.limit ?? 20;
+    const timeout = options?.timeout ?? 10000;
+    const results: UnifiedAgent[] = [];
+
+    // Search skills.sh
+    try {
+      const skillsShResults = await searchSkillsSh(query, Math.ceil(limit / 2), timeout);
+      results.push(...skillsShResults);
+    } catch {
+      // skills.sh might not have a public search API — fall back to known skills
+    }
+
+    // Search ClawHub
+    try {
+      const clawHubResults = await searchClawHub(query, Math.ceil(limit / 2), timeout);
+      results.push(...clawHubResults);
+    } catch {
+      // ClawHub might be rate-limited
+    }
+
+    // If both APIs fail, return from seed list
+    if (results.length === 0) {
+      return searchSeedList(query, limit);
+    }
+
+    return results.slice(0, limit);
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(SKILLS_SH_API, { signal: AbortSignal.timeout(3000) });
+      return res.ok;
+    } catch {
+      return true; // Seed list always available
+    }
+  },
+};
+
+async function searchSkillsSh(query: string, limit: number, timeout: number): Promise<UnifiedAgent[]> {
+  // skills.sh has a search page — try to query it
+  const res = await fetch(`${SKILLS_SH_API}/api/search?q=${encodeURIComponent(query)}&limit=${limit}`, {
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!res.ok) {
+    // Try the leaderboard endpoint
+    const lbRes = await fetch(`${SKILLS_SH_API}/api/leaderboard?limit=${limit}`, {
+      signal: AbortSignal.timeout(timeout),
+    });
+    if (!lbRes.ok) return [];
+    const data = await lbRes.json();
+    const skills = Array.isArray(data) ? data : data.skills ?? data.data ?? [];
+    return skills
+      .filter((s: any) => matchesQuery(s, query))
+      .map((s: any) => mapSkill(s, "skills-sh"));
+  }
+
+  const data = await res.json();
+  const skills = Array.isArray(data) ? data : data.skills ?? data.results ?? [];
+  return skills.map((s: any) => mapSkill(s, "skills-sh"));
+}
+
+async function searchClawHub(query: string, limit: number, timeout: number): Promise<UnifiedAgent[]> {
+  const res = await fetch(`${CLAWHUB_API}/api/skills/search?q=${encodeURIComponent(query)}&limit=${limit}`, {
+    signal: AbortSignal.timeout(timeout),
+  });
+
+  if (!res.ok) return [];
+
+  const data = await res.json();
+  const skills = Array.isArray(data) ? data : data.skills ?? data.results ?? [];
+  return skills.map((s: any) => mapSkill(s, "clawhub"));
+}
+
+function mapSkill(skill: any, registry: string): UnifiedAgent {
+  const name = skill.name ?? skill.slug ?? skill.title ?? "Unknown Skill";
+  const description = skill.description ?? "";
+  const repo = skill.repo ?? skill.repository ?? skill.url ?? "";
+  const installs = skill.installs ?? skill.downloads ?? 0;
+
+  return {
+    id: `skills-registry:${registry}:${name.toLowerCase().replace(/\s+/g, "-")}`,
+    nativeId: skill.id ?? name,
+    name,
+    description,
+    categories: extractSkillCategories(name, description),
+    capabilities: [description, ...(skill.tags ?? [])],
+    source: "skills-registry" as any,
+    protocol: "skill" as any,
+    endpoints: {
+      http: repo || `https://skills.sh/${name}`,
+    },
+    pricing: { model: "free" as const },
+    verified: installs > 100,
+    lastSeen: Date.now(),
+    raw: { ...skill, registry },
+  };
+}
+
+// Seed list of well-known skills for when APIs are unavailable
+const KNOWN_SKILLS = [
+  { name: "remotion-best-practices", description: "Video creation in React with Remotion", categories: ["media", "development"], registry: "skills-sh", installs: 145000 },
+  { name: "web-design-guidelines", description: "UI/UX design best practices for web development", categories: ["design", "development"], registry: "skills-sh", installs: 89000 },
+  { name: "react-best-practices", description: "React and Next.js performance optimization from Vercel", categories: ["development"], registry: "skills-sh", installs: 120000 },
+  { name: "solana-dev", description: "End-to-end Solana development playbook", categories: ["development", "defi"], registry: "skills-sh", installs: 50000 },
+  { name: "cairo-contracts", description: "Write Cairo smart contracts on Starknet", categories: ["development", "defi"], registry: "skills-sh", installs: 30000 },
+  { name: "x402-skill", description: "x402 HTTP payment protocol for monetizing APIs", categories: ["payments", "development"], registry: "skills-sh", installs: 25000 },
+  { name: "agent-browser", description: "Automate browser interactions, screenshots, form filling", categories: ["tools", "automation"], registry: "skills-sh", installs: 70000 },
+  { name: "implement-design", description: "Translate Figma designs into production-ready code", categories: ["design", "development"], registry: "skills-sh", installs: 60000 },
+  { name: "find-skills", description: "Discover and install new agent skills", categories: ["tools", "discovery"], registry: "skills-sh", installs: 200000 },
+  { name: "tailwind-v4-shadcn", description: "Set up Tailwind v4 with shadcn/ui", categories: ["development", "design"], registry: "skills-sh", installs: 45000 },
+  { name: "ethskills", description: "Learn Ethereum, Solidity, smart contracts, web3 development", categories: ["development", "defi"], registry: "skills-sh", installs: 8000 },
+  { name: "soul-markets", description: "Agent skill marketplace — monetize agent capabilities", categories: ["marketplace", "commerce"], registry: "clawhub", installs: 5000 },
+  { name: "a2a-market", description: "Buy and sell agent skills using USDC on Base via A2A", categories: ["marketplace", "commerce"], registry: "clawhub", installs: 3000 },
+  { name: "skillzmarket", description: "Discover and install skills from community marketplace", categories: ["marketplace", "discovery"], registry: "clawhub", installs: 4000 },
+  { name: "x402-agent-marketplace", description: "x402 agent marketplace for paid AI capabilities", categories: ["marketplace", "payments"], registry: "clawhub", installs: 2000 },
+];
+
+function searchSeedList(query: string, limit: number): UnifiedAgent[] {
+  const lower = query.toLowerCase();
+  return KNOWN_SKILLS
+    .filter((s) => matchesQuery(s, query))
+    .slice(0, limit)
+    .map((s) => mapSkill({ ...s, installs: s.installs }, s.registry));
+}
+
+function matchesQuery(skill: any, query: string): boolean {
+  if (!query) return true;
+  const lower = query.toLowerCase();
+  const text = `${skill.name ?? ""} ${skill.description ?? ""} ${(skill.tags ?? []).join(" ")} ${(skill.categories ?? []).join(" ")}`.toLowerCase();
+  return lower.split(/\s+/).some((term) => text.includes(term));
+}
+
+function extractSkillCategories(name: string, description: string): string[] {
+  const text = `${name} ${description}`.toLowerCase();
+  const cats: string[] = [];
+  if (text.match(/react|next|vue|svelte|frontend|css|tailwind|design/)) cats.push("development");
+  if (text.match(/defi|yield|swap|solidity|ethereum|solana|contract/)) cats.push("defi");
+  if (text.match(/image|video|audio|media|remotion|figma/)) cats.push("media");
+  if (text.match(/data|analytics|research|search/)) cats.push("data");
+  if (text.match(/browser|automat|tool|file/)) cats.push("tools");
+  if (text.match(/market|commerce|pay|x402|monetiz/)) cats.push("commerce");
+  if (text.match(/security|audit|test/)) cats.push("security");
+  return cats.length > 0 ? cats : ["general"];
+}

package/src/sources/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Kompass Universal Agent Discovery — Core Types
+ *
+ * UnifiedAgent is the normalized representation of an agent
+ * from ANY source (ACP, MCP, ERC-8004, x402, A2A, L402, etc.)
+ */
+
+export type AgentSource =
+  | "kompass-registry"
+  | "acp"
+  | "mcp-registry"
+  | "x402-ecosystem"
+  | "erc8004"
+  | "adp"
+  | "a2a-wellknown"
+  | "l402-directory"
+  | "skills-registry";
+
+export type AgentProtocol = "acp" | "mcp" | "x402" | "a2a" | "http" | "l402" | "onchain" | "skill";
+
+export interface UnifiedAgent {
+  /** Globally unique ID: "${source}:${nativeId}" */
+  id: string;
+  /** ID within the source registry */
+  nativeId: string;
+  /** Agent name */
+  name: string;
+  /** Description of what this agent does */
+  description: string;
+  /** Capability categories (e.g., ["defi", "yield", "analytics"]) */
+  categories: string[];
+  /** Free-text capability descriptions for matching */
+  capabilities: string[];
+  /** Which source registry this came from */
+  source: AgentSource;
+  /** Which protocol to use for hiring/interacting */
+  protocol: AgentProtocol;
+  /** Protocol-specific endpoints */
+  endpoints: {
+    mcp?: string;
+    a2a?: string;
+    x402?: string;
+    http?: string;
+    l402?: string;
+    acp?: { walletAddress: string; entityAddress?: string };
+  };
+  /** Reputation/trust signals */
+  reputation?: {
+    score: number;
+    count: number;
+    source: string;
+  };
+  /** Pricing info */
+  pricing?: {
+    model: "free" | "per-call" | "subscription" | "escrow" | "unknown";
+    amount?: string;
+    currency?: string;
+  };
+  /** Identity verification status */
+  verified?: boolean;
+  /** Last time this agent was seen active */
+  lastSeen?: number;
+  /** Original raw data from source */
+  raw?: unknown;
+}
+
+export interface SourceSearchOptions {
+  limit?: number;
+  category?: string;
+  timeout?: number;
+}
+
+export interface SourceAdapter {
+  /** Unique name for this source */
+  name: AgentSource;
+  /** Human-readable display name */
+  displayName: string;
+  /** Search this source for agents matching the query */
+  search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]>;
+  /** Check if this source is reachable */
+  ping(): Promise<boolean>;
+}

package/src/sources/x402-ecosystem.ts

@@ -0,0 +1,86 @@
+/**
+ * x402 Ecosystem Source Adapter
+ * Fetches known x402 endpoints from the x402.org ecosystem
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+// Seed list of known x402 services (from x402.org/ecosystem + x402scan)
+const KNOWN_X402_SERVICES = [
+  { name: "OpenRouter", url: "https://openrouter.ai", description: "LLM API access with USDC payments", categories: ["ai", "llm"] },
+  { name: "Dexter AI", url: "https://dexterai.com", description: "x402 facilitator on Solana. 38M+ settlements", categories: ["defi", "trading"] },
+  { name: "AgentCash", url: "https://agentcash.dev", description: "One balance, every paid API. Multi-protocol agent wallet", categories: ["payments", "tools"] },
+  { name: "Allium", url: "https://allium.so", description: "Blockchain data APIs with x402 payments", categories: ["data", "analytics"] },
+  { name: "Kompass Data Provider", url: "http://localhost:4021", description: "DeFi yield data, token prices, risk scores via x402", categories: ["defi", "data"] },
+  { name: "Wurk", url: "https://wurk.fun", description: "Agent job board with x402 integration", categories: ["jobs", "tools"] },
+  { name: "Tavily", url: "https://tavily.com", description: "AI-powered web search API", categories: ["search", "data"] },
+  { name: "ASSAY", url: "https://assayaudit.com", description: "Agent evaluation and auditing service", categories: ["audit", "trust"] },
+  { name: "Zentiece", url: "https://zentiece.com", description: "Agent with x402 payments + ORBIT burns", categories: ["defi", "trading"] },
+  { name: "AlgoVoi", url: "https://algovoi.com", description: "x402 integration on Algorand", categories: ["defi", "tools"] },
+  { name: "LibertAI", url: "https://libertai.io", description: "Autonomous agents on Aleph Cloud with x402", categories: ["ai", "compute"] },
+  { name: "Handshake_58", url: "https://handshake58.com", description: "Streaming AI agent payment channels", categories: ["payments"] },
+];
+
+export const x402EcosystemAdapter: SourceAdapter = {
+  name: "x402-ecosystem",
+  displayName: "x402 Ecosystem",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    // Also try to fetch from x402.org ecosystem page
+    let dynamicServices: typeof KNOWN_X402_SERVICES = [];
+    try {
+      const res = await fetch("https://www.x402.org/ecosystem", {
+        signal: AbortSignal.timeout(options?.timeout ?? 5000),
+      });
+      if (res.ok) {
+        const html = await res.text();
+        // Extract any JSON data from the page
+        const jsonMatch = html.match(/\[{.*"name".*}\]/s);
+        if (jsonMatch) {
+          dynamicServices = JSON.parse(jsonMatch[0]);
+        }
+      }
+    } catch {
+      // Fall back to seed list
+    }
+
+    const allServices = [...KNOWN_X402_SERVICES, ...dynamicServices];
+    const lower = query.toLowerCase();
+
+    return allServices
+      .filter((s) => {
+        if (!query) return true;
+        return (
+          s.name.toLowerCase().includes(lower) ||
+          s.description.toLowerCase().includes(lower) ||
+          s.categories.some((c) => lower.includes(c))
+        );
+      })
+      .slice(0, options?.limit ?? 50)
+      .map(mapX402Service);
+  },
+
+  async ping(): Promise<boolean> {
+    return true; // Seed list always available
+  },
+};
+
+function mapX402Service(service: (typeof KNOWN_X402_SERVICES)[0]): UnifiedAgent {
+  return {
+    id: `x402-ecosystem:${service.name.toLowerCase().replace(/\s+/g, "-")}`,
+    nativeId: service.name,
+    name: service.name,
+    description: service.description,
+    categories: service.categories,
+    capabilities: [service.description],
+    source: "x402-ecosystem",
+    protocol: "x402",
+    endpoints: {
+      x402: service.url,
+      http: service.url,
+    },
+    pricing: { model: "per-call", currency: "USDC" },
+    verified: true,
+    raw: service,
+  };
+}

package/src/types.ts

@@ -0,0 +1,147 @@
+import type { Address, WalletClient, PublicClient, Chain, Transport, Account } from "viem";
+
+/** SDK configuration */
+export interface KompassConfig {
+  /** viem PublicClient for read operations */
+  publicClient: PublicClient<Transport, Chain>;
+  /** viem WalletClient for write operations (optional for read-only usage) */
+  walletClient?: WalletClient<Transport, Chain, Account>;
+  /** KompassEscrow contract address */
+  escrowAddress: Address;
+  /** KompassRegistry contract address */
+  registryAddress: Address;
+  /** ERC-8004 Reputation Registry address */
+  reputationRegistryAddress: Address;
+  /** PipelineOrchestrator contract address */
+  pipelineAddress?: Address;
+  /** Default settlement token for pipeline creation */
+  paymentTokenAddress?: Address;
+  /** Default hook address for escrow jobs (e.g., ReputationUpdateHook) */
+  defaultHookAddress?: Address;
+  /** Indexer GraphQL endpoint (e.g., http://localhost:42069/graphql) */
+  indexerUrl: string;
+}
+
+/** Job status matching the contract enum */
+export type JobStatus = "Open" | "Funded" | "Submitted" | "Completed" | "Rejected" | "Expired";
+
+/** Milestone status matching the contract enum */
+export type MilestoneStatus = "Pending" | "Submitted" | "Approved" | "Rejected";
+
+/** Agent type from ENS text records */
+export type AgentType = "provider" | "evaluator" | "both" | "unknown";
+
+/** Payment mode for agent services */
+export type PaymentMode = "escrow" | "x402" | "hybrid" | "unknown";
+
+/** Agent profile from the indexer */
+export interface AgentProfile {
+  id: Address;
+  ensNode: `0x${string}`;
+  ensName: string;
+  agentType: AgentType;
+  categories: string;
+  pricingModel: string;
+  pricingRate: string;
+  pricingToken: string;
+  erc8004Id: string;
+  identityVerification: string;
+  identityVerified: boolean;
+  paymentMode: PaymentMode;
+  endpointMcp: string;
+  endpointA2a: string;
+  endpointX402: string;
+  x402Enabled: boolean;
+  evaluatorDomains: string;
+  description: string;
+  registered: boolean;
+  registeredAt: bigint;
+  updatedAt: bigint;
+}
+
+/** Options for discovering agents */
+export interface DiscoverOptions {
+  category?: string;
+  evaluatorDomain?: string;
+  maxPrice?: bigint;
+  minReputation?: number;
+  agentType?: AgentType;
+  paymentMode?: PaymentMode;
+  requiresX402?: boolean;
+  verifiedOnly?: boolean;
+  limit?: number;
+}
+
+/** Milestone configuration for job creation */
+export interface MilestoneConfig {
+  budgetShareBps: number;
+}
+
+/** Options for creating a job */
+export interface CreateJobOptions {
+  provider: Address;
+  evaluator: Address;
+  budget: bigint;
+  expiredAt: bigint;
+  description: string;
+  hook?: Address;
+  milestones?: MilestoneConfig[];
+}
+
+/** On-chain job data */
+export interface Job {
+  client: Address;
+  provider: Address;
+  evaluator: Address;
+  hook: Address;
+  budget: bigint;
+  expiredAt: bigint;
+  status: JobStatus;
+  description: string;
+  deliverable: `0x${string}`;
+  milestoneCount: number;
+  currentMilestone: number;
+}
+
+/** Milestone data from contract */
+export interface MilestoneData {
+  budgetShareBps: number;
+  deliverable: `0x${string}`;
+  status: MilestoneStatus;
+}
+
+/** Transaction result */
+export interface TxResult {
+  txHash: `0x${string}`;
+}
+
+/** Job creation result */
+export interface CreateJobResult extends TxResult {
+  jobId: bigint;
+}
+
+/** ERC-8004 reputation summary */
+export interface ReputationSummary {
+  count: bigint;
+  summaryValue: bigint;
+  summaryValueDecimals: number;
+}
+
+/** Registration profile (fields to set as ENS text records) */
+export interface RegisterProfile {
+  ensNode: `0x${string}`;
+  ensName?: string;
+  agentType?: AgentType;
+  categories?: string;
+  pricingModel?: string;
+  pricingRate?: string;
+  pricingToken?: string;
+  erc8004Id?: string;
+  identityVerification?: string;
+  paymentMode?: PaymentMode;
+  endpointMcp?: string;
+  endpointA2a?: string;
+  endpointX402?: string;
+  evaluatorDomains?: string;
+  description?: string;
+}