Shelv MCP Server

Instructions

Implementation Reference

• src/tools/list-shelves.ts:32-66 (handler)

  Main tool registration and handler for list_shelves. This function registers the tool with the MCP server and implements the async handler that calls the HTTP client and formats the response.

  export function registerListShelvesTool(
    server: McpServer,
    context: ToolContext,
  ): void {
    server.registerTool(
      "list_shelves",
      {
        title: "List Shelves",
        description: "List shelves available to the authenticated user",
        inputSchema,
        outputSchema,
        annotations: { readOnlyHint: true },
      },
      async (input, extra) => {
        try {
          const apiKey = context.getApiKey(extra);
          const client = context.createHttpClient(apiKey);
          const result = await client.listShelves({
            page: input.page,
            limit: input.limit,
          });
  
          return successResult(
            `Loaded ${result.data.length} shelves (page ${result.pagination.page}/${result.pagination.totalPages})`,
            {
              shelves: result.data,
              pagination: result.pagination,
            },
          );
        } catch (error) {
          return errorResult(error);
        }
      },
    );
  }

• src/tools/list-shelves.ts:6-30 (schema)

  Input and output Zod schemas for the list_shelves tool. Defines the structure for pagination parameters (page, limit) and the response format with shelves array and pagination metadata.

  const inputSchema = {
    page: z.number().int().min(1).optional(),
    limit: z.number().int().min(1).max(100).optional(),
  };
  
  const outputSchema = {
    shelves: z.array(
      z.object({
        publicId: z.string(),
        name: z.string(),
        status: z.string(),
        template: z.string().nullable(),
        pageCount: z.number().nullable(),
        reviewMode: z.boolean(),
        createdAt: z.string(),
        updatedAt: z.string(),
      }),
    ),
    pagination: z.object({
      page: z.number(),
      limit: z.number(),
      total: z.number(),
      totalPages: z.number(),
    }),
  };

• src/tools/index.ts:1-24 (registration)

  Tool registration entry point. Imports registerListShelvesTool and calls it within registerShelvTools to add the tool to the MCP server.

  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import type { ToolContext } from "./context";
  import { registerCreateShelfTool } from "./create-shelf";
  import { registerGetShelfTreeTool } from "./get-shelf-tree";
  import { registerHydrateShelfTool } from "./hydrate-shelf";
  import { registerListShelvesTool } from "./list-shelves";
  import { registerReadShelfFileTool } from "./read-shelf-file";
  import { registerSearchShelfTool } from "./search-shelf";
  
  export function registerShelvTools(
    server: McpServer,
    context: ToolContext,
  ): void {
    registerListShelvesTool(server, context);
    registerGetShelfTreeTool(server, context);
    registerReadShelfFileTool(server, context);
    registerSearchShelfTool(server, context);
  
    if (context.config.enableWriteTools) {
      registerCreateShelfTool(server, context);
      registerHydrateShelfTool(server, context);
    }
  }

• src/http-client.ts:50-62 (helper)

  HTTP client method that makes the actual API request to list shelves. Handles pagination parameters and constructs the request URL.

  async listShelves(params?: {
    page?: number;
    limit?: number;
  }): Promise<ListShelvesResponse> {
    const search = new URLSearchParams();
    if (params?.page) search.set("page", String(params.page));
    if (params?.limit) search.set("limit", String(params.limit));
  
    const path =
      search.size > 0 ? `/v1/shelves?${search.toString()}` : "/v1/shelves";
  
    return this.requestJson<ListShelvesResponse>("GET", path);
  }

• src/tools/common.ts:5-25 (helper)

  Helper functions used by the list_shelves handler to format success and error responses in the MCP tool result format.

  export function successResult(
    text: string,
    structuredContent: Record<string, unknown>,
  ): CallToolResult {
    return {
      content: [{ type: "text", text }],
      structuredContent,
    };
  }
  
  export function errorResult(error: unknown): CallToolResult {
    const normalized = toMcpToolError(error, "Tool execution failed");
  
    return {
      isError: true,
      content: [{ type: "text", text: normalized.message }],
      structuredContent: {
        error: serializeToolError(normalized),
      },
    };
  }