@hivemind-os/collective-mcp-server 0.2.0

package/src/tools/stake.ts

@@ -0,0 +1,103 @@
+import { StakingClient, STAKING_COOLDOWN_MS } from '@hivemind-os/collective-core';
+
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshStakeParams {
+  action: 'deposit' | 'status' | 'withdraw';
+  amount_sui?: string;
+  stake_type?: 'agent' | 'relay';
+}
+
+export const meshStakeTool = {
+  name: 'collective_stake',
+  description: 'Manage stake deposits, status, and withdrawals for the local Agentic Mesh identity',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      action: { type: 'string', enum: ['deposit', 'status', 'withdraw'] },
+      amount_sui: { type: 'string', description: 'SUI amount to deposit when action=deposit' },
+      stake_type: { type: 'string', enum: ['agent', 'relay'], description: 'Stake type for deposits (default agent)' },
+    },
+    required: ['action'],
+  },
+};
+
+export async function runMeshStake(params: MeshStakeParams, context: MeshToolContext): Promise<Record<string, unknown>> {
+  const client = context.stakingClient ?? new StakingClient(context.suiClient, context.networkConfig);
+  const owner = context.keypair.getPublicKey().toSuiAddress();
+
+  switch (params.action) {
+    case 'deposit': {
+      if (!params.amount_sui) {
+        throw new Error('amount_sui is required when action=deposit');
+      }
+      const amountMist = parseSuiToMist(params.amount_sui);
+      const result = await client.depositStake({
+        amountMist,
+        stakeType: params.stake_type ?? 'agent',
+        signer: context.keypair as never,
+      });
+      return {
+        action: 'deposit',
+        stake_id: result.stakeId,
+        tx_digest: result.txDigest,
+        amount_mist: amountMist.toString(),
+        amount_sui: params.amount_sui,
+        stake_type: params.stake_type ?? 'agent',
+      };
+    }
+    case 'status': {
+      const stake = await client.getStakeByOwner(owner);
+      return {
+        action: 'status',
+        owner,
+        staked: Boolean(stake),
+        stake,
+      };
+    }
+    case 'withdraw': {
+      const stake = await client.getStakeByOwner(owner);
+      if (!stake) {
+        throw new Error('No stake position found for this wallet.');
+      }
+      if (stake.deactivatedAt === 0) {
+        const result = await client.startDeactivation({ stakeId: stake.id, signer: context.keypair as never });
+        return {
+          action: 'deactivation_started',
+          stake_id: stake.id,
+          cooldown_ends_at: result.cooldownEndsAt,
+          tx_digest: result.txDigest,
+        };
+      }
+
+      const cooldownEndsAt = stake.deactivatedAt + STAKING_COOLDOWN_MS;
+      if (Date.now() < cooldownEndsAt) {
+        return {
+          action: 'cooling_down',
+          stake_id: stake.id,
+          cooldown_ends_at: cooldownEndsAt,
+          cooldown_remaining_ms: Math.max(cooldownEndsAt - Date.now(), 0),
+        };
+      }
+
+      const result = await client.withdrawStake({ stakeId: stake.id, signer: context.keypair as never });
+      return {
+        action: 'withdrawn',
+        stake_id: stake.id,
+        amount_returned_mist: result.amountReturned.toString(),
+        tx_digest: result.txDigest,
+      };
+    }
+    default:
+      throw new Error(`Unknown staking action: ${String(params.action)}`);
+  }
+}
+
+function parseSuiToMist(input: string): bigint {
+  const trimmed = input.trim();
+  if (!/^\d+(?:\.\d{1,9})?$/.test(trimmed)) {
+    throw new Error(`Invalid SUI amount: ${input}`);
+  }
+  const [whole, fraction = ''] = trimmed.split('.');
+  return BigInt(whole) * 1_000_000_000n + BigInt(fraction.padEnd(9, '0'));
+}

package/src/tools/task-history.ts

