query-actions

Instructions

Implementation Reference

• src/index.ts:75-87 (handler)

  MCP tool handler that destructures input parameters, invokes minaClient.queryActions with them, formats the result as JSON text content, and handles errors.

  async ({ address, tokenId, status, to, from, fromActionState, endActionState }) => {
    try {
      const result = await minaClient.queryActions({address, tokenId, status, to, from, fromActionState, endActionState});
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error) {
      throw new Error(`Failed to query actions: ${error}`);
    }
  }

• src/index.ts:66-74 (schema)

  Zod schema for input validation of the query-actions tool parameters, including required address and optional filters.

  {
    address: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{55,60}$/, 'Invalid Ethereum address format'),
    tokenId: z.string().optional().describe("Token ID to filter transactions"),
    status: z.enum(Object.values(BlockStatusFilter) as [BlockStatusFilter, ...BlockStatusFilter[]]).optional().describe("Transaction status to filter"),
    to: z.number().optional().describe("Block height to filter transactions"),
    from: z.number().optional().describe("Block height to filter transactions"),
    fromActionState: z.string().optional().describe("Action state to filter transactions"),
    endActionState: z.string().optional().describe("Action state to filter transactions"),
  },

• src/index.ts:63-88 (registration)

  Registration of the query-actions tool on the MCP server, specifying name, description, input schema, and handler function.

  server.tool(
      "query-actions",
      "Query actions from the Mina blockchain with optional filters",
      {
        address: z.string().regex(/^[1-9A-HJ-NP-Za-km-z]{55,60}$/, 'Invalid Ethereum address format'),
        tokenId: z.string().optional().describe("Token ID to filter transactions"),
        status: z.enum(Object.values(BlockStatusFilter) as [BlockStatusFilter, ...BlockStatusFilter[]]).optional().describe("Transaction status to filter"),
        to: z.number().optional().describe("Block height to filter transactions"),
        from: z.number().optional().describe("Block height to filter transactions"),
        fromActionState: z.string().optional().describe("Action state to filter transactions"),
        endActionState: z.string().optional().describe("Action state to filter transactions"),
      },
      async ({ address, tokenId, status, to, from, fromActionState, endActionState }) => {
        try {
          const result = await minaClient.queryActions({address, tokenId, status, to, from, fromActionState, endActionState});
          return {
            content: [{
              type: "text",
              text: JSON.stringify(result, null, 2)
            }]
          };
        } catch (error) {
          throw new Error(`Failed to query actions: ${error}`);
        }
      }
    );

• src/graphql-client.ts:208-253 (helper)

  Helper method in MinaGraphQLClient that builds the GraphQL query string from filter options and executes it to fetch action data from the Mina archive node API.

  async queryActions(filterOptions: ActionFilterOptions): Promise<{ actions: ActionOutput[] }> {
    // Convert filter options to GraphQL input format
    const inputParams = Object.entries(filterOptions)
      .filter(([_, value]) => value !== undefined)
      .map(([key, value]) => `${key}: ${typeof value === 'string' ? `"${value}"` : value}`)
      .join(', ');
  
    const query = `
      query {
        actions(input: {${inputParams}}) {
          blockInfo {
            height
            stateHash
            parentHash
            ledgerHash
            chainStatus
            timestamp
            globalSlotSinceHardfork
            globalSlotSinceGenesis
            distanceFromMaxBlockHeight
          }
          transactionInfo {
            status
            hash
            memo
            authorizationKind
            sequenceNumber
            zkappAccountUpdateIds
          }
          actionData {
            accountUpdateId
            data
          }
          actionState {
            actionStateOne
            actionStateTwo
            actionStateThree
            actionStateFour
            actionStateFive
          }
        }
      }
    `;
  
    return this.client.request(query);
  }