wc_status

Instructions

Implementation Reference

• packages/mcp/src/tools/wc-status.ts:13-35 (handler)

  Handler: registers the wc_status MCP tool. Calls GET /v1/wallet/wc/session with optional wallet_id query param and returns the WalletConnect session status (peer wallet, chain, expiry).

  export function registerWcStatus(
    server: McpServer,
    apiClient: ApiClient,
    walletContext?: WalletContext,
  ): void {
    server.tool(
      'wc_status',
      withWalletPrefix(
        'Get WalletConnect session status. Returns session info (peer wallet, chain, expiry) or error if no active session.',
        walletContext?.walletName,
      ),
      {
        wallet_id: z.string().optional().describe('Target wallet ID. Required for multi-wallet sessions; auto-resolved when session has a single wallet.'),
      },
      async (args) => {
        const params = new URLSearchParams();
        if (args.wallet_id) params.set('walletId', args.wallet_id);
        const qs = params.toString();
        const result = await apiClient.get('/v1/wallet/wc/session' + (qs ? '?' + qs : ''));
        return toToolResult(result);
      },
    );
  }

• packages/mcp/src/server.ts:108-108 (registration)

  Registration: import and call to registerWcStatus in createMcpServer, wiring it into the MCP server.

  registerWcStatus(server, apiClient, walletContext);

• packages/mcp/src/api-client.ts:37-90 (helper)

  Helper: toToolResult converts ApiResult to MCP CallToolResult format, handling success, session_expired, network_error, and actual API errors.

  export function toToolResult<T>(result: ApiResult<T>): CallToolResult {
    if ('ok' in result && result.ok) {
      return {
        content: [{ type: 'text', text: JSON.stringify(result.data) }],
      };
    }
  
    if ('expired' in result && result.expired) {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            session_expired: true,
            message: result.message,
            action: 'Run waiaas mcp setup to get a new token',
          }),
        }],
        // NO isError (H-04: prevents Claude Desktop from disconnecting)
      };
    }
  
    if ('networkError' in result && result.networkError) {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            network_error: true,
            message: result.message,
          }),
        }],
        // NO isError
      };
    }
  
    // Actual API error -- isError: true
    if ('error' in result) {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            error: true,
            ...result.error,
          }),
        }],
        isError: true,
      };
    }
  
    // Should never happen -- fallback
    return {
      content: [{ type: 'text', text: JSON.stringify({ error: true, message: 'Unknown error' }) }],
      isError: true,
    };
  }

• packages/mcp/src/tools/wc-status.ts:25-26 (schema)

  Schema: optional wallet_id input parameter defined with Zod (string), used when multi-wallet sessions exist.

    wallet_id: z.string().optional().describe('Target wallet ID. Required for multi-wallet sessions; auto-resolved when session has a single wallet.'),
  },

• packages/mcp/src/server.ts:74-76 (helper)

  Helper: withWalletPrefix prepends the wallet name to the tool description for multi-wallet identification.

  export function withWalletPrefix(description: string, walletName?: string): string {
    return walletName ? `[${walletName}] ${description}` : description;
  }