@@ -0,0 +1,86 @@
+import type { MeshToolContext } from '../context.js';
+
+export interface MeshTaskHistoryParams {
+  limit?: number;
+  status_filter?: string;
+}
+
+export const meshTaskHistoryTool = {
+  name: 'collective_task_history',
+  description: 'Query locally persisted task history',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      limit: { type: 'number', description: 'Max task rows to return (default 20)' },
+      status_filter: { type: 'string', description: 'Optional task status filter' },
+    },
+    required: [],
+  },
+};
+
+export async function runMeshTaskHistory(
+  params: MeshTaskHistoryParams,
+  context: MeshToolContext,
+): Promise<{ tasks: unknown[]; note?: string }> {
+  const db = context.taskHistoryDb as
+    | {
+        prepare?: (sql: string) => {
+          all: (...args: unknown[]) => unknown[];
+        };
+      }
+    | undefined;
+
+  if (!db?.prepare) {
+    return {
+      tasks: [],
+      note: 'Local task history is not initialized yet.',
+    };
+  }
+
+  const limit = normalizeLimit(params.limit);
+  const statusFilter = params.status_filter?.trim();
+
+  try {
+    const statement = statusFilter
+      ? db.prepare(
+          'SELECT * FROM task_history WHERE status = ? ORDER BY created_at DESC LIMIT ?',
+        )
+      : db.prepare('SELECT * FROM task_history ORDER BY created_at DESC LIMIT ?');
+    const rows = statusFilter ? statement.all(statusFilter, limit) : statement.all(limit);
+
+    return {
+      tasks: rows.map((row) => serializeBigInts(row)),
+    };
+  } catch {
+    return {
+      tasks: [],
+      note: 'Local task history database is not available yet.',
+    };
+  }
+}
+
+function normalizeLimit(limit?: number): number {
+  if (typeof limit !== 'number' || Number.isNaN(limit)) {
+    return 20;
+  }
+
+  return Math.max(1, Math.floor(limit));
+}
+
+function serializeBigInts(value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeBigInts(entry));
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, serializeBigInts(entry)]),
+    );
+  }
+
+  return value;
+}

package/src/tools/task-status.ts

@@ -0,0 +1,66 @@
+import { decodeMeteredResult, parseMeteredResultEnvelope } from '@hivemind-os/collective-core';
+import { TaskStatus } from '@hivemind-os/collective-types';
+
+import type { MeshToolContext } from '../context.js';
+import { fetchMeshBlob } from '../encryption.js';
+
+const decoder = new TextDecoder();
+
+export interface MeshTaskStatusParams {
+  task_id: string;
+}
+
+export const meshTaskStatusTool = {
+  name: 'collective_task_status',
+  description: 'Get task status and fetch the result if available',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      task_id: { type: 'string', description: 'Task object id' },
+    },
+    required: ['task_id'],
+  },
+};
+
+export async function runMeshTaskStatus(
+  params: MeshTaskStatusParams,
+  context: MeshToolContext,
+): Promise<{
+  task_id: string;
+  status: string;
+  provider_did?: string;
+  result?: string;
+  price_mist: string;
+  created_at: number;
+}> {
+  const task = await context.taskClient.getTask(params.task_id);
+  if (!task) {
+    throw new Error(`Task ${params.task_id} was not found.`);
+  }
+
+  let result: string | undefined;
+  if ((task.status === TaskStatus.COMPLETED || task.status === TaskStatus.RELEASED) && task.resultBlobId) {
+    const resultBytes = await fetchMeshBlob(context.blobStore, task.resultBlobId);
+    if (resultBytes) {
+      const envelope = parseMeteredResultEnvelope(resultBytes);
+      result = decoder.decode(envelope ? decodeMeteredResult(envelope) : resultBytes);
+    }
+  }
+
+  return {
+    task_id: task.id,
+    status: TaskStatus[task.status] ?? 'UNKNOWN',
+    provider_did: findProviderDid(context, task.provider),
+    result,
+    price_mist: task.price.toString(),
+    created_at: task.createdAt,
+  };
+}
+
+function findProviderDid(context: MeshToolContext, owner?: string): string | undefined {
+  if (!owner) {
+    return undefined;
+  }
+
+  return context.agentCache.getAllActive(1_000).find((agent) => agent.owner === owner)?.did;
+}

