subscribe

Instructions

Implementation Reference

• index.ts:1089-1135 (handler)

  Handler function for the 'subscribe' tool. Validates parameters, creates an Alchemy WebSocket subscription based on the type ('newHeads', 'logs', 'pendingTransactions', 'mined'), stores the subscription with a generated ID, and returns the subscriptionId.

  private async handleSubscribe(args: Record<string, unknown>) {
    const params = this.validateAndCastParams<SubscribeParams>(
      args,
      isValidSubscribeParams,
      "Invalid subscribe parameters"
    );
  
    const subscriptionId = Math.random().toString(36).substring(7);
    let subscription;
  
    switch (params.type) {
      case "newHeads":
        subscription = this.alchemy.ws.on("block", (blockNumber) => {
          console.log("[WebSocket] New block:", blockNumber);
        });
        break;
      case "logs":
        subscription = this.alchemy.ws.on(
          {
            address: params.address,
            topics: params.topics,
          },
          (log) => {
            console.log("[WebSocket] New log:", log);
          }
        );
        break;
      case "pendingTransactions":
        subscription = this.alchemy.ws.on("pending", (tx) => {
          console.log("[WebSocket] Pending transaction:", tx);
        });
        break;
      case "mined":
        subscription = this.alchemy.ws.on("mined", (tx) => {
          console.log("[WebSocket] Mined transaction:", tx);
        });
        break;
      default:
        throw new McpError(
          ErrorCode.InvalidParams,
          `Unknown subscription type: ${params.type}`
        );
    }
  
    this.activeSubscriptions.set(subscriptionId, subscription);
    return { subscriptionId };
  }

• index.ts:936-961 (registration)

  Registration of the 'subscribe' tool in the ListTools response, including name, description, and inputSchema.

  {
    name: "subscribe",
    description: "Subscribe to blockchain events",
    inputSchema: {
      type: "object",
      properties: {
        type: {
          type: "string",
          enum: ["newHeads", "logs", "pendingTransactions", "mined"],
          description: "The type of subscription",
        },
        address: {
          type: "string",
          description: "The address to filter by (for logs)",
        },
        topics: {
          type: "array",
          items: {
            type: "string",
          },
          description: "The topics to filter by (for logs)",
        },
      },
      required: ["type"],
    },
  },

• index.ts:93-97 (schema)

  Type definition for SubscribeParams used in the handler for input validation.

  type SubscribeParams = {
    type: string;
    address?: string;
    topics?: string[];
  };

• index.ts:1054-1065 (helper)

  Validation helper function isValidSubscribeParams used to validate subscribe parameters before casting.

  isValidSubscribeParams = (args: any): args is SubscribeParams => {
    return (
      typeof args === "object" &&
      args !== null &&
      typeof args.type === "string" &&
      ["newHeads", "logs", "pendingTransactions", "mined"].includes(
        args.type
      ) &&
      (args.address === undefined || typeof args.address === "string") &&
      (args.topics === undefined || Array.isArray(args.topics))
    );
  };

• index.ts:999-1001 (registration)

  Dispatcher switch case that routes 'subscribe' tool calls to the handleSubscribe handler.

  case "subscribe":
    result = await this.handleSubscribe(request.params.arguments);
    break;