@burdenoff/mcp-libs 2026.1008.4 → 2026.1009.2

package/dist/modules/files/index.cjs

@@ -37,12 +37,6 @@ function mcpToolName(productName, ...parts) {
 }
 
 // src/core/result.ts
-function jsonResult(data, structured) {
-  const result = {
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
-  };
-  return result;
-}
 function errorResult(message, hint) {
   const text = hint ? `${message}
 
@@ -50,449 +44,124 @@ Hint: ${hint}` : message;
   return { content: [{ type: "text", text }], isError: true };
 }
 
-// src/modules/files/operations.ts
-var BROWSE_FOLDER = `
-  query BrowseFolder($folderId: ID, $pagination: PaginationInput) {
-    getFolder(id: $folderId) {
-      id name path
-      files { id name size mimeType }
-      subFolders { id name path level }
-    }
-    getFilesInFolder(folderId: $folderId, pagination: $pagination) {
-      files { id name size mimeType extension createdAt }
-      total hasMore
-    }
-  }
-`;
-var LIST_FILES = `
-  query GetFiles($folderId: ID, $pagination: PaginationInput) {
-    getFiles(folderId: $folderId, pagination: $pagination) {
-      files {
-        id name description workspaceId folderId
-        mimeType extension size s3Key s3Bucket
-        downloadUrl status visibility
-        starred downloadCount viewCount sha256Hash
-        uploadedById createdAt updatedAt tags
-      }
-      total page limit hasMore
-    }
-  }
-`;
-var GET_FILE = `
-  query GetFile($id: ID!) {
-    getFile(id: $id) {
-      id name description workspaceId folderId
-      mimeType extension size s3Key s3Bucket
-      downloadUrl status visibility
-      starred downloadCount viewCount sha256Hash
-      uploadedById createdAt updatedAt tags
-    }
-  }
-`;
-var GET_FILE_DOWNLOAD_URL = `
-  query GetFileDownloadUrl($id: ID!, $expiresIn: Int) {
-    getFileDownloadUrl(id: $id, expiresIn: $expiresIn)
-  }
-`;
-var UPLOAD_FILE = `
-  mutation UploadFile($input: UploadFileInput!) {
-    uploadFile(input: $input) {
-      file {
-        id name description workspaceId folderId
-        mimeType extension size s3Key s3Bucket
-        status visibility uploadedById createdAt
-      }
-      uploadProgress
-      message
-    }
-  }
-`;
-var INITIATE_UPLOAD = `
-  mutation InitiateUpload($input: InitiateUploadInput!) {
-    initiateUpload(input: $input) {
-      session { id fileName fileSize s3Bucket s3Key }
-      uploadUrl
-      presignedUrls { partNumber url expiresAt }
-      multipartUploadId
-    }
-  }
-`;
-var COMPLETE_UPLOAD = `
-  mutation CompleteUpload($input: CompleteUploadInput!) {
-    completeUpload(input: $input) {
-      file { id name size s3Bucket s3Key downloadUrl }
-      fileId
-    }
-  }
-`;
-var CREATE_SHARE = `
-  mutation CreateShare($input: FileCreateShareInput!) {
-    createShare(input: $input) {
-      id token shareType accessLevel expiresAt requiresPassword
-      downloadCount maxDownloads createdAt
-    }
-  }
-`;
-var REVOKE_SHARE = `
-  mutation RevokeShare($id: ID!) {
-    revokeShare(id: $id) {
-      id revokedAt revokedBy
-    }
-  }
-`;
-
 // src/modules/files/tools.ts
