Shelv MCP Server

Instructions

Implementation Reference

• src/tools/get-shelf-tree.ts:17-50 (handler)

  Main implementation of get_shelf_tree tool. The registerGetShelfTreeTool function contains the handler logic that calls the shelv client's getTree method and formats the response with shelf_id, name, file_count, and files.

  export function registerGetShelfTreeTool(
    server: McpServer,
    context: ToolContext,
  ): void {
    server.registerTool(
      "get_shelf_tree",
      {
        title: "Get Shelf Tree",
        description: "Get the full file tree and file contents for a shelf",
        inputSchema,
        outputSchema,
        annotations: { readOnlyHint: true },
      },
      async (input, extra) => {
        try {
          const apiKey = context.getApiKey(extra);
          const client = context.createShelvClient(apiKey);
          const tree = await client.getTree(input.shelf_id);
  
          return successResult(
            `Loaded ${tree.fileCount} files for shelf ${tree.shelfPublicId}`,
            {
              shelf_id: tree.shelfPublicId,
              name: tree.name,
              file_count: tree.fileCount,
              files: tree.files,
            },
          );
        } catch (error) {
          return errorResult(error);
        }
      },
    );
  }

• src/tools/get-shelf-tree.ts:6-15 (schema)

  Input and output schema definitions for the get_shelf_tree tool. Input requires shelf_id (string), output returns shelf_id, name, file_count, and a record of files.

  const inputSchema = {
    shelf_id: z.string().min(1),
  };
  
  const outputSchema = {
    shelf_id: z.string(),
    name: z.string(),
    file_count: z.number(),
    files: z.record(z.string()),
  };

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

  Import statement for registerGetShelfTreeTool function from get-shelf-tree module.

  import { registerGetShelfTreeTool } from "./get-shelf-tree";

• src/tools/index.ts:10-23 (registration)

  registerShelvTools function that registers all tools including get_shelf_tree. The get_shelf_tree tool is always registered on line 15.

  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/tools/common.ts:5-25 (helper)

  Helper functions successResult and errorResult used by the get_shelf_tree handler to format tool execution responses.

  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),
      },
    };
  }