package/tests/analytics.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeshToolContext } from '../src/context.js';
+import { runMeshAnalytics } from '../src/tools/analytics.js';
+
+function createContext(): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {} as MeshToolContext['keypair'],
+    suiClient: {} as MeshToolContext['suiClient'],
+    registryClient: {} as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {} as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {} as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+    indexer: {
+      graphqlUrl: 'http://localhost:4000/graphql',
+      fetch: vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ data: { analytics: { totalTasks: 3 } } }),
+      }) as unknown as typeof fetch,
+    },
+  };
+}
+
+describe('runMeshAnalytics', () => {
+  it('queries analytics summary from the indexer', async () => {
+    const context = createContext();
+
+    const result = await runMeshAnalytics({ view: 'summary' }, context);
+
+    expect(result).toEqual({ view: 'summary', data: { totalTasks: 3 } });
+    expect(context.indexer?.fetch).toHaveBeenCalled();
+  });
+});

package/tests/auth-errors.test.ts

@@ -0,0 +1,85 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SessionExpiredError } from '@hivemind-os/collective-core';
+
+import { registerMeshTools, type MeshToolContext } from '../src/index.js';
+
+function createContext(): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {
+      getPublicKey: () => {
+        throw new SessionExpiredError();
+      },
+    } as MeshToolContext['keypair'],
+    suiClient: {
+      getBalance: vi.fn().mockResolvedValue(0n),
+      queryEvents: vi.fn(),
+    } as unknown as MeshToolContext['suiClient'],
+    registryClient: {
+      discoverByCapability: vi.fn().mockResolvedValue([]),
+      getAgentCard: vi.fn(),
+    } as unknown as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {
+      searchByCapability: vi.fn().mockReturnValue([]),
+      getAgentByDID: vi.fn(),
+      getAllActive: vi.fn().mockReturnValue([]),
+      upsertAgent: vi.fn(),
+      removeAgent: vi.fn(),
+    } as unknown as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {
+      getSpent: vi.fn().mockReturnValue(0n),
+    } as unknown as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+    authProvider: {
+      getSessionState: vi.fn().mockResolvedValue('reauth_required'),
+    } as never,
+  };
+}
+
+describe('MCP auth errors', () => {
+  it('returns a clear reauth message for expired sessions', async () => {
+    const handlers = new Map<unknown, (request: { params: { name: string; arguments?: unknown } }) => Promise<unknown>>();
+    const server = {
+      setRequestHandler: vi.fn((schema: unknown, handler: (request: { params: { name: string; arguments?: unknown } }) => Promise<unknown>) => {
+        handlers.set(schema, handler);
+      }),
+    } as unknown as Server;
+
+    registerMeshTools(server, createContext());
+
+    const callTool = handlers.get(CallToolRequestSchema);
+    const result = await callTool?.({
+      params: {
+        name: 'collective_balance',
+        arguments: {},
+      },
+    });
+
+    expect(result).toMatchObject({
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: expect.stringContaining('Authentication expired. Please re-authenticate via the daemon portal.'),
+        },
+      ],
+    });
+    expect(result).toMatchObject({
+      content: [
+        {
+          text: expect.stringContaining('"session_state": "reauth_required"'),
+        },
+      ],
+    });
+  });
+});

package/tests/balance.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MeshToolContext } from '../src/context.js';
+import { formatMistToSui, runMeshBalance } from '../src/tools/balance.js';
+
+describe('runMeshBalance', () => {
+  it('returns the correct balance payload', async () => {
+    const context = {
+      keypair: {
+        getPublicKey: () => ({
+          toSuiAddress: () => '0xabc',
+        }),
+      },
+      suiClient: {
+        getBalance: vi.fn().mockResolvedValue(1_500_000_000n),
+      },
+    } as unknown as MeshToolContext;
+
+    const result = await runMeshBalance({}, context);
+
+    expect(result).toEqual({
+      address: '0xabc',
+      balance_mist: '1500000000',
+      balance_sui: '1.5',
+    });
+  });
+
+  it('formats MIST into SUI correctly', () => {
+    expect(formatMistToSui(2_000_000_000n)).toBe('2');
+    expect(formatMistToSui(123_456_789n)).toBe('0.123456789');
+  });
+});

package/tests/context.test.ts

@@ -0,0 +1,112 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListResourceTemplatesRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SessionState } from '@hivemind-os/collective-core';
+
+import { registerMeshTools, type MeshToolContext } from '../src/index.js';
+
+function createContext(): MeshToolContext {
+  return {
+    did: 'did:mesh:test' as MeshToolContext['did'],
+    keypair: {
+      getPublicKey: () => ({
+        toSuiAddress: () => '0xabc',
+      }),
+    } as MeshToolContext['keypair'],
+    suiClient: {
+      getBalance: vi.fn().mockResolvedValue(0n),
+      queryEvents: vi.fn(),
+    } as unknown as MeshToolContext['suiClient'],
+    registryClient: {
+      discoverByCapability: vi.fn().mockResolvedValue([]),
+      getAgentCard: vi.fn(),
+    } as unknown as MeshToolContext['registryClient'],
+    taskClient: {} as MeshToolContext['taskClient'],
+    agentCache: {
+      searchByCapability: vi.fn().mockReturnValue([]),
+      getAgentByDID: vi.fn(),
+      getAllActive: vi.fn().mockReturnValue([]),
+      upsertAgent: vi.fn(),
+      removeAgent: vi.fn(),
+    } as unknown as MeshToolContext['agentCache'],
+    blobStore: {} as MeshToolContext['blobStore'],
+    spendingPolicy: {
+      getSpent: vi.fn().mockReturnValue(0n),
+    } as unknown as MeshToolContext['spendingPolicy'],
+    networkConfig: {
+      rpcUrl: 'http://127.0.0.1:9000',
+      faucetUrl: 'http://127.0.0.1:9123',
+      packageId: '0x1',
+      registryId: '0x2',
+    },
+  };
+}
+
+describe('MeshToolContext and registration', () => {
+  it('constructs a tool context with mocked dependencies', () => {
+    const context = createContext();
+
+    expect(context.did).toBe('did:mesh:test');
+    expect(context.networkConfig.packageId).toBe('0x1');
+  });
+
+  it('registers the expected tools and resources', async () => {
+    const handlers = new Map<unknown, (request?: unknown) => Promise<unknown>>();
+    const server = {
+      setRequestHandler: vi.fn((schema: unknown, handler: (request?: unknown) => Promise<unknown>) => {
+        handlers.set(schema, handler);
+      }),
+    } as unknown as Server;
+
+    registerMeshTools(server, createContext());
+
+    const listTools = await handlers.get(ListToolsRequestSchema)?.();
+    const listResources = await handlers.get(ListResourcesRequestSchema)?.();
+    const listTemplates = await handlers.get(ListResourceTemplatesRequestSchema)?.();
+
+    expect(listTools.tools).toHaveLength(20);
+    expect(listTools.tools.map((tool: { name: string }) => tool.name)).toContain('collective_relay_registry');
+    expect(listResources.resources).toHaveLength(2);
+    expect(listTemplates.resourceTemplates).toHaveLength(2);
+  });
+
+  it('includes auth session state in tool errors', async () => {
+    const handlers = new Map<unknown, (request?: unknown) => Promise<unknown>>();
+    const server = {
+      setRequestHandler: vi.fn((schema: unknown, handler: (request?: unknown) => Promise<unknown>) => {
+        handlers.set(schema, handler);
+      }),
+    } as unknown as Server;
+    const context = createContext();
+    context.suiClient = {
+      ...context.suiClient,
+      getBalance: vi.fn(async () => {
+        throw new Error('wallet unavailable');
+      }),
+    } as MeshToolContext['suiClient'];
+    context.authProvider = {
+      getSessionState: () => SessionState.NEEDS_REAUTH,
+    } as MeshToolContext['authProvider'];
+
+    registerMeshTools(server, context);
+
+    const callTool = await handlers.get(CallToolRequestSchema)?.({
+      params: {
+        name: 'collective_balance',
+        arguments: {},
+      },
+    });
+    const payload = JSON.parse(callTool.content[0].text) as Record<string, unknown>;
+
+    expect(callTool.isError).toBe(true);
+    expect(payload.error).toBe('wallet unavailable (session state: needs_reauth)');
+    expect(payload.session_state).toBe('needs_reauth');
+    expect(payload.reauth_required).toBe(false);
+  });
+});