@shelv/mcp 0.2.0

package/dist/bin/shelv-mcp.js

@@ -0,0 +1,1093 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { createShelvClient } from "@shelv/adapters";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/config.ts
+var API_BASE_URL = "https://api.shelv.dev";
+function parseBoolean(value, fallback) {
+  if (value === void 0) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1" || normalized === "yes") {
+    return true;
+  }
+  if (normalized === "false" || normalized === "0" || normalized === "no") {
+    return false;
+  }
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+function parseInteger(value, fallback, label) {
+  if (value === void 0 || value.trim() === "") {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return parsed;
+}
+function parseTransport(value) {
+  if (!value || value.trim() === "") {
+    return "stdio";
+  }
+  if (value === "stdio" || value === "http") {
+    return value;
+  }
+  throw new Error("SHELV_MCP_TRANSPORT must be either 'stdio' or 'http'");
+}
+function loadConfig(env = process.env) {
+  return {
+    apiBaseUrl: API_BASE_URL,
+    apiKey: env.SHELV_API_KEY?.trim() || void 0,
+    transport: parseTransport(env.SHELV_MCP_TRANSPORT),
+    httpHost: env.SHELV_MCP_HTTP_HOST?.trim() || "127.0.0.1",
+    httpPort: parseInteger(env.SHELV_MCP_HTTP_PORT, 3334, "SHELV_MCP_HTTP_PORT"),
+    enableWriteTools: parseBoolean(env.SHELV_MCP_ENABLE_WRITE_TOOLS, false),
+    searchMaxFiles: parseInteger(
+      env.SHELV_MCP_SEARCH_MAX_FILES,
+      500,
+      "SHELV_MCP_SEARCH_MAX_FILES"
+    ),
+    searchMaxBytes: parseInteger(
+      env.SHELV_MCP_SEARCH_MAX_BYTES,
+      5e6,
+      "SHELV_MCP_SEARCH_MAX_BYTES"
+    ),
+    searchMaxMatches: parseInteger(
+      env.SHELV_MCP_SEARCH_MAX_MATCHES,
+      200,
+      "SHELV_MCP_SEARCH_MAX_MATCHES"
+    ),
+    readMaxBytes: parseInteger(
+      env.SHELV_MCP_READ_MAX_BYTES,
+      25e4,
+      "SHELV_MCP_READ_MAX_BYTES"
+    )
+  };
+}
+
+// src/errors.ts
+import { AdapterError } from "@shelv/adapters";
+var McpToolError = class extends Error {
+  code;
+  status;
+  details;
+  retryable;
+  constructor(data, options) {
+    super(data.message, options);
+    this.name = "McpToolError";
+    this.code = data.code;
+    this.status = data.status;
+    this.details = data.details;
+    this.retryable = data.retryable;
+  }
+};
+var ApiRequestError = class extends Error {
+  method;
+  path;
+  status;
+  body;
+  constructor(method, path4, status, body, options) {
+    const message = typeof body === "object" && body !== null && "message" in body && typeof body.message === "string" ? body.message : `Shelv API request failed (${status})`;
+    super(message, options);
+    this.name = "ApiRequestError";
+    this.method = method;
+    this.path = path4;
+    this.status = status;
+    this.body = body;
+  }
+};
+function statusToCode(status) {
+  if (status === 400) return "INPUT_ERROR";
+  if (status === 401 || status === 403) return "AUTH_ERROR";
+  if (status === 402) return "BILLING_REQUIRED";
+  if (status === 404) return "NOT_FOUND";
+  if (status === 409) return "NOT_READY";
+  if (status === 429) return "RATE_LIMITED";
+  return "UPSTREAM_ERROR";
+}
+function extractStatusFromMessage(message) {
+  const match = message.match(/\((\d{3})\)/);
+  if (!match) return void 0;
+  const status = Number.parseInt(match[1] ?? "", 10);
+  return Number.isFinite(status) ? status : void 0;
+}
+function toMcpToolError(error, fallbackMessage = "Request failed") {
+  if (error instanceof McpToolError) {
+    return error;
+  }
+  if (error instanceof ApiRequestError) {
+    return new McpToolError(
+      {
+        code: statusToCode(error.status),
+        status: error.status,
+        message: error.message,
+        details: error.body,
+        retryable: error.status >= 500 || error.status === 429
+      },
+      { cause: error }
+    );
+  }
+  if (error instanceof AdapterError) {
+    if (error.code === "TREE_FETCH_FAILED") {
+      const status = extractStatusFromMessage(error.message);
+      return new McpToolError(
+        {
+          code: status ? statusToCode(status) : "UPSTREAM_ERROR",
+          status,
+          message: error.message,
+          retryable: status ? status >= 500 || status === 429 : false
+        },
+        { cause: error }
+      );
+    }
+    if (error.code === "ARCHIVE_TIMEOUT") {
+      return new McpToolError(
+        {
+          code: "UPSTREAM_ERROR",
+          message: error.message,
+          retryable: true
+        },
+        { cause: error }
+      );
+    }
+    if (error.code === "ARCHIVE_PARSE_FAILED") {
+      return new McpToolError(
+        {
+          code: "UPSTREAM_ERROR",
+          message: error.message,
+          retryable: false
+        },
+        { cause: error }
+      );
+    }
+    return new McpToolError(
+      {
+        code: "UPSTREAM_ERROR",
+        message: error.message,
+        retryable: false
+      },
+      { cause: error }
+    );
+  }
+  if (error instanceof Error) {
+    return new McpToolError(
+      {
+        code: "UPSTREAM_ERROR",
+        message: error.message || fallbackMessage,
+        retryable: false
+      },
+      { cause: error }
+    );
+  }
+  return new McpToolError({
+    code: "UPSTREAM_ERROR",
+    message: fallbackMessage,
+    details: error,
+    retryable: false
+  });
+}
+function serializeToolError(error) {
+  return {
+    code: error.code,
+    status: error.status,
+    details: error.details,
+    retryable: error.retryable,
+    message: error.message
+  };
+}
+
+// src/http-client.ts
+var ShelvHttpClient = class {
+  apiKey;
+  apiBaseUrl;
+  fetchImplementation;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.apiBaseUrl = config.apiBaseUrl.replace(/\/$/, "");
+    this.fetchImplementation = config.fetchImplementation ?? fetch;
+  }
+  async listShelves(params) {
+    const search = new URLSearchParams();
+    if (params?.page) search.set("page", String(params.page));
+    if (params?.limit) search.set("limit", String(params.limit));
+    const path4 = search.size > 0 ? `/v1/shelves?${search.toString()}` : "/v1/shelves";
+    return this.requestJson("GET", path4);
+  }
+  async createShelf(input) {
+    const formData = new FormData();
+    formData.append(
+      "file",
+      new Blob([Buffer.from(input.pdfBytes)], { type: "application/pdf" }),
+      input.fileName
+    );
+    if (input.name) formData.append("name", input.name);
+    if (input.template) formData.append("template", input.template);
+    if (typeof input.review === "boolean") {
+      formData.append("review", input.review ? "true" : "false");
+    }
+    return this.requestJson("POST", "/v1/shelves", {
+      body: formData
+    });
+  }
+  async requestJson(method, path4, options) {
+    const response = await this.fetchImplementation(`${this.apiBaseUrl}${path4}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: options?.body
+    });
+    if (!response.ok) {
+      throw new ApiRequestError(
+        method,
+        path4,
+        response.status,
+        await this.parseErrorBody(response)
+      );
+    }
+    return await response.json();
+  }
+  async parseErrorBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("application/json")) {
+      try {
+        return await response.json();
+      } catch {
+        return { message: "Failed to parse API error body" };
+      }
+    }
+    try {
+      return await response.text();
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/tools/create-shelf.ts
+import fs from "fs/promises";
+import path2 from "path";
+import { z } from "zod";
+
+// src/tools/common.ts
+import path from "path";
+function successResult(text, structuredContent) {
+  return {
+    content: [{ type: "text", text }],
+    structuredContent
+  };
+}
+function errorResult(error) {
+  const normalized = toMcpToolError(error, "Tool execution failed");
+  return {
+    isError: true,
+    content: [{ type: "text", text: normalized.message }],
+    structuredContent: {
+      error: serializeToolError(normalized)
+    }
+  };
+}
+function ensureRelativePath(inputPath) {
+  const trimmed = inputPath.trim();
+  if (!trimmed) {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "Path is required",
+      status: 400,
+      retryable: false
+    });
+  }
+  if (trimmed.includes("\\") || trimmed.includes("\0")) {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "Path contains unsupported characters",
+      status: 400,
+      retryable: false
+    });
+  }
+  const normalized = path.posix.normalize(trimmed);
+  if (normalized === "." || normalized === "") {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "Path must reference a file under the shelf root",
+      status: 400,
+      retryable: false
+    });
+  }
+  if (normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "Path traversal is not allowed",
+      status: 400,
+      retryable: false
+    });
+  }
+  return normalized;
+}
+function safeJoin(baseDir, relativePath) {
+  const resolvedBase = path.resolve(baseDir);
+  const candidate = path.resolve(resolvedBase, relativePath);
+  if (candidate !== resolvedBase && !candidate.startsWith(`${resolvedBase}${path.sep}`)) {
+    throw new McpToolError({
+      code: "LOCAL_IO_ERROR",
+      message: `Unsafe output path: ${relativePath}`,
+      retryable: false
+    });
+  }
+  return candidate;
+}
+function truncateUtf8(content, maxBytes) {
+  const totalBytes = Buffer.byteLength(content, "utf8");
+  if (totalBytes <= maxBytes) {
+    return { value: content, truncated: false, bytes: totalBytes };
+  }
+  let low = 0;
+  let high = content.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    const candidateBytes = Buffer.byteLength(content.slice(0, mid), "utf8");
+    if (candidateBytes <= maxBytes) {
+      low = mid;
+    } else {
+      high = mid - 1;
+    }
+  }
+  const value = content.slice(0, low);
+  return {
+    value,
+    truncated: true,
+    bytes: Buffer.byteLength(value, "utf8")
+  };
+}
+function inferContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === ".md") return "text/markdown";
+  if (ext === ".json") return "application/json";
+  if (ext === ".txt") return "text/plain";
+  return "text/plain";
+}
+
+// src/tools/create-shelf.ts
+var MAX_PDF_BYTES = 300 * 1024 * 1024;
+var inputSchema = {
+  pdf_path: z.string().min(1),
+  name: z.string().min(1).max(100).optional(),
+  template: z.enum(["book", "legal-contract", "academic-paper"]).optional(),
+  review: z.boolean().optional()
+};
+var outputSchema = {
+  shelf: 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()
+  })
+};
+async function assertPdfFile(filePath) {
+  const stats = await fs.stat(filePath).catch(() => null);
+  if (!stats || !stats.isFile()) {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "pdf_path must point to an existing file",
+      status: 400,
+      retryable: false
+    });
+  }
+  if (stats.size > MAX_PDF_BYTES) {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "PDF exceeds 300 MB limit",
+      status: 400,
+      retryable: false
+    });
+  }
+  if (path2.extname(filePath).toLowerCase() !== ".pdf") {
+    throw new McpToolError({
+      code: "INPUT_ERROR",
+      message: "Only .pdf files are supported",
+      status: 400,
+      retryable: false
+    });
+  }
+  const handle = await fs.open(filePath, "r");
+  try {
+    const header = Buffer.alloc(5);
+    await handle.read(header, 0, 5, 0);
+    if (header.toString("utf8") !== "%PDF-") {
+      throw new McpToolError({
+        code: "INPUT_ERROR",
+        message: "File does not appear to be a valid PDF",
+        status: 400,
+        retryable: false
+      });
+    }
+  } finally {
+    await handle.close();
+  }
+}
+function registerCreateShelfTool(server, context) {
+  server.registerTool(
+    "create_shelf",
+    {
+      title: "Create Shelf",
+      description: "Upload a local PDF and create a shelf",
+      inputSchema,
+      outputSchema,
+      annotations: { readOnlyHint: false }
+    },
+    async (input, extra) => {
+      try {
+        const absolutePath = path2.resolve(input.pdf_path);
+        await assertPdfFile(absolutePath);
+        const fileBytes = new Uint8Array(await fs.readFile(absolutePath));
+        const apiKey = context.getApiKey(extra);
+        const client = context.createHttpClient(apiKey);
+        const shelf = await client.createShelf({
+          pdfBytes: fileBytes,
+          fileName: path2.basename(absolutePath),
+          name: input.name,
+          template: input.template,
+          review: input.review
+        });
+        return successResult(`Created shelf ${shelf.publicId}`, { shelf });
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}
+
+// src/tools/get-shelf-tree.ts
+import { z as z2 } from "zod";
+var inputSchema2 = {
+  shelf_id: z2.string().min(1)
+};
+var outputSchema2 = {
+  shelf_id: z2.string(),
+  name: z2.string(),
+  file_count: z2.number(),
+  files: z2.record(z2.string())
+};
+function registerGetShelfTreeTool(server, context) {
+  server.registerTool(
+    "get_shelf_tree",
+    {
+      title: "Get Shelf Tree",
+      description: "Get the full file tree and file contents for a shelf",
+      inputSchema: inputSchema2,
+      outputSchema: outputSchema2,
+      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/hydrate-shelf.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+import { resolveShelfSource } from "@shelv/adapters";
+import { z as z3 } from "zod";
+var inputSchema3 = {
+  shelf_id: z3.string().min(1),
+  target_dir: z3.string().min(1),
+  overwrite: z3.boolean().optional()
+};
+var outputSchema3 = {
+  shelf_id: z3.string(),
+  source_kind: z3.enum(["archive", "tree"]),
+  target_dir: z3.string(),
+  files_written: z3.number(),
+  bytes_written: z3.number(),
+  archive_version: z3.string().nullable()
+};
+function registerHydrateShelfTool(server, context) {
+  server.registerTool(
+    "hydrate_shelf",
+    {
+      title: "Hydrate Shelf",
+      description: "Download and write shelf files into a local directory",
+      inputSchema: inputSchema3,
+      outputSchema: outputSchema3,
+      annotations: { readOnlyHint: false }
+    },
+    async (input, extra) => {
+      try {
+        const apiKey = context.getApiKey(extra);
+        const source = await resolveShelfSource({
+          client: context.createShelvClient(apiKey),
+          shelfPublicId: input.shelf_id,
+          mode: "archive-first"
+        });
+        const overwrite = input.overwrite ?? false;
+        const targetDir = path3.resolve(input.target_dir);
+        await fs2.mkdir(targetDir, { recursive: true });
+        let filesWritten = 0;
+        let bytesWritten = 0;
+        for (const [relativePath, content] of Object.entries(source.files)) {
+          const normalized = ensureRelativePath(relativePath);
+          const fullPath = safeJoin(targetDir, normalized);
+          if (!overwrite) {
+            const exists = await fs2.access(fullPath).then(() => true).catch(() => false);
+            if (exists) {
+              throw new McpToolError({
+                code: "LOCAL_IO_ERROR",
+                message: `Refusing to overwrite existing file: ${normalized}`,
+                retryable: false
+              });
+            }
+          }
+          await fs2.mkdir(path3.dirname(fullPath), { recursive: true });
+          await fs2.writeFile(fullPath, content, "utf8");
+          filesWritten += 1;
+          bytesWritten += Buffer.byteLength(content, "utf8");
+        }
+        return successResult(
+          `Hydrated ${filesWritten} files to ${targetDir}`,
+          {
+            shelf_id: input.shelf_id,
+            source_kind: source.kind,
+            target_dir: targetDir,
+            files_written: filesWritten,
+            bytes_written: bytesWritten,
+            archive_version: source.kind === "archive" ? source.archiveVersion : null
+          }
+        );
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}
+
+// src/tools/list-shelves.ts
+import { z as z4 } from "zod";
+var inputSchema4 = {
+  page: z4.number().int().min(1).optional(),
+  limit: z4.number().int().min(1).max(100).optional()
+};
+var outputSchema4 = {
+  shelves: z4.array(
+    z4.object({
+      publicId: z4.string(),
+      name: z4.string(),
+      status: z4.string(),
+      template: z4.string().nullable(),
+      pageCount: z4.number().nullable(),
+      reviewMode: z4.boolean(),
+      createdAt: z4.string(),
+      updatedAt: z4.string()
+    })
+  ),
+  pagination: z4.object({
+    page: z4.number(),
+    limit: z4.number(),
+    total: z4.number(),
+    totalPages: z4.number()
+  })
+};
+function registerListShelvesTool(server, context) {
+  server.registerTool(
+    "list_shelves",
+    {
+      title: "List Shelves",
+      description: "List shelves available to the authenticated user",
+      inputSchema: inputSchema4,
+      outputSchema: outputSchema4,
+      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/read-shelf-file.ts
+import { z as z5 } from "zod";
+var inputSchema5 = {
+  shelf_id: z5.string().min(1),
+  path: z5.string().min(1)
+};
+var outputSchema5 = {
+  shelf_id: z5.string(),
+  path: z5.string(),
+  content_type: z5.string(),
+  content: z5.string(),
+  bytes: z5.number(),
+  truncated: z5.boolean()
+};
+function registerReadShelfFileTool(server, context) {
+  server.registerTool(
+    "read_shelf_file",
+    {
+      title: "Read Shelf File",
+      description: "Read a single file from a shelf",
+      inputSchema: inputSchema5,
+      outputSchema: outputSchema5,
+      annotations: { readOnlyHint: true }
+    },
+    async (input, extra) => {
+      try {
+        const normalizedPath = ensureRelativePath(input.path);
+        const apiKey = context.getApiKey(extra);
+        const client = context.createShelvClient(apiKey);
+        const raw = await client.getFile(input.shelf_id, normalizedPath);
+        const truncated = truncateUtf8(raw, context.config.readMaxBytes);
+        return successResult(
+          truncated.truncated ? `Read ${normalizedPath} (truncated to ${truncated.bytes} bytes)` : `Read ${normalizedPath}`,
+          {
+            shelf_id: input.shelf_id,
+            path: normalizedPath,
+            content_type: inferContentType(normalizedPath),
+            content: truncated.value,
+            bytes: truncated.bytes,
+            truncated: truncated.truncated
+          }
+        );
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}
+
+// src/tools/search-shelf.ts
+import { resolveShelfSource as resolveShelfSource2 } from "@shelv/adapters";
+import { z as z6 } from "zod";
+var inputSchema6 = {
+  shelf_id: z6.string().min(1),
+  query: z6.string().min(1),
+  mode: z6.enum(["substring", "regex"]).optional(),
+  case_sensitive: z6.boolean().optional(),
+  max_matches: z6.number().int().min(1).optional()
+};
+var outputSchema6 = {
+  shelf_id: z6.string(),
+  query: z6.string(),
+  mode: z6.enum(["substring", "regex"]),
+  case_sensitive: z6.boolean(),
+  matches: z6.array(
+    z6.object({
+      path: z6.string(),
+      line: z6.string(),
+      line_number: z6.number(),
+      snippet: z6.string()
+    })
+  ),
+  scanned_files: z6.number(),
+  scanned_bytes: z6.number(),
+  truncated: z6.boolean()
+};
+function buildMatcher(query, mode, caseSensitive) {
+  if (mode === "regex") {
+    let regex;
+    try {
+      regex = new RegExp(query, caseSensitive ? "" : "i");
+    } catch {
+      throw new McpToolError({
+        code: "INPUT_ERROR",
+        message: "Invalid regular expression",
+        status: 400,
+        retryable: false
+      });
+    }
+    return (line) => regex.test(line);
+  }
+  const needle = caseSensitive ? query : query.toLowerCase();
+  return (line) => {
+    const haystack = caseSensitive ? line : line.toLowerCase();
+    return haystack.includes(needle);
+  };
+}
+function registerSearchShelfTool(server, context) {
+  server.registerTool(
+    "search_shelf",
+    {
+      title: "Search Shelf",
+      description: "Search for text across files in a shelf",
+      inputSchema: inputSchema6,
+      outputSchema: outputSchema6,
+      annotations: { readOnlyHint: true }
+    },
+    async (input, extra) => {
+      try {
+        const mode = input.mode ?? "substring";
+        const caseSensitive = input.case_sensitive ?? false;
+        const apiKey = context.getApiKey(extra);
+        const source = await resolveShelfSource2({
+          client: context.createShelvClient(apiKey),
+          shelfPublicId: input.shelf_id,
+          mode: "archive-first"
+        });
+        const matcher = buildMatcher(input.query, mode, caseSensitive);
+        const maxMatches = Math.min(
+          input.max_matches ?? context.config.searchMaxMatches,
+          context.config.searchMaxMatches
+        );
+        const matches = [];
+        let scannedFiles = 0;
+        let scannedBytes = 0;
+        let truncated = false;
+        for (const [filePath, content] of Object.entries(source.files)) {
+          if (scannedFiles >= context.config.searchMaxFiles) {
+            truncated = true;
+            break;
+          }
+          const bytes = Buffer.byteLength(content, "utf8");
+          if (scannedBytes + bytes > context.config.searchMaxBytes) {
+            truncated = true;
+            break;
+          }
+          scannedFiles += 1;
+          scannedBytes += bytes;
+          const lines = content.split(/\r?\n/);
+          for (let index = 0; index < lines.length; index += 1) {
+            const line = lines[index] || "";
+            if (!matcher(line)) continue;
+            matches.push({
+              path: filePath,
+              line,
+              line_number: index + 1,
+              snippet: line.slice(0, 300)
+            });
+            if (matches.length >= maxMatches) {
+              truncated = true;
+              break;
+            }
+          }
+          if (truncated) break;
+        }
+        return successResult(
+          `Found ${matches.length} matches across ${scannedFiles} files`,
+          {
+            shelf_id: input.shelf_id,
+            query: input.query,
+            mode,
+            case_sensitive: caseSensitive,
+            matches,
+            scanned_files: scannedFiles,
+            scanned_bytes: scannedBytes,
+            truncated
+          }
+        );
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}
+
+// src/tools/index.ts
+function registerShelvTools(server, context) {
+  registerListShelvesTool(server, context);
+  registerGetShelfTreeTool(server, context);
+  registerReadShelfFileTool(server, context);
+  registerSearchShelfTool(server, context);
+  if (context.config.enableWriteTools) {
+    registerCreateShelfTool(server, context);
+    registerHydrateShelfTool(server, context);
+  }
+}
+
+// src/server.ts
+function validateApiKey(token) {
+  const trimmed = token.trim();
+  if (!trimmed.startsWith("sk_")) {
+    throw new McpToolError({
+      code: "AUTH_ERROR",
+      message: "Shelv API key must use sk_ prefix",
+      status: 401,
+      retryable: false
+    });
+  }
+  return trimmed;
+}
+function createContext(config) {
+  return {
+    config,
+    getApiKey(extra) {
+      const authToken = extra?.authInfo?.token;
+      if (typeof authToken === "string" && authToken.trim().length > 0) {
+        return validateApiKey(authToken);
+      }
+      if (config.apiKey) {
+        return validateApiKey(config.apiKey);
+      }
+      throw new McpToolError({
+        code: "AUTH_ERROR",
+        message: "Missing Shelv API key. Set SHELV_API_KEY or provide Authorization bearer token.",
+        status: 401,
+        retryable: false
+      });
+    },
+    createShelvClient(apiKey) {
+      return createShelvClient({
+        apiKey,
+        apiBaseUrl: config.apiBaseUrl
+      });
+    },
+    createHttpClient(apiKey) {
+      return new ShelvHttpClient({
+        apiKey,
+        apiBaseUrl: config.apiBaseUrl
+      });
+    }
+  };
+}
+function createShelvMcpRuntime(env = process.env) {
+  const config = loadConfig(env);
+  const context = createContext(config);
+  const server = new McpServer(
+    {
+      name: "shelv-mcp",
+      version: "0.1.0"
+    },
+    {
+      instructions: "Shelv MCP server for creating, listing, reading, searching, and hydrating document shelves."
+    }
+  );
+  registerShelvTools(server, context);
+  return { server, config };
+}
+
+// src/transports/http.ts
+import { createServer } from "http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+var MCP_PATH = "/mcp";
+function stripPort(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[")) {
+    const end = trimmed.indexOf("]");
+    if (end >= 0) return trimmed.slice(1, end).toLowerCase();
+  }
+  const [host] = trimmed.split(":");
+  return (host || "").toLowerCase();
+}
+function getAllowedHosts(config) {
+  const configuredHost = stripPort(config.httpHost);
+  const hosts = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", configuredHost]);
+  return hosts;
+}
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    req.on("error", reject);
+    req.on("end", () => {
+      if (chunks.length === 0) {
+        resolve(void 0);
+        return;
+      }
+      const raw = Buffer.concat(chunks).toString("utf8");
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Invalid JSON request body"));
+      }
+    });
+  });
+}
+function respondJson(res, status, payload) {
+  if (res.writableEnded) return;
+  const body = JSON.stringify(payload);
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json");
+  res.end(body);
+}
+function validateHostAndOrigin(req, config) {
+  const allowedHosts = getAllowedHosts(config);
+  const hostHeader = req.headers.host;
+  if (hostHeader) {
+    const host = stripPort(hostHeader);
+    if (!allowedHosts.has(host)) {
+      return { ok: false, reason: "Host header is not allowed" };
+    }
+  }
+  const origin = req.headers.origin;
+  if (origin) {
+    try {
+      const originHost = stripPort(new URL(origin).host);
+      if (!allowedHosts.has(originHost)) {
+        return { ok: false, reason: "Origin is not allowed" };
+      }
+    } catch {
+      return { ok: false, reason: "Invalid Origin header" };
+    }
+  }
+  return { ok: true };
+}
+function parseAuth(req, config) {
+  const header = req.headers.authorization;
+  if (header === void 0 || header.trim() === "") {
+    if (config.apiKey) {
+      return {
+        ok: true,
+        auth: {
+          token: config.apiKey,
+          clientId: "env-fallback",
+          scopes: [],
+          expiresAt: void 0
+        }
+      };
+    }
+    return {
+      ok: false,
+      reason: "Missing Authorization header"
+    };
+  }
+  if (!header.startsWith("Bearer ")) {
+    return {
+      ok: false,
+      reason: "Authorization must use Bearer token"
+    };
+  }
+  const token = header.slice("Bearer ".length).trim();
+  if (!token.startsWith("sk_")) {
+    return {
+      ok: false,
+      reason: "Shelv API key must use sk_ prefix"
+    };
+  }
+  return {
+    ok: true,
+    auth: {
+      token,
+      clientId: "request-bearer",
+      scopes: [],
+      expiresAt: void 0
+    }
+  };
+}
+async function runHttpTransport(server, config) {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: void 0
+  });
+  await server.connect(transport);
+  const httpServer = createServer(async (req, res) => {
+    try {
+      const requestPath = req.url ? new URL(req.url, "http://localhost").pathname : "/";
+      if (requestPath !== MCP_PATH) {
+        respondJson(res, 404, { error: "Not found" });
+        return;
+      }
+      const method = req.method || "GET";
+      if (!["GET", "POST", "DELETE"].includes(method)) {
+        respondJson(res, 405, { error: "Method not allowed" });
+        return;
+      }
+      const security = validateHostAndOrigin(req, config);
+      if (!security.ok) {
+        respondJson(res, 403, { error: security.reason });
+        return;
+      }
+      const auth = parseAuth(req, config);
+      if (!auth.ok) {
+        respondJson(res, 401, { error: auth.reason });
+        return;
+      }
+      const authenticatedRequest = req;
+      authenticatedRequest.auth = auth.auth;
+      const body = method === "POST" ? await readJsonBody(req) : void 0;
+      await transport.handleRequest(authenticatedRequest, res, body);
+    } catch (error) {
+      respondJson(res, 500, {
+        error: error instanceof Error ? error.message : "Internal server error"
+      });
+    }
+  });
+  await new Promise((resolve, reject) => {
+    httpServer.once("error", reject);
+    httpServer.listen(config.httpPort, config.httpHost, () => {
+      httpServer.off("error", reject);
+      resolve();
+    });
+  });
+  const host = config.httpHost.includes(":") ? `[${config.httpHost}]` : config.httpHost;
+  const url = `http://${host}:${config.httpPort}${MCP_PATH}`;
+  return {
+    server: httpServer,
+    url,
+    close() {
+      return new Promise((resolve, reject) => {
+        httpServer.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  };
+}
+
+// src/transports/stdio.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+async function runStdioTransport(server) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// src/bin/shelv-mcp.ts
+async function main() {
+  const runtime = createShelvMcpRuntime();
+  if (runtime.config.transport === "stdio") {
+    if (!runtime.config.apiKey) {
+      throw new Error("SHELV_API_KEY is required in stdio mode");
+    }
+    await runStdioTransport(runtime.server);
+    return;
+  }
+  const http = await runHttpTransport(runtime.server, runtime.config);
+  console.error(`shelv-mcp listening at ${http.url}`);
+  console.error(
+    runtime.config.enableWriteTools ? "write tools enabled" : "write tools disabled (set SHELV_MCP_ENABLE_WRITE_TOOLS=true to enable)"
+  );
+}
+main().catch((error) => {
+  console.error(
+    error instanceof Error ? error.message : "Failed to start shelv-mcp"
+  );
+  process.exit(1);
+});
+//# sourceMappingURL=shelv-mcp.js.map