run-handler-using-handler-name

Implementation Reference

• src/mcp.ts:257-279 (registration)

  Registers the MCP tool 'run-handler-using-handler-name' with input schema, description, and a thin async handler that delegates to the runHandler helper function from helpers/handlers.ts.

  this.server.tool(
    "run-handler-using-handler-name",
    "run a handler using its name in an existing AO process",
    { processId: z.string(), handlerName: z.string(), data: z.string() },
    async ({ processId, handlerName, data }) => {
      const result = await runHandler(
        processId,
        handlerName,
        data,
        this.signer
      );
      if (result.Error) {
        return {
          content: [{ type: "text", text: cleanOutput(result.Error) }],
        };
      }
      return {
        content: [
          { type: "text", text: cleanOutput(result.Messages[0].Data) },
        ],
      };
    }
  );

• src/mcp.ts:260-260 (schema)

  Zod schema defining the input parameters for the tool: processId, handlerName, and data.

  { processId: z.string(), handlerName: z.string(), data: z.string() },

• src/helpers/handlers.ts:55-76 (helper)

  Core helper function that implements the logic to run a named handler in an AO process by sending a message with 'Action' tag set to handlerName and the provided data, then retrieving the result using aoconnect APIs.

  export async function runHandler(
    processId: string,
    handlerName: string,
    data: string,
    signer: any
  ) {
    const messageId = await message({
      process: processId,
      signer,
      data,
      tags: [{ name: "Action", value: handlerName }],
    });
  
    await sleep(100);
  
    const outputResult = await result({
      message: messageId,
      process: processId,
    });
  
    return outputResult;
  }

• src/local/index.js:326-340 (registration)

  Alternative registration of the same tool in the local development server (src/local/index.js), using an inline runHandler implementation.

  server.tool(
    "run-handler-using-handler-name",
    { processId: z.string(), handlerName: z.string(), data: z.string() },
    async ({ processId, handlerName, data }) => {
      const result2 = await runHandler(processId, handlerName, data);
      if (result2.Error) {
        return {
          content: [{ type: "text", text: cleanOutput(result2.Error) }],
        };
      }
      return {
        content: [{ type: "text", text: cleanOutput(result2.Messages[0].Data) }],
      };
    }
  );

• src/local/index.js:229-242 (helper)

  Inline helper function runHandler in local/index.js, identical logic to the exported one in helpers/handlers.ts.

  async function runHandler(processId, handlerName, data) {
    const messageId = await message({
      process: processId,
      signer,
      data,
      tags: [{ name: "Action", value: handlerName }],
    });
    await sleep(100);
    const outputResult = await result({
      message: messageId,
      process: processId,
    });
    return outputResult;
  }