Sidearm MCP Server

Instructions

Implementation Reference

• src/tools/list-searches.ts:5-46 (handler)

  Main implementation of list_searches tool. Contains the tool registration, input schema definition (cursor and limit parameters), and the handler logic that makes an API call to /api/v1/search with pagination support.

  export function register(server: McpServer, api: ApiClient): void {
    server.tool(
      "list_searches",
      "List previous similarity searches performed on your account. " +
        "Returns a paginated list of past search queries with timestamps and result counts.",
      {
        cursor: z
          .string()
          .optional()
          .describe("Pagination cursor from a previous response"),
        limit: z
          .number()
          .int()
          .min(1)
          .max(100)
          .optional()
          .describe("Results per page (1-100, default: 20)"),
      },
      async (params) => {
        try {
          const result = await api.get("/api/v1/search", {
            cursor: params.cursor,
            limit: params.limit?.toString(),
          });
          return {
            content: [
              { type: "text" as const, text: JSON.stringify(result, null, 2) },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
              },
            ],
            isError: true as const,
          };
        }
      },
    );

• src/tools/list-searches.ts:11-22 (schema)

  Zod schema definition for list_searches tool parameters. Defines optional 'cursor' (pagination token) and 'limit' (1-100, default 20) parameters with validation.

    cursor: z
      .string()
      .optional()
      .describe("Pagination cursor from a previous response"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .optional()
      .describe("Results per page (1-100, default: 20)"),
  },

• src/index.ts:11-11 (registration)

  Import statement for listSearches function from ./tools/list-searches.js

  import { register as listSearches } from "./tools/list-searches.js";

• src/index.ts:51-51 (registration)

  Registration of list_searches tool by calling listSearches(server, api) in the server initialization

  listSearches(server, api);