-var VisibilityEnum = zod.z.enum(["PRIVATE", "TEAM", "WORKSPACE", "PUBLIC"]);
-var ShareAccessEnum = zod.z.enum(["VIEW", "COMMENT", "DOWNLOAD", "EDIT"]);
-var ShareTypeEnum = zod.z.enum(["PUBLIC_LINK", "EMAIL_INVITE", "GROUP_SHARE"]);
-function registerFilesTools(server, ctx, track) {
+function stubbedTool(server, toolName, title, description, featureNote, inputSchema, altSuggestions) {
   server.registerTool(
-    track(mcpToolName(ctx.productName, "files_browse")),
+    toolName,
     {
-      title: "Browse Folder",
-      description: "Browse a workspace folder. Returns subfolders and paginated files. Omit folderId to browse the root.",
-      inputSchema: {
-        folderId: zod.z.string().optional().describe("Folder ID (omit to browse root)"),
-        limit: zod.z.number().optional().describe("Page size (default 100)"),
-        offset: zod.z.number().optional().describe("Skip results")
-      }
+      title,
+      description: `${description} [STUB]`,
+      inputSchema
     },
-    async ({ folderId, limit, offset }) => {
-      try {
-        const pagination = {};
-        if (limit !== void 0) pagination.limit = limit;
-        if (offset !== void 0) pagination.offset = offset;
-        const data = await ctx.gql.workspace.request(BROWSE_FOLDER, {
-          folderId: folderId ?? null,
-          pagination: Object.keys(pagination).length > 0 ? pagination : void 0
-        });
-        return jsonResult({
-          folder: data.getFolder,
-          files: data.getFilesInFolder.files,
-          total: data.getFilesInFolder.total,
-          hasMore: data.getFilesInFolder.hasMore
-        });
-      } catch (error) {
-        ctx.logger.error("files_browse failed", { error });
-        return errorResult(
-          `Failed to browse folder: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    async () => errorResult(
+      `[stubbed] ${featureNote} Use ${altSuggestions.join(", ")} instead. The tool remains registered so callers receive a meaningful response instead of a schema-validation error.`
+    )
   );
-  server.registerTool(
-    track(mcpToolName(ctx.productName, "files_upload_initiate")),
-    {
-      title: "Initiate File Upload",
-      description: "Initiate a multipart upload session. Returns presigned URL(s) the caller must PUT bytes to, plus a sessionId to use with files_upload_complete. MCP cannot read local files; the caller is responsible for streaming bytes to the returned URL(s).",
-      inputSchema: {
-        fileName: zod.z.string().describe("File name including extension"),
-        fileSize: zod.z.number().describe("File size in bytes"),
-        sha256Hash: zod.z.string().describe("Hex SHA-256 of the file contents"),
-        mimeType: zod.z.string().optional().describe("MIME type (default: application/octet-stream)"),
-        extension: zod.z.string().optional().describe("File extension without leading dot"),
-        folderId: zod.z.string().optional().describe("Target folder ID"),
-        visibility: VisibilityEnum.optional().describe("Visibility (default: WORKSPACE)")
-      }
-    },
-    async ({ fileName, fileSize, sha256Hash, mimeType, extension, folderId, visibility }) => {
-      try {
-        const input = {
-          fileName,
-          fileSize,
-          sha256Hash,
-          mimeType: mimeType ?? "application/octet-stream",
-          visibility: visibility ?? "WORKSPACE"
-        };
-        if (extension !== void 0) input.extension = extension;
-        if (folderId !== void 0) input.folderId = folderId;
-        const data = await ctx.gql.workspace.request(INITIATE_UPLOAD, { input });
-        return jsonResult(data.initiateUpload);
-      } catch (error) {
-        ctx.logger.error("files_upload_initiate failed", { error });
-        return errorResult(
-          `Failed to initiate upload: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
-  );
-  server.registerTool(
-    track(mcpToolName(ctx.productName, "files_upload_complete")),
-    {
-      title: "Complete File Upload",
-      description: "Complete an in-flight upload session previously initiated by files_upload_initiate.",
-      inputSchema: {
-        sessionId: zod.z.string().describe("Session ID from files_upload_initiate"),
-        folderId: zod.z.string().optional().describe("Target folder ID (overrides initiate)"),
-        description: zod.z.string().optional().describe("File description")
-      }
-    },
-    async ({ sessionId, folderId, description }) => {
-      try {
-        const input = { sessionId };
-        if (folderId !== void 0) input.folderId = folderId;
-        if (description !== void 0) input.description = description;
-        const data = await ctx.gql.workspace.request(COMPLETE_UPLOAD, { input });
-        return jsonResult(data.completeUpload);
-      } catch (error) {
-        ctx.logger.error("files_upload_complete failed", { error });
-        return errorResult(
-          `Failed to complete upload: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
-  );
-  server.registerTool(
-    track(mcpToolName(ctx.productName, "files_share_create")),
-    {
-      title: "Create File Share",
-      description: "Create a shareable link for a file with optional access controls.",
-      inputSchema: {
-        fileId: zod.z.string().describe("File ID to share"),
-        access: ShareAccessEnum.optional().describe("Access level (default: DOWNLOAD)"),
-        expiresAt: zod.z.string().optional().describe("Expiry timestamp in ISO 8601"),
-        password: zod.z.string().optional().describe("Optional password to gate the share"),
-        maxDownloads: zod.z.number().optional().describe("Maximum download count")
-      }
-    },
-    async ({ fileId, access, expiresAt, password, maxDownloads }) => {
-      try {
-        const input = {
-          fileId,
-          shareType: "PUBLIC_LINK",
-          accessLevel: access ?? "DOWNLOAD"
-        };
-        if (expiresAt !== void 0) input.expiresAt = expiresAt;
-        if (password !== void 0) input.password = password;
-        if (maxDownloads !== void 0) input.maxDownloads = maxDownloads;
-        const data = await ctx.gql.workspace.request(CREATE_SHARE, { input });
-        return jsonResult(data.createShare);
-      } catch (error) {
-        ctx.logger.error("files_share_create failed", { error });
-        return errorResult(
-          `Failed to create share: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
-  );
-  server.registerTool(
-    track(mcpToolName(ctx.productName, "files_share_revoke")),
-    {
-      title: "Revoke File Share",
-      description: "Revoke a previously created file share by ID.",
-      inputSchema: {
-        id: zod.z.string().describe("Share ID to revoke")
-      }
-    },
-    async ({ id }) => {
-      try {
-        const data = await ctx.gql.workspace.request(REVOKE_SHARE, { id });
-        return jsonResult(data.revokeShare);
-      } catch (error) {
-        ctx.logger.error("files_share_revoke failed", { error });
-        return errorResult(
-          `Failed to revoke share: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+}
+function registerFilesTools(server, ctx, track) {
+  const featureNote = "Live alpha removed the `files` query family (workspace files are moving to a per-workspace service).";
+  const alts = [
+    "the next alpha release that re-exposes the files surface",
+    "the SDK files API (which the MCP will mirror once it lands)"
+  ];
+  stubbedTool(
+    server,
+    track(mcpToolName(ctx.productName, "files_browse")),
+    "Browse Folder",
+    "Browse a workspace folder. Returns subfolders and paginated files.",
+    featureNote,
+    { folderId: zod.z.string().optional().describe("Folder ID (omit to browse root)") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_list")),
-    {
-      title: "List Files",
-      description: "List files in a workspace, optionally scoped to a folder. Returns { files, total, page, limit, hasMore }.",
-      inputSchema: {
-        folderId: zod.z.string().optional().describe("Folder ID (omit to list workspace root)"),
-        limit: zod.z.number().optional().describe("Page size (default 50)"),
-        offset: zod.z.number().optional().describe("Skip results")
-      }
-    },
-    async ({ folderId, limit, offset }) => {
-      try {
-        const pagination = {};
-        if (limit !== void 0) pagination.limit = limit;
-        if (offset !== void 0) pagination.offset = offset;
-        const data = await ctx.gql.workspace.request(LIST_FILES, {
-          folderId: folderId ?? null,
-          pagination: Object.keys(pagination).length > 0 ? pagination : void 0
-        });
-        return jsonResult(data.getFiles);
-      } catch (error) {
-        ctx.logger.error("files_list failed", { error });
-        return errorResult(
-          `Failed to list files: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "List Files",
+    "List files in a workspace, optionally scoped to a folder.",
+    featureNote,
+    { folderId: zod.z.string().optional().describe("Folder ID (omit to list workspace root)") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_get")),
-    {
-      title: "Get File",
-      description: "Get a single file by ID. Returns the file record or an error if not found.",
-      inputSchema: { id: zod.z.string().describe("File ID") }
-    },
-    async ({ id }) => {
-      try {
-        const data = await ctx.gql.workspace.request(GET_FILE, { id });
-        if (!data.getFile) return errorResult(`File ${id} not found`);
-        return jsonResult(data.getFile);
-      } catch (error) {
-        ctx.logger.error("files_get failed", { error });
-        return errorResult(
-          `Failed to get file: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "Get File",
+    "Get a single file by ID. Returns the file record or an error if not found.",
+    featureNote,
+    { id: zod.z.string().describe("File ID") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_download")),
-    {
-      title: "Get File Download URL",
-      description: "Resolve a server-signed presigned download URL for a file. The MCP cannot stream binary bytes itself; callers must GET the returned URL out-of-band. Returns { url, expiresIn }.",
-      inputSchema: {
-        id: zod.z.string().describe("File ID"),
-        expiresIn: zod.z.number().optional().describe("URL TTL in seconds (server default applies when omitted)")
-      }
-    },
-    async ({ id, expiresIn }) => {
-      try {
-        const data = await ctx.gql.workspace.request(
-          GET_FILE_DOWNLOAD_URL,
-          { id, expiresIn }
-        );
-        return jsonResult({ url: data.getFileDownloadUrl, expiresIn: expiresIn ?? null });
-      } catch (error) {
-        ctx.logger.error("files_download failed", { error });
-        return errorResult(
-          `Failed to resolve download URL: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "Get File Download URL",
+    "Resolve a server-signed presigned download URL for a file.",
+    featureNote,
+    { id: zod.z.string().describe("File ID") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_upload")),
-    {
-      title: "Upload File",
-      description: "Single-shot file upload mirroring the SDK files.upload contract (s3Bucket/s3Key/size pre-resolved). For raw-byte uploads from MCP callers, prefer files_upload_initiate + files_upload_complete which use presigned URLs. Returns the persisted file record.",
-      inputSchema: {
-        name: zod.z.string().describe("Display filename including extension"),
-        mimeType: zod.z.string().describe("MIME type"),
-        extension: zod.z.string().describe("File extension without leading dot"),
-        size: zod.z.number().describe("File size in bytes"),
-        s3Bucket: zod.z.string().describe("S3 bucket holding the uploaded object"),
-        s3Key: zod.z.string().describe("S3 key under the bucket"),
-        description: zod.z.string().optional().describe("File description"),
-        folderId: zod.z.string().optional().describe("Target folder ID"),
-        visibility: VisibilityEnum.optional().describe("Visibility (default: WORKSPACE)"),
-        tags: zod.z.unknown().optional().describe("Optional entity-owned tags JSON array")
-      }
-    },
-    async ({
-      name,
-      mimeType,
-      extension,
-      size,
-      s3Bucket,
-      s3Key,
-      description,
-      folderId,
-      visibility,
-      tags
-    }) => {
-      try {
-        const input = {
-          name,
-          mimeType,
-          extension,
-          size: String(size),
-          s3Bucket,
-          s3Key
-        };
-        if (description !== void 0) input.description = description;
-        if (folderId !== void 0) input.folderId = folderId;
-        if (visibility !== void 0) input.visibility = visibility;
-        if (tags !== void 0) input.tags = tags;
-        const data = await ctx.gql.workspace.request(
-          UPLOAD_FILE,
-          { input }
-        );
-        return jsonResult(data.uploadFile);
-      } catch (error) {
-        ctx.logger.error("files_upload failed", { error });
-        return errorResult(
-          `Failed to upload file: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "Upload File",
+    "Single-shot file upload mirroring the SDK files.upload contract (s3Bucket/s3Key/size pre-resolved). For raw-byte uploads from MCP callers, prefer files_upload_initiate + files_upload_complete which use presigned URLs.",
+    featureNote,
+    { name: zod.z.string().describe("Display filename including extension") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
+    track(mcpToolName(ctx.productName, "files_upload_initiate")),
+    "Initiate File Upload",
+    "Initiate a multipart upload session. Returns presigned URL(s) the caller must PUT bytes to, plus a sessionId to use with files_upload_complete.",
+    featureNote,
+    { fileName: zod.z.string().describe("File name including extension") },
+    alts
+  );
+  stubbedTool(
+    server,
+    track(mcpToolName(ctx.productName, "files_upload_complete")),
+    "Complete File Upload",
+    "Complete an in-flight upload session previously initiated by files_upload_initiate.",
+    featureNote,
+    { sessionId: zod.z.string().describe("Session ID from files_upload_initiate") },
+    alts
+  );
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_share")),
-    {
-      title: "Share File",
-      description: "Create a share for a file (mirrors SDK files.share). Returns the persisted FileShare record.",
-      inputSchema: {
-        fileId: zod.z.string().describe("File ID to share"),
-        shareType: ShareTypeEnum.describe(
-          "Share type (PUBLIC_LINK = anonymous, EMAIL_INVITE = by email, GROUP_SHARE = by user IDs)"
-        ),
-        accessLevel: ShareAccessEnum.describe("Access level the share grants"),
-        expiresAt: zod.z.string().optional().describe("Expiry timestamp in ISO 8601"),
-        password: zod.z.string().optional().describe("Optional password to gate the share"),
-        maxDownloads: zod.z.number().optional().describe("Maximum download count"),
-        invitedEmail: zod.z.string().optional().describe("Email address for EMAIL_INVITE shares"),
-        invitedUserIds: zod.z.array(zod.z.string()).optional().describe("User IDs to grant access for GROUP_SHARE shares")
-      }
-    },
-    async ({
-      fileId,
-      shareType,
-      accessLevel,
-      expiresAt,
-      password,
-      maxDownloads,
-      invitedEmail,
-      invitedUserIds
-    }) => {
-      try {
-        const input = { fileId, shareType, accessLevel };
-        if (expiresAt !== void 0) input.expiresAt = expiresAt;
-        if (password !== void 0) input.password = password;
-        if (maxDownloads !== void 0) input.maxDownloads = maxDownloads;
-        if (invitedEmail !== void 0) input.invitedEmail = invitedEmail;
-        if (invitedUserIds !== void 0) input.invitedUserIds = invitedUserIds;
-        const data = await ctx.gql.workspace.request(CREATE_SHARE, {
-          input
-        });
-        return jsonResult(data.createShare);
-      } catch (error) {
-        ctx.logger.error("files_share failed", { error });
-        return errorResult(
-          `Failed to share file: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "Share File",
+    "Create a share for a file (mirrors SDK files.share).",
+    featureNote,
+    { fileId: zod.z.string().describe("File ID to share") },
+    alts
   );
-  server.registerTool(
+  stubbedTool(
+    server,
+    track(mcpToolName(ctx.productName, "files_share_create")),
+    "Create File Share",
+    "Create a shareable link for a file with optional access controls.",
+    featureNote,
+    { fileId: zod.z.string().describe("File ID to share") },
+    alts
+  );
+  stubbedTool(
+    server,
+    track(mcpToolName(ctx.productName, "files_share_revoke")),
+    "Revoke File Share",
+    "Revoke a previously created file share by ID.",
+    featureNote,
+    { id: zod.z.string().describe("Share ID to revoke") },
+    alts
+  );
+  stubbedTool(
+    server,
     track(mcpToolName(ctx.productName, "files_revoke")),
-    {
-      title: "Revoke File Share",
-      description: "Revoke an existing file share by ID (mirrors SDK files.shareApi.revoke). Returns the updated share record with revokedAt/revokedBy set.",
-      inputSchema: { id: zod.z.string().describe("Share ID to revoke") }
-    },
-    async ({ id }) => {
-      try {
-        const data = await ctx.gql.workspace.request(REVOKE_SHARE, {
-          id
-        });
-        return jsonResult(data.revokeShare);
-      } catch (error) {
-        ctx.logger.error("files_revoke failed", { error });
-        return errorResult(
-          `Failed to revoke share: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
+    "Revoke File Share",
+    "Revoke an existing file share by ID (mirrors SDK files.shareApi.revoke).",
+    featureNote,
+    { id: zod.z.string().describe("Share ID") },
+    alts
   );
 }