@hivemind-os/collective-mcp-server 0.2.0

package/src/tools/index.ts

@@ -0,0 +1,152 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { SessionExpiredError } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+import { meshAnalyticsTool, runMeshAnalytics } from './analytics.js';
+import { meshBalanceTool, runMeshBalance } from './balance.js';
+import { meshDeactivateTool, runMeshDeactivate } from './deactivate.js';
+import { meshDiscoverTool, runMeshDiscover } from './discover.js';
+import { meshDisputeTool, runMeshDispute } from './dispute.js';
+import { meshExecuteAsyncTool, runMeshExecuteAsync } from './execute-async.js';
+import { meshExecuteTool, runMeshExecute } from './execute.js';
+import { meshMeteredExecuteTool, meshVerifyResultTool, runMeshMeteredExecute, runMeshVerifyResult } from './metering.js';
+import { meshMarketplaceAcceptBidTool, runMeshMarketplaceAcceptBid } from './marketplace-accept-bid.js';
+import { meshMarketplaceBidTool, runMeshMarketplaceBid } from './marketplace-bid.js';
+import { meshMarketplaceBrowseTool, runMeshMarketplaceBrowse } from './marketplace-browse.js';
+import { meshMarketplacePostTool, runMeshMarketplacePost } from './marketplace-post.js';
+import { meshMultiExecuteTool, runMeshMultiExecute } from './multi-execute.js';
+import { meshPolicyUpdateTool, runMeshPolicyUpdate } from './policy-update.js';
+import { meshRegisterTool, runMeshRegister } from './register.js';
+import { meshRelayRegistryTool, runMeshRelayRegistry } from './relay-registry.js';
+import { meshStakeTool, runMeshStake } from './stake.js';
+import { meshTaskHistoryTool, runMeshTaskHistory } from './task-history.js';
+import { meshTaskStatusTool, runMeshTaskStatus } from './task-status.js';
+
+const toolDefinitions = [
+  meshAnalyticsTool,
+  meshDiscoverTool,
+  meshDisputeTool,
+  meshExecuteTool,
+  meshExecuteAsyncTool,
+  meshMeteredExecuteTool,
+  meshVerifyResultTool,
+  meshMarketplacePostTool,
+  meshMarketplaceBrowseTool,
+  meshMultiExecuteTool,
+  meshMarketplaceBidTool,
+  meshMarketplaceAcceptBidTool,
+  meshTaskStatusTool,
+  meshRegisterTool,
+  meshDeactivateTool,
+  meshBalanceTool,
+  meshPolicyUpdateTool,
+  meshStakeTool,
+  meshRelayRegistryTool,
+  meshTaskHistoryTool,
+];
+
+export type MeshToolHandler = (params: never, context: MeshToolContext) => Promise<unknown>;
+
+export const meshToolHandlers: Record<string, MeshToolHandler> = {
+  [meshAnalyticsTool.name]: runMeshAnalytics,
+  [meshDiscoverTool.name]: runMeshDiscover,
+  [meshDisputeTool.name]: runMeshDispute,
+  [meshExecuteTool.name]: runMeshExecute,
+  [meshExecuteAsyncTool.name]: runMeshExecuteAsync,
+  [meshMeteredExecuteTool.name]: runMeshMeteredExecute,
+  [meshVerifyResultTool.name]: runMeshVerifyResult,
+  [meshMarketplacePostTool.name]: runMeshMarketplacePost,
+  [meshMarketplaceBrowseTool.name]: runMeshMarketplaceBrowse,
+  [meshMultiExecuteTool.name]: runMeshMultiExecute,
+  [meshMarketplaceBidTool.name]: runMeshMarketplaceBid,
+  [meshMarketplaceAcceptBidTool.name]: runMeshMarketplaceAcceptBid,
+  [meshTaskStatusTool.name]: runMeshTaskStatus,
+  [meshRegisterTool.name]: runMeshRegister,
+  [meshDeactivateTool.name]: runMeshDeactivate,
+  [meshBalanceTool.name]: runMeshBalance,
+  [meshPolicyUpdateTool.name]: runMeshPolicyUpdate,
+  [meshStakeTool.name]: runMeshStake,
+  [meshRelayRegistryTool.name]: runMeshRelayRegistry,
+  [meshTaskHistoryTool.name]: runMeshTaskHistory,
+};
+
+export function registerToolHandlers(server: Server, context: MeshToolContext): void {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolDefinitions,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const handler = meshToolHandlers[request.params.name];
+    if (!handler) {
+      return createErrorResult(`Unknown tool: ${request.params.name}`);
+    }
+
+    try {
+      const response = await handler((request.params.arguments ?? {}) as never, context);
+      return createSuccessResult(response);
+    } catch (error) {
+      const message =
+        error instanceof SessionExpiredError
+          ? 'Authentication expired. Please re-authenticate via the daemon portal.'
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      const sessionState = await getSessionState(context);
+      return createErrorResult(
+        sessionState ? `${message} (session state: ${sessionState})` : message,
+        sessionState ? { session_state: sessionState, reauth_required: error instanceof SessionExpiredError } : undefined,
+      );
+    }
+  });
+}
+
+export const meshToolDefinitions = toolDefinitions;
+
+function createSuccessResult(payload: unknown): { content: Array<{ type: 'text'; text: string }> } {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: serialize(payload),
+      },
+    ],
+  };
+}
+
+function createErrorResult(
+  message: string,
+  details?: Record<string, unknown>,
+): {
+  isError: true;
+  content: Array<{ type: 'text'; text: string }>;
+} {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: serialize({ error: message, ...details }),
+      },
+    ],
+  };
+}
+
+async function getSessionState(context: MeshToolContext): Promise<string | null> {
+  const provider = context.authProvider;
+  if (!provider?.getSessionState) {
+    return null;
+  }
+
+  const state = await provider.getSessionState();
+  return typeof state === 'string' ? state : null;
+}
+
+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/tools/indexer-client.ts

@@ -0,0 +1,163 @@
+import type { AgentCard, Capability } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: Array<{ message?: string }>;
+}
+
+interface GraphQLAgentNode {
+  id: string;
+  owner: string;
+  did: string;
+  name: string;
+  description: string;
+  endpoint?: string | null;
+  active: boolean;
+  version: number;
+  registeredAt: string;
+  updatedAt: string;
+  totalTasksCompleted: number;
+  totalTasksFailed: number;
+  totalTasksDisputed: number;
+  totalEarningsMist: string;
+  hasStake: boolean;
+  stakeMist?: string | null;
+  stakeType?: 'agent' | 'relay' | null;
+  capabilities: Array<{
+    name: string;
+    description: string;
+    version: string;
+    executionMode?: 'sync' | 'async' | null;
+    paymentRails?: string[] | null;
+    pricing: {
+      rail: Capability['pricing']['rail'];
+      amount: string;
+      currency: string;
+    };
+  }>;
+}
+
+export async function executeIndexerQuery<TData>(
+  context: Pick<MeshToolContext, 'indexer'>,
+  query: string,
+  variables?: Record<string, unknown>,
+): Promise<TData> {
+  const endpoint = resolveIndexerUrl(context);
+  if (!endpoint) {
+    throw new Error('Indexer is not configured.');
+  }
+
+  const fetchImpl = context.indexer?.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({ query, variables }),
+  });
+  if (!response.ok) {
+    throw new Error(`Indexer query failed with status ${response.status}.`);
+  }
+
+  const payload = (await response.json()) as GraphQLResponse<TData>;
+  if (payload.errors && payload.errors.length > 0) {
+    throw new Error(payload.errors.map((entry) => entry.message ?? 'Unknown GraphQL error').join('; '));
+  }
+  if (!payload.data) {
+    throw new Error('Indexer query returned no data.');
+  }
+  return payload.data;
+}
+
+export async function queryIndexerAgents(
+  context: Pick<MeshToolContext, 'indexer'>,
+  params: { capability: string; limit: number; minReputation?: number; category?: string },
+): Promise<AgentCard[]> {
+  const data = await executeIndexerQuery<{ agents: { nodes: GraphQLAgentNode[] } }>(
+    context,
+    `query IndexedAgents($capability: String, $limit: Int, $minReputation: Float, $category: String) {
+      agents(capability: $capability, limit: $limit, minReputation: $minReputation, category: $category) {
+        nodes {
+          id
+          owner
+          did
+          name
+          description
+          endpoint
+          active
+          version
+          registeredAt
+          updatedAt
+          totalTasksCompleted
+          totalTasksFailed
+          totalTasksDisputed
+          totalEarningsMist
+          hasStake
+          stakeMist
+          stakeType
+          capabilities {
+            name
+            description
+            version
+            executionMode
+            paymentRails
+            pricing {
+              rail
+              amount
+              currency
+            }
+          }
+        }
+      }
+    }`,
+    {
+      capability: params.capability,
+      limit: params.limit,
+      minReputation: params.minReputation,
+      category: params.category,
+    },
+  );
+
+  return data.agents.nodes.map(mapGraphqlAgent);
+}
+
+export function resolveIndexerUrl(context: Pick<MeshToolContext, 'indexer'>): string | null {
+  const value = context.indexer?.graphqlUrl ?? process.env.COLLECTIVE_INDEXER_URL;
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function mapGraphqlAgent(agent: GraphQLAgentNode): AgentCard {
+  return {
+    id: agent.id,
+    owner: agent.owner,
+    did: agent.did as AgentCard['did'],
+    name: agent.name,
+    description: agent.description,
+    endpoint: agent.endpoint ?? undefined,
+    active: agent.active,
+    version: agent.version,
+    registeredAt: Number(agent.registeredAt),
+    updatedAt: Number(agent.updatedAt),
+    totalTasksCompleted: agent.totalTasksCompleted,
+    totalTasksFailed: agent.totalTasksFailed,
+    totalTasksDisputed: agent.totalTasksDisputed,
+    totalEarningsMist: BigInt(agent.totalEarningsMist),
+    hasStake: agent.hasStake,
+    stakeMist: agent.stakeMist ? BigInt(agent.stakeMist) : undefined,
+    stakeType: agent.stakeType ?? undefined,
+    capabilities: agent.capabilities.map((capability) => ({
+      name: capability.name,
+      description: capability.description,
+      version: capability.version,
+      executionMode: capability.executionMode ?? undefined,
+      paymentRails: capability.paymentRails ?? undefined,
+      pricing: {
+        rail: capability.pricing.rail,
+        amount: BigInt(capability.pricing.amount),
+        currency: capability.pricing.currency,
+      },
+    })),
+  };
+}

package/src/tools/marketplace-accept-bid.ts

@@ -0,0 +1,43 @@
+import { MarketplaceClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshMarketplaceAcceptBidParams {
+  task_id: string;
+  bid_id: string;
+  reject_competing?: boolean;
+}
+
+export const meshMarketplaceAcceptBidTool = {
+  name: 'collective_marketplace_accept_bid',
+  description: 'Accept a marketplace bid and optionally reject competing bids',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: { type: 'string', description: 'Marketplace task id' },
+      bid_id: { type: 'string', description: 'Bid id to accept' },
+      reject_competing: { type: 'boolean', description: 'Reject other active bids in the same transaction (default true)' },
+    },
+    required: ['task_id', 'bid_id'],
+  },
+};
+
+export async function runMeshMarketplaceAcceptBid(
+  params: MeshMarketplaceAcceptBidParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const client = context.marketplaceClient ?? new MarketplaceClient(context.suiClient, context.networkConfig);
+  const result = await client.acceptBid({
+    taskId: params.task_id,
+    bidId: params.bid_id,
+    rejectCompeting: params.reject_competing,
+    signer: context.keypair,
+  });
+
+  return {
+    task_id: params.task_id,
+    bid_id: params.bid_id,
+    rejected_bid_ids: result.rejectedBidIds,
+    tx_digest: result.txDigest,
+  };
+}

package/src/tools/marketplace-bid.ts

@@ -0,0 +1,56 @@
+import { MarketplaceClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshMarketplaceBidParams {
+  task_id: string;
+  bid_price_mist: string | number;
+  reputation_score?: string | number;
+  evidence?: string;
+}
+
+export const meshMarketplaceBidTool = {
+  name: 'collective_marketplace_bid',
+  description: 'Place a marketplace bid on an open task',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: { type: 'string', description: 'Open task object id' },
+      bid_price_mist: { type: 'string', description: 'Bid price in MIST' },
+      reputation_score: { type: 'string', description: 'Optional reputation score override' },
+      evidence: { type: 'string', description: 'Optional proposal or qualifications blob content' },
+    },
+    required: ['task_id', 'bid_price_mist'],
+  },
+};
+
+export async function runMeshMarketplaceBid(
+  params: MeshMarketplaceBidParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const client = context.marketplaceClient ?? new MarketplaceClient(context.suiClient, context.networkConfig);
+  const result = await client.placeBid({
+    taskId: params.task_id,
+    bidPriceMist: parseMist(params.bid_price_mist, 'bid_price_mist'),
+    reputationScore: params.reputation_score == null ? undefined : parseMist(params.reputation_score, 'reputation_score'),
+    evidenceBlob: params.evidence,
+    signer: context.keypair,
+  });
+
+  return {
+    bid_id: result.bidId,
+    task_id: params.task_id,
+    tx_digest: result.txDigest,
+    reputation_score: result.reputationScore.toString(),
+  };
+}
+
+function parseMist(value: string | number, field: string): bigint {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    return BigInt(value.trim());
+  }
+  throw new Error(`${field} must be a non-negative integer string.`);
+}

package/src/tools/marketplace-browse.ts

@@ -0,0 +1,66 @@
+import { MarketplaceClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshMarketplaceBrowseParams {
+  category?: string;
+  min_price_mist?: string | number;
+  max_price_mist?: string | number;
+  limit?: number;
+}
+
+export const meshMarketplaceBrowseTool = {
+  name: 'collective_marketplace_browse',
+  description: 'Browse open marketplace tasks by category and price filters',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      category: { type: 'string', description: 'Optional marketplace category filter' },
+      min_price_mist: { type: 'string', description: 'Optional minimum escrow budget in MIST' },
+      max_price_mist: { type: 'string', description: 'Optional maximum escrow budget in MIST' },
+      limit: { type: 'number', description: 'Maximum number of open tasks to return (default 20)' },
+    },
+    required: [],
+  },
+};
+
+export async function runMeshMarketplaceBrowse(
+  params: MeshMarketplaceBrowseParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const client = context.marketplaceClient ?? new MarketplaceClient(context.suiClient, context.networkConfig);
+  const tasks = await client.browseOpenTasks({
+    category: params.category,
+    minPriceMist: parseOptionalMist(params.min_price_mist),
+    maxPriceMist: parseOptionalMist(params.max_price_mist),
+    limit: normalizeLimit(params.limit),
+  });
+
+  return {
+    tasks,
+    count: tasks.length,
+  };
+}
+
+function parseOptionalMist(value: string | number | undefined): bigint | undefined {
+  if (value == null) {
+    return undefined;
+  }
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    return BigInt(value.trim());
+  }
+  throw new Error('Price filters must be non-negative integer strings.');
+}
+
+function normalizeLimit(limit?: number): number {
+  if (limit == null) {
+    return 20;
+  }
+  if (!Number.isSafeInteger(limit) || limit <= 0) {
+    throw new Error('limit must be a positive integer.');
+  }
+  return limit;
+}

package/src/tools/marketplace-post.ts

@@ -0,0 +1,96 @@
+import { MarketplaceClient } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+const DEFAULT_DISPUTE_WINDOW_MS = 60_000;
+const DEFAULT_EXPIRY_HOURS = 24;
+
+export interface MeshMarketplacePostParams {
+  capability: string;
+  category: string;
+  price_mist: string | number;
+  input?: string;
+  input_blob_id?: string;
+  agreement_hash?: string;
+  dispute_window_ms?: number;
+  expiry_hours?: number;
+}
+
+export const meshMarketplacePostTool = {
+  name: 'collective_marketplace_post',
+  description: 'Post an open marketplace task with category metadata',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      capability: { type: 'string', description: 'Capability requested for the task' },
+      category: { type: 'string', description: 'Marketplace category used for browsing' },
+      price_mist: { type: 'string', description: 'Escrowed task budget in MIST' },
+      input: { type: 'string', description: 'Inline task input to upload to blob storage' },
+      input_blob_id: { type: 'string', description: 'Existing blob id containing task input' },
+      agreement_hash: { type: 'string', description: 'Optional agreement hash or plaintext summary' },
+      dispute_window_ms: { type: 'number', description: 'Optional dispute window override in milliseconds' },
+      expiry_hours: { type: 'number', description: 'Optional task expiry in hours' },
+    },
+    required: ['capability', 'category', 'price_mist'],
+  },
+};
+
+export async function runMeshMarketplacePost(
+  params: MeshMarketplacePostParams,
+  context: MeshToolContext,
+): Promise<Record<string, unknown>> {
+  const client = context.marketplaceClient ?? new MarketplaceClient(context.suiClient, context.networkConfig);
+  const inputBlobId = await resolveInputBlobId(params, context);
+  const result = await client.postOpenTask({
+    capability: params.capability,
+    category: params.category,
+    inputBlobId,
+    agreementHash: params.agreement_hash,
+    priceMist: parseMist(params.price_mist, 'price_mist'),
+    disputeWindowMs: normalizeNonNegativeInteger(params.dispute_window_ms, DEFAULT_DISPUTE_WINDOW_MS, 'dispute_window_ms'),
+    expiryHours: normalizeNonNegativeInteger(params.expiry_hours, DEFAULT_EXPIRY_HOURS, 'expiry_hours'),
+    signer: context.keypair,
+  });
+
+  return {
+    task_id: result.taskId,
+    tx_digest: result.txDigest,
+    capability: params.capability,
+    category: params.category,
+    input_blob_id: inputBlobId,
+  };
+}
+
+async function resolveInputBlobId(params: MeshMarketplacePostParams, context: MeshToolContext): Promise<string> {
+  if ((params.input_blob_id ? 1 : 0) + (params.input ? 1 : 0) !== 1) {
+    throw new Error('Provide exactly one of input or input_blob_id when posting a marketplace task');
+  }
+  if (params.input_blob_id) {
+    return params.input_blob_id;
+  }
+  if (!params.input) {
+    throw new Error('input or input_blob_id is required when posting a marketplace task');
+  }
+  const stored = await context.blobStore.store(new TextEncoder().encode(params.input));
+  return stored.blobId;
+}
+
+function parseMist(value: string | number, field: string): bigint {
+  if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0) {
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value.trim())) {
+    return BigInt(value.trim());
+  }
+  throw new Error(`${field} must be a non-negative integer string.`);
+}
+
+function normalizeNonNegativeInteger(value: number | undefined, fallback: number, field: string): number {
+  if (value == null) {
+    return fallback;
+  }
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new Error(`${field} must be a non-negative integer.`);
+  }
+  return value;
+}