@hivemind-os/collective-mcp-server 0.2.0

package/src/resources/index.ts

@@ -0,0 +1,70 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import type { MeshToolContext } from '../context.js';
+import { readAgentResource, meshAgentResourceTemplate } from './agent.js';
+import { readCapabilitiesResource, meshCapabilitiesResource } from './capabilities.js';
+import { readTaskResource, meshTaskResourceTemplate } from './task.js';
+import { readWalletResource, meshWalletResource } from './wallet.js';
+
+const staticResources = [meshCapabilitiesResource, meshWalletResource];
+const resourceTemplates = [meshAgentResourceTemplate, meshTaskResourceTemplate];
+
+export function registerResourceHandlers(server: Server, context: MeshToolContext): void {
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: staticResources,
+  }));
+
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates,
+  }));
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const data = await routeResourceRead(uri, context);
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: serialize(data),
+        },
+      ],
+    };
+  });
+}
+
+export const meshResourceDefinitions = {
+  resources: staticResources,
+  templates: resourceTemplates,
+};
+
+async function routeResourceRead(uri: string, context: MeshToolContext): Promise<unknown> {
+  const parsed = new URL(uri);
+
+  switch (parsed.host) {
+    case 'capabilities':
+      return readCapabilitiesResource(context);
+    case 'wallet':
+      return readWalletResource(context);
+    case 'agent':
+      return readAgentResource(decodeURIComponent(parsed.pathname.replace(/^\//, '')), context);
+    case 'task':
+      return readTaskResource(decodeURIComponent(parsed.pathname.replace(/^\//, '')), context);
+    default:
+      throw new Error(`Unknown resource: ${uri}`);
+  }
+}
+
+function serialize(payload: unknown): string {
+  return JSON.stringify(payload, bigintReplacer, 2);
+}
+
+function bigintReplacer(_key: string, value: unknown): unknown {
+  return typeof value === 'bigint' ? value.toString() : value;
+}

package/src/resources/task.ts

@@ -0,0 +1,58 @@
+import { TaskStatus } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+import { fetchMeshBlob } from '../encryption.js';
+
+const decoder = new TextDecoder();
+
+export const meshTaskResourceTemplate = {
+  uriTemplate: 'mesh://task/{id}',
+  name: 'Task Details',
+  description: 'Resolve task details and result payload by task id',
+  mimeType: 'application/json',
+};
+
+export async function readTaskResource(taskId: string, context: MeshToolContext): Promise<{
+  id: string;
+  requester: string;
+  provider?: string;
+  capability: string;
+  input_blob_id: string;
+  result_blob_id?: string;
+  price_mist: string;
+  status: string;
+  created_at: number;
+  accepted_at?: number;
+  completed_at?: number;
+  expires_at: number;
+  agreement_hash?: string;
+  result?: string;
+}> {
+  const task = await context.taskClient.getTask(taskId);
+  if (!task) {
+    throw new Error(`Task ${taskId} was not found.`);
+  }
+
+  let result: string | undefined;
+  if ((task.status === TaskStatus.COMPLETED || task.status === TaskStatus.RELEASED) && task.resultBlobId) {
+    const bytes = await fetchMeshBlob(context.blobStore, task.resultBlobId);
+    result = bytes ? decoder.decode(bytes) : undefined;
+  }
+
+  return {
+    id: task.id,
+    requester: task.requester,
+    provider: task.provider,
+    capability: task.capability,
+    input_blob_id: task.inputBlobId,
+    result_blob_id: task.resultBlobId,
+    price_mist: task.price.toString(),
+    status: TaskStatus[task.status] ?? 'UNKNOWN',
+    created_at: task.createdAt,
+    accepted_at: task.acceptedAt,
+    completed_at: task.completedAt,
+    expires_at: task.expiresAt,
+    agreement_hash: task.agreementHash,
+    result,
+  };
+}

package/src/resources/wallet.ts

@@ -0,0 +1,32 @@
+import { PaymentRail } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+import { formatMistToSui } from '../tools/balance.js';
+
+export const meshWalletResource = {
+  uri: 'mesh://wallet',
+  name: 'Wallet Overview',
+  description: 'Current wallet balance and local spending totals',
+  mimeType: 'application/json',
+};
+
+export async function readWalletResource(context: MeshToolContext): Promise<{
+  address: string;
+  balance_mist: string;
+  balance_sui: string;
+  spent_today_mist: string;
+  spent_month_mist: string;
+  rail: PaymentRail;
+}> {
+  const address = context.keypair.getPublicKey().toSuiAddress();
+  const balance = await context.suiClient.getBalance(address);
+
+  return {
+    address,
+    balance_mist: balance.toString(),
+    balance_sui: formatMistToSui(balance),
+    spent_today_mist: context.spendingPolicy.getSpent('day', PaymentRail.SUI_ESCROW).toString(),
+    spent_month_mist: context.spendingPolicy.getSpent('month', PaymentRail.SUI_ESCROW).toString(),
+    rail: PaymentRail.SUI_ESCROW,
+  };
+}

package/src/tools/analytics.ts

@@ -0,0 +1,122 @@
+import type { MeshToolContext } from '../context.js';
+import { executeIndexerQuery } from './indexer-client.js';
+
+export interface MeshAnalyticsParams {
+  view?: 'summary' | 'task-volume' | 'top-providers' | 'marketplace';
+  period?: 'HOUR' | 'DAY' | 'WEEK';
+  buckets?: number;
+  limit?: number;
+  sort_by?: 'COMPLETED_TASKS' | 'EARNINGS' | 'REPUTATION';
+}
+
+export const meshAnalyticsTool = {
+  name: 'collective_analytics',
+  description: 'Query task volume, top providers, and marketplace analytics from the Agentic Mesh indexer',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      view: { type: 'string', enum: ['summary', 'task-volume', 'top-providers', 'marketplace'] },
+      period: { type: 'string', enum: ['HOUR', 'DAY', 'WEEK'] },
+      buckets: { type: 'number' },
+      limit: { type: 'number' },
+      sort_by: { type: 'string', enum: ['COMPLETED_TASKS', 'EARNINGS', 'REPUTATION'] },
+    },
+  },
+};
+
+export async function runMeshAnalytics(
+  params: MeshAnalyticsParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const view = params.view ?? 'summary';
+
+  switch (view) {
+    case 'task-volume': {
+      const data = await executeIndexerQuery<{ taskVolume: unknown[] }>(
+        context,
+        `query TaskVolume($period: TimePeriod!, $buckets: Int) {
+          taskVolume(period: $period, buckets: $buckets) {
+            label
+            count
+            volumeMist
+          }
+        }`,
+        {
+          period: params.period ?? 'DAY',
+          buckets: params.buckets ?? 14,
+        },
+      );
+      return { view, period: params.period ?? 'DAY', buckets: params.buckets ?? 14, data: data.taskVolume };
+    }
+    case 'top-providers': {
+      const data = await executeIndexerQuery<{ topProviders: unknown[] }>(
+        context,
+        `query TopProviders($limit: Int, $sortBy: ProviderSortField) {
+          topProviders(limit: $limit, sortBy: $sortBy) {
+            did
+            owner
+            name
+            completedTasks
+            earningsMist
+            disputeCount
+            successRate
+            reputation
+          }
+        }`,
+        {
+          limit: params.limit ?? 10,
+          sortBy: params.sort_by ?? 'COMPLETED_TASKS',
+        },
+      );
+      return { view, limit: params.limit ?? 10, sort_by: params.sort_by ?? 'COMPLETED_TASKS', data: data.topProviders };
+    }
+    case 'marketplace': {
+      const data = await executeIndexerQuery<{ analytics: { marketplace: unknown } }>(
+        context,
+        `query MarketplaceAnalytics {
+          analytics {
+            marketplace {
+              averageBidCount
+              acceptanceRate
+              categoryPopularity {
+                category
+                taskCount
+              }
+            }
+          }
+        }`,
+      );
+      return { view, data: data.analytics.marketplace };
+    }
+    case 'summary':
+    default: {
+      const data = await executeIndexerQuery<{ analytics: unknown }>(
+        context,
+        `query AnalyticsSummary {
+          analytics {
+            totalAgents
+            activeAgents
+            totalTasks
+            completedTasks
+            disputedTasks
+            totalVolumeMist
+            averageGasCosts {
+              capability
+              averageGasMist
+              taskCount
+            }
+            marketplace {
+              averageBidCount
+              acceptanceRate
+              categoryPopularity {
+                category
+                taskCount
+              }
+            }
+          }
+        }`,
+      );
+      return { view: 'summary', data: data.analytics };
+    }
+  }
+}

package/src/tools/balance.ts

@@ -0,0 +1,36 @@
+import type { MeshToolContext } from '../context.js';
+
+export const meshBalanceTool = {
+  name: 'collective_balance',
+  description: 'Get the current wallet balance in MIST and SUI',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {},
+    required: [],
+  },
+};
+
+export async function runMeshBalance(
+  _params: Record<string, never>,
+  context: MeshToolContext,
+): Promise<{ address: string; balance_mist: string; balance_sui: string }> {
+  const address = context.keypair.getPublicKey().toSuiAddress();
+  const balanceMist = await context.suiClient.getBalance(address);
+
+  return {
+    address,
+    balance_mist: balanceMist.toString(),
+    balance_sui: formatMistToSui(balanceMist),
+  };
+}
+
+export function formatMistToSui(balanceMist: bigint): string {
+  const whole = balanceMist / 1_000_000_000n;
+  const fraction = balanceMist % 1_000_000_000n;
+  if (fraction === 0n) {
+    return whole.toString();
+  }
+
+  const fractionText = fraction.toString().padStart(9, '0').replace(/0+$/, '');
+  return `${whole.toString()}.${fractionText}`;
+}

package/src/tools/deactivate.ts

@@ -0,0 +1,33 @@
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshDeactivateParams {
+  agent_card_id: string;
+}
+
+export const meshDeactivateTool = {
+  name: 'collective_deactivate',
+  description: 'Deactivate an existing agent card',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      agent_card_id: { type: 'string', description: 'Agent card object id' },
+    },
+    required: ['agent_card_id'],
+  },
+};
+
+export async function runMeshDeactivate(
+  params: MeshDeactivateParams,
+  context: MeshToolContext,
+): Promise<{ tx_digest: string; status: 'deactivated' }> {
+  const result = await context.registryClient.deactivateAgent({
+    cardId: params.agent_card_id,
+    keypair: context.keypair,
+  });
+  context.agentCache.removeAgent(params.agent_card_id);
+
+  return {
+    tx_digest: result.txDigest,
+    status: 'deactivated',
+  };
+}

package/src/tools/discover.ts

@@ -0,0 +1,256 @@
+import type { AgentCard, Capability } from '@hivemind-os/collective-types';
+import { ReputationScoreCalculator } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+import { queryIndexerAgents, resolveIndexerUrl } from './indexer-client.js';
+
+const scoreCalculator = new ReputationScoreCalculator();
+
+export interface MeshDiscoverParams {
+  capability: string;
+  limit?: number;
+  sort_by?: 'price' | 'reputation';
+  useIndexer?: boolean;
+}
+
+export const meshDiscoverTool = {
+  name: 'collective_discover',
+  description: 'Find agents by capability on the Agentic Mesh network',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      capability: { type: 'string', description: 'Capability name to search for' },
+      limit: { type: 'number', description: 'Max results (default 10)' },
+      sort_by: { type: 'string', enum: ['price', 'reputation'], description: 'Sort results by price or reputation' },
+      useIndexer: { type: 'boolean', description: 'Prefer the indexer GraphQL API when available' },
+    },
+    required: ['capability'],
+  },
+};
+
+export async function runMeshDiscover(
+  params: MeshDiscoverParams,
+  context: MeshToolContext,
+): Promise<{ capability: string; source: 'indexer' | 'cache' | 'registry'; agents: ReturnType<typeof summarizeAgent>[] }> {
+  const capability = params.capability.trim();
+  const limit = normalizeLimit(params.limit);
+  const sortBy = params.sort_by ?? 'price';
+  const { agents, source } = await discoverAgentsByCapability(capability, context, limit, sortBy, params.useIndexer);
+
+  return {
+    capability,
+    source,
+    agents: agents.map((agent) => summarizeAgent(agent, capability)),
+  };
+}
+
+export async function discoverAgentsByCapability(
+  capability: string,
+  context: MeshToolContext,
+  limit = 10,
+  sortBy: 'price' | 'reputation' = 'price',
+  useIndexer?: boolean,
+): Promise<{ agents: AgentCard[]; source: 'indexer' | 'cache' | 'registry' }> {
+  const normalizedCapability = capability.trim();
+  if (!normalizedCapability) {
+    return { agents: [], source: 'cache' };
+  }
+
+  if (shouldUseIndexer(context, useIndexer)) {
+    try {
+      const indexed = await queryIndexerAgents(context, {
+        capability: normalizedCapability,
+        limit,
+      });
+      if (indexed.length > 0) {
+        return {
+          agents: sortBy === 'reputation' ? indexed.slice(0, limit) : sortByPrice(indexed, normalizedCapability).slice(0, limit),
+          source: 'indexer',
+        };
+      }
+    } catch (error) {
+      context.logger?.warn?.({ err: error }, 'Indexer discovery failed; falling back to local cache.');
+    }
+  }
+
+  const cached = (await queryLocalCache(context, normalizedCapability, Math.max(limit * 2, limit), sortBy))
+    .filter((agent) => hasCapability(agent, normalizedCapability))
+    .slice(0, limit);
+
+  if (cached.length > 0) {
+    return {
+      agents: sortBy === 'reputation' ? cached : sortByPrice(cached, normalizedCapability).slice(0, limit),
+      source: 'cache',
+    };
+  }
+
+  const discovered = await context.registryClient.discoverByCapability(normalizedCapability, limit, {
+    sortByReputation: sortBy === 'reputation',
+  });
+  for (const agent of discovered) {
+    context.agentCache.upsertAgent(agent);
+  }
+
+  const ranked = sortBy === 'reputation' ? discovered : sortByPrice(discovered, normalizedCapability);
+  return { agents: ranked.slice(0, limit), source: 'registry' };
+}
+
+export async function resolveProviderCapability(
+  capability: string,
+  context: MeshToolContext,
+  providerDid?: string,
+): Promise<{ agent: AgentCard; capability: Capability }> {
+  const normalizedCapability = capability.trim();
+  if (!normalizedCapability) {
+    throw new Error('Capability is required.');
+  }
+
+  if (providerDid) {
+    const cachedAgent = context.agentCache.getAgentByDID(providerDid);
+    const cachedCapability = cachedAgent ? findCapability(cachedAgent, normalizedCapability) : undefined;
+    if (cachedAgent?.active && cachedCapability) {
+      return { agent: cachedAgent, capability: cachedCapability };
+    }
+
+    const { agents } = await discoverAgentsByCapability(normalizedCapability, context, 50);
+    const matched = agents.find((entry) => entry.did === providerDid);
+    const matchedCapability = matched ? findCapability(matched, normalizedCapability) : undefined;
+    if (!matched || !matchedCapability) {
+      throw new Error(`Provider ${providerDid} was not found for capability ${normalizedCapability}.`);
+    }
+
+    return { agent: matched, capability: matchedCapability };
+  }
+
+  const { agents } = await discoverAgentsByCapability(normalizedCapability, context, 20);
+  const ranked = agents
+    .map((agent) => ({ agent, capability: findCapability(agent, normalizedCapability) }))
+    .filter((entry): entry is { agent: AgentCard; capability: Capability } => Boolean(entry.capability))
+    .sort((left, right) => compareBigInt(left.capability.pricing.amount, right.capability.pricing.amount));
+
+  if (ranked.length === 0) {
+    throw new Error(`No providers found for capability ${normalizedCapability}.`);
+  }
+
+  return ranked[0];
+}
+
+export function summarizeAgent(agent: AgentCard, capability?: string): {
+  name: string;
+  did: AgentCard['did'];
+  capabilities: string[];
+  pricing: Array<{
+    capability: string;
+    price_mist: string;
+    rail: string;
+    currency: string;
+  }>;
+  reputation: {
+    success_rate: number;
+    total_tasks: number;
+    total_disputes: number;
+    total_earnings_mist: string;
+  };
+  endpoint?: string;
+} {
+  const scopedCapabilities = capability
+    ? agent.capabilities.filter((entry) => capabilityNameEquals(entry.name, capability))
+    : agent.capabilities;
+  const reputation = scoreCalculator.computeScore(agent, []);
+
+  return {
+    name: agent.name,
+    did: agent.did,
+    capabilities: scopedCapabilities.map((entry) => entry.name),
+    pricing: scopedCapabilities.map((entry) => ({
+      capability: entry.name,
+      price_mist: entry.pricing.amount.toString(),
+      rail: entry.pricing.rail,
+      currency: entry.pricing.currency,
+    })),
+    reputation: {
+      success_rate: reputation.successRate,
+      total_tasks: reputation.totalTasks,
+      total_disputes: reputation.totalDisputes,
+      total_earnings_mist: reputation.totalEarningsMist.toString(),
+    },
+    endpoint: agent.endpoint,
+  };
+}
+
+async function queryLocalCache(
+  context: MeshToolContext,
+  capability: string,
+  limit: number,
+  sortBy: 'price' | 'reputation',
+): Promise<AgentCard[]> {
+  const cache = context.agentCache as MeshToolContext['agentCache'] & {
+    queryAgentsAdvanced?: (filters: {
+      capability?: string;
+      limit?: number;
+      sortBy?: 'stake' | 'reputation';
+    }) => Promise<AgentCard[]>;
+  };
+
+  if (typeof cache.queryAgentsAdvanced === 'function') {
+    return await cache.queryAgentsAdvanced({
+      capability,
+      limit,
+      sortBy: sortBy === 'reputation' ? 'reputation' : 'stake',
+    });
+  }
+
+  return context.agentCache.searchByCapability(capability, limit, { sortByReputation: sortBy === 'reputation' });
+}
+
+function shouldUseIndexer(context: MeshToolContext, useIndexer?: boolean): boolean {
+  if (useIndexer === false) {
+    return false;
+  }
+  return Boolean(resolveIndexerUrl(context));
+}
+
+function findCapability(agent: AgentCard, capability: string): Capability | undefined {
+  return agent.capabilities.find((entry) => capabilityNameEquals(entry.name, capability));
+}
+
+function hasCapability(agent: AgentCard, capability: string): boolean {
+  return findCapability(agent, capability) !== undefined;
+}
+
+function capabilityNameEquals(left: string, right: string): boolean {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+function compareBigInt(left: bigint, right: bigint): number {
+  if (left === right) {
+    return 0;
+  }
+
+  return left < right ? -1 : 1;
+}
+
+function normalizeLimit(limit?: number): number {
+  if (typeof limit !== 'number' || Number.isNaN(limit)) {
+    return 10;
+  }
+
+  return Math.max(1, Math.floor(limit));
+}
+
+function sortByPrice(agents: AgentCard[], capability: string): AgentCard[] {
+  return [...agents].sort((left, right) => {
+    const leftCapability = findCapability(left, capability);
+    const rightCapability = findCapability(right, capability);
+    if (!leftCapability && !rightCapability) {
+      return 0;
+    }
+    if (!leftCapability) {
+      return 1;
+    }
+    if (!rightCapability) {
+      return -1;
+    }
+    return compareBigInt(leftCapability.pricing.amount, rightCapability.pricing.amount);
+  });
+}