@sendsafely/mcp-server-local 0.0.0-stage → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +22 -0
  3. package/README.md +390 -2
  4. package/dist/context.d.ts +2 -0
  5. package/dist/context.js +21 -0
  6. package/dist/credentials.d.ts +7 -0
  7. package/dist/credentials.js +59 -0
  8. package/dist/server.d.ts +2 -0
  9. package/dist/server.js +47 -0
  10. package/dist/setupCredentials.d.ts +2 -0
  11. package/dist/setupCredentials.js +151 -0
  12. package/dist/trustedDeviceKeyStore.d.ts +3 -0
  13. package/dist/trustedDeviceKeyStore.js +34 -0
  14. package/node_modules/@sendsafely/mcp-tools-core/LICENSE +201 -0
  15. package/node_modules/@sendsafely/mcp-tools-core/dist/approval.d.ts +51 -0
  16. package/node_modules/@sendsafely/mcp-tools-core/dist/approval.js +148 -0
  17. package/node_modules/@sendsafely/mcp-tools-core/dist/constants.d.ts +5 -0
  18. package/node_modules/@sendsafely/mcp-tools-core/dist/constants.js +8 -0
  19. package/node_modules/@sendsafely/mcp-tools-core/dist/context.d.ts +25 -0
  20. package/node_modules/@sendsafely/mcp-tools-core/dist/context.js +16 -0
  21. package/node_modules/@sendsafely/mcp-tools-core/dist/index.d.ts +18 -0
  22. package/node_modules/@sendsafely/mcp-tools-core/dist/index.js +17 -0
  23. package/node_modules/@sendsafely/mcp-tools-core/dist/instructions.d.ts +1 -0
  24. package/node_modules/@sendsafely/mcp-tools-core/dist/instructions.js +17 -0
  25. package/node_modules/@sendsafely/mcp-tools-core/dist/jsonResult.d.ts +3 -0
  26. package/node_modules/@sendsafely/mcp-tools-core/dist/jsonResult.js +15 -0
  27. package/node_modules/@sendsafely/mcp-tools-core/dist/recipientAddContext.d.ts +42 -0
  28. package/node_modules/@sendsafely/mcp-tools-core/dist/recipientAddContext.js +182 -0
  29. package/node_modules/@sendsafely/mcp-tools-core/dist/runTool.d.ts +2 -0
  30. package/node_modules/@sendsafely/mcp-tools-core/dist/runTool.js +22 -0
  31. package/node_modules/@sendsafely/mcp-tools-core/dist/safeHandler.d.ts +17 -0
  32. package/node_modules/@sendsafely/mcp-tools-core/dist/safeHandler.js +32 -0
  33. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/clientFactory.d.ts +17 -0
  34. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/clientFactory.js +29 -0
  35. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/oauthError.d.ts +9 -0
  36. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/oauthError.js +34 -0
  37. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/sdkPromise.d.ts +53 -0
  38. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/sdkPromise.js +462 -0
  39. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/signedFetch.d.ts +6 -0
  40. package/node_modules/@sendsafely/mcp-tools-core/dist/sdk/signedFetch.js +28 -0
  41. package/node_modules/@sendsafely/mcp-tools-core/dist/store/keyStore.d.ts +6 -0
  42. package/node_modules/@sendsafely/mcp-tools-core/dist/store/keyStore.js +1 -0
  43. package/node_modules/@sendsafely/mcp-tools-core/dist/store/packageSecretCache.d.ts +18 -0
  44. package/node_modules/@sendsafely/mcp-tools-core/dist/store/packageSecretCache.js +39 -0
  45. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/createDirectory.d.ts +9 -0
  46. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/createDirectory.js +53 -0
  47. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/deleteDirectory.d.ts +10 -0
  48. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/deleteDirectory.js +46 -0
  49. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/deleteFile.d.ts +11 -0
  50. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/deleteFile.js +53 -0
  51. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getActivityLog.d.ts +8 -0
  52. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getActivityLog.js +44 -0
  53. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getDirectory.d.ts +12 -0
  54. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getDirectory.js +51 -0
  55. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getEnterpriseInfo.d.ts +5 -0
  56. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getEnterpriseInfo.js +27 -0
  57. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getFileInformation.d.ts +9 -0
  58. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getFileInformation.js +34 -0
  59. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getPackageInformation.d.ts +7 -0
  60. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getPackageInformation.js +41 -0
  61. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getReceivedPackages.d.ts +5 -0
  62. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getReceivedPackages.js +54 -0
  63. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getRecipient.d.ts +8 -0
  64. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getRecipient.js +30 -0
  65. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getSentPackages.d.ts +7 -0
  66. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getSentPackages.js +84 -0
  67. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getWorkspaces.d.ts +5 -0
  68. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/getWorkspaces.js +114 -0
  69. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/index.d.ts +46 -0
  70. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/index.js +92 -0
  71. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/moveDirectory.d.ts +9 -0
  72. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/moveDirectory.js +39 -0
  73. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/removeRecipient.d.ts +8 -0
  74. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/removeRecipient.js +34 -0
  75. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/renameDirectory.d.ts +9 -0
  76. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/renameDirectory.js +34 -0
  77. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/setRecipientPhoneNumber.d.ts +10 -0
  78. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/setRecipientPhoneNumber.js +40 -0
  79. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addPackageMessage.d.ts +9 -0
  80. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addPackageMessage.js +37 -0
  81. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipient.d.ts +9 -0
  82. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipient.js +109 -0
  83. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipientWithSms.d.ts +11 -0
  84. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipientWithSms.js +115 -0
  85. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipientsBulk.d.ts +9 -0
  86. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/addRecipientsBulk.js +110 -0
  87. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/createPackage.d.ts +6 -0
  88. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/createPackage.js +65 -0
  89. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/createWorkspace.d.ts +10 -0
  90. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/createWorkspace.js +107 -0
  91. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/deletePackage.d.ts +10 -0
  92. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/deletePackage.js +39 -0
  93. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/downloadFileFromDirectory.d.ts +12 -0
  94. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/downloadFileFromDirectory.js +91 -0
  95. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/downloadPackageFiles.d.ts +12 -0
  96. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/downloadPackageFiles.js +205 -0
  97. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/finalizePackage.d.ts +9 -0
  98. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/finalizePackage.js +111 -0
  99. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/finalizeUndisclosedPackage.d.ts +9 -0
  100. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/finalizeUndisclosedPackage.js +57 -0
  101. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/generateTrustedDeviceKeypair.d.ts +10 -0
  102. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/generateTrustedDeviceKeypair.js +75 -0
  103. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageInformationFromLink.d.ts +8 -0
  104. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageInformationFromLink.js +50 -0
  105. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageKeycode.d.ts +11 -0
  106. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageKeycode.js +120 -0
  107. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageMessage.d.ts +9 -0
  108. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/getPackageMessage.js +59 -0
  109. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/listDownloadedFiles.d.ts +5 -0
  110. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/listDownloadedFiles.js +71 -0
  111. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/readDownloadedFile.d.ts +8 -0
  112. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/readDownloadedFile.js +176 -0
  113. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/uploadFile.d.ts +12 -0
  114. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/stdio/uploadFile.js +69 -0
  115. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updateFile.d.ts +9 -0
  116. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updateFile.js +38 -0
  117. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updatePackage.d.ts +14 -0
  118. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updatePackage.js +122 -0
  119. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updateRecipientRole.d.ts +9 -0
  120. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/updateRecipientRole.js +45 -0
  121. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/verifyCredentials.d.ts +5 -0
  122. package/node_modules/@sendsafely/mcp-tools-core/dist/tools/verifyCredentials.js +27 -0
  123. package/node_modules/@sendsafely/mcp-tools-core/dist/types/sendsafely.d.ts +432 -0
  124. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageChecksum.d.ts +1 -0
  125. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageChecksum.js +7 -0
  126. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageDir.d.ts +8 -0
  127. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageDir.js +50 -0
  128. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageLink.d.ts +2 -0
  129. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/packageLink.js +4 -0
  130. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/sanitizeFilename.d.ts +4 -0
  131. package/node_modules/@sendsafely/mcp-tools-core/dist/utils/sanitizeFilename.js +8 -0
  132. package/node_modules/@sendsafely/mcp-tools-core/package.json +40 -0
  133. package/npm-shrinkwrap.json +1632 -0
  134. package/package.json +58 -4
@@ -0,0 +1,148 @@
1
+ import { z } from "zod";
2
+ import { jsonError } from "./jsonResult.js";
3
+ import { sanitizeForPrompt } from "./utils/sanitizeFilename.js";
4
+ export function elicitationUnsupportedConsentPrompt(action, optInParam) {
5
+ return ("The connected MCP client does not support elicitation, so an approval " +
6
+ `prompt cannot be shown before this action would ${action}. Do not set ` +
7
+ `${optInParam}=true on your own initiative. ASK THE USER directly, in ` +
8
+ "your reply, whether they want to proceed without a guaranteed approval " +
9
+ "prompt — make clear there is no UI confirmation in this client. ONLY " +
10
+ `if they explicitly agree, call this tool again with ${optInParam}=true.`);
11
+ }
12
+ export async function requireUserApproval(server, message) {
13
+ const capabilities = server.getClientCapabilities();
14
+ const supportsElicitation = Boolean(capabilities?.elicitation?.form);
15
+ if (!supportsElicitation) {
16
+ const clientInfo = server.getClientVersion();
17
+ const clientId = clientInfo
18
+ ? `${clientInfo.name} ${clientInfo.version}`
19
+ : "unknown client";
20
+ process.stderr.write(`[WARN] Client '${clientId}' does not support MCP elicitation; ` +
21
+ `returning "unsupported"; gated tools will deny until the user opts in.\n`);
22
+ return { outcome: "unsupported" };
23
+ }
24
+ try {
25
+ const result = await server.elicitInput({
26
+ message: sanitizeForPrompt(message),
27
+ requestedSchema: {
28
+ type: "object",
29
+ properties: {
30
+ approve: {
31
+ type: "boolean",
32
+ description: "Approve this operation?",
33
+ },
34
+ },
35
+ required: ["approve"],
36
+ },
37
+ });
38
+ if (result.action === "accept") {
39
+ if (result.content?.approve === true) {
40
+ return { outcome: "approved" };
41
+ }
42
+ return {
43
+ outcome: "declined",
44
+ reason: "User did not grant approval.",
45
+ };
46
+ }
47
+ if (result.action === "decline") {
48
+ return { outcome: "declined", reason: "User declined the operation." };
49
+ }
50
+ if (result.action === "cancel") {
51
+ return {
52
+ outcome: "cancelled",
53
+ reason: "User cancelled the authorization prompt.",
54
+ };
55
+ }
56
+ return {
57
+ outcome: "error",
58
+ message: `Unknown elicitation action: ${String(result.action)}`,
59
+ };
60
+ }
61
+ catch (err) {
62
+ const msg = err instanceof Error ? err.message : String(err);
63
+ return { outcome: "error", message: `Authorization prompt failed: ${msg}` };
64
+ }
65
+ }
66
+ export async function requireUserChoice(server, message, choices) {
67
+ const capabilities = server.getClientCapabilities();
68
+ const supportsElicitation = Boolean(capabilities?.elicitation?.form);
69
+ if (!supportsElicitation) {
70
+ const clientInfo = server.getClientVersion();
71
+ const clientId = clientInfo
72
+ ? `${clientInfo.name} ${clientInfo.version}`
73
+ : "unknown client";
74
+ process.stderr.write(`[WARN] Client '${clientId}' does not support MCP elicitation; ` +
75
+ `requireUserChoice falling back to "unsupported".\n`);
76
+ return { outcome: "unsupported" };
77
+ }
78
+ const enumValues = choices.map((c) => c.value);
79
+ const enumNames = choices.map((c) => c.label);
80
+ try {
81
+ const result = await server.elicitInput({
82
+ message: sanitizeForPrompt(message),
83
+ requestedSchema: {
84
+ type: "object",
85
+ properties: {
86
+ choice: {
87
+ type: "string",
88
+ description: "Pick one of the listed options.",
89
+ enum: enumValues,
90
+ enumNames,
91
+ },
92
+ },
93
+ required: ["choice"],
94
+ },
95
+ });
96
+ if (result.action === "accept") {
97
+ const picked = typeof result.content?.choice === "string"
98
+ ? result.content.choice
99
+ : undefined;
100
+ if (picked && enumValues.includes(picked)) {
101
+ return { outcome: "selected", value: picked };
102
+ }
103
+ return {
104
+ outcome: "error",
105
+ message: `Elicitation returned an unexpected choice: ${String(picked)}`,
106
+ };
107
+ }
108
+ if (result.action === "decline") {
109
+ return { outcome: "declined", reason: "User declined the prompt." };
110
+ }
111
+ if (result.action === "cancel") {
112
+ return {
113
+ outcome: "cancelled",
114
+ reason: "User cancelled the prompt.",
115
+ };
116
+ }
117
+ return {
118
+ outcome: "error",
119
+ message: `Unknown elicitation action: ${String(result.action)}`,
120
+ };
121
+ }
122
+ catch (err) {
123
+ const msg = err instanceof Error ? err.message : String(err);
124
+ return { outcome: "error", message: `Choice prompt failed: ${msg}` };
125
+ }
126
+ }
127
+ export const CONSENT_FALLBACK_INSTRUCTIONS = "On a client without elicitation support, ask the user in your reply " +
128
+ "and call again with proceed_without_prompt=true once they agree.";
129
+ export const proceedWithoutPromptSchema = z
130
+ .boolean()
131
+ .optional()
132
+ .describe("Records the user's explicit, in-conversation agreement to proceed " +
133
+ "on a client that does not support elicitation. Do not set it on " +
134
+ "your own initiative — but when the user has clearly agreed, set " +
135
+ "it to true so the action they asked for can complete.");
136
+ export function approvalGateError(approval, action, options = {}) {
137
+ const prefix = options.abortPrefix ?? "Operation aborted";
138
+ if (approval.outcome === "declined" || approval.outcome === "cancelled") {
139
+ return jsonError(`${prefix}: ${approval.reason}`);
140
+ }
141
+ if (approval.outcome === "error") {
142
+ return jsonError(`${prefix}: ${approval.message}`);
143
+ }
144
+ if (approval.outcome === "unsupported" && !options.proceedWithoutPrompt) {
145
+ return jsonError(elicitationUnsupportedConsentPrompt(action, "proceed_without_prompt"));
146
+ }
147
+ return undefined;
148
+ }
@@ -0,0 +1,5 @@
1
+ export declare const SENDSAFELY_DOWNLOAD_DIR: string;
2
+ export declare const MAX_FILE_READ_SIZE: number;
3
+ export declare const MAX_TEXT_PREVIEW = 100000;
4
+ export declare const MAX_PDF_PAGES = 50;
5
+ export declare const MCP_REQUEST_API = "MCP";
@@ -0,0 +1,8 @@
1
+ import os from "node:os";
2
+ import path from "node:path";
3
+ export const SENDSAFELY_DOWNLOAD_DIR = process.env.SENDSAFELY_DOWNLOAD_DIR ??
4
+ path.join(os.tmpdir(), "sendsafely_downloads");
5
+ export const MAX_FILE_READ_SIZE = 10 * 1024 * 1024;
6
+ export const MAX_TEXT_PREVIEW = 100_000;
7
+ export const MAX_PDF_PAGES = 50;
8
+ export const MCP_REQUEST_API = "MCP";
@@ -0,0 +1,25 @@
1
+ import type SendSafelyClient from "@sendsafely/sendsafely";
2
+ import type { ApprovalResult, ApprovalServer, ChoiceOption, ChoiceResult } from "./approval.js";
3
+ export type { ApprovalServer };
4
+ export interface ToolExtra {
5
+ sessionId?: string;
6
+ authInfo?: {
7
+ token?: string;
8
+ extra?: Record<string, unknown>;
9
+ };
10
+ }
11
+ export interface ToolContext {
12
+ getClient(extra: ToolExtra): Promise<SendSafelyClient>;
13
+ getDownloadDir(extra: ToolExtra): string;
14
+ requireUserApproval(message: string): Promise<ApprovalResult>;
15
+ requireUserChoice(message: string, choices: ChoiceOption[]): Promise<ChoiceResult>;
16
+ }
17
+ export declare class CredentialResolutionError extends Error {
18
+ constructor(message: string, name: string);
19
+ }
20
+ export declare class MissingCredentialsError extends CredentialResolutionError {
21
+ constructor(message: string);
22
+ }
23
+ export declare class InvalidTokenError extends CredentialResolutionError {
24
+ constructor(message: string);
25
+ }
@@ -0,0 +1,16 @@
1
+ export class CredentialResolutionError extends Error {
2
+ constructor(message, name) {
3
+ super(message);
4
+ this.name = name;
5
+ }
6
+ }
7
+ export class MissingCredentialsError extends CredentialResolutionError {
8
+ constructor(message) {
9
+ super(message, "MissingCredentialsError");
10
+ }
11
+ }
12
+ export class InvalidTokenError extends CredentialResolutionError {
13
+ constructor(message) {
14
+ super(message, "InvalidTokenError");
15
+ }
16
+ }
@@ -0,0 +1,18 @@
1
+ /// <reference path="./types/sendsafely.d.ts" />
2
+ export * from "./sdk/sdkPromise.js";
3
+ export * from "./sdk/oauthError.js";
4
+ export * from "./constants.js";
5
+ export * from "./instructions.js";
6
+ export * from "./jsonResult.js";
7
+ export * from "./safeHandler.js";
8
+ export * from "./approval.js";
9
+ export * from "./context.js";
10
+ export * from "./sdk/clientFactory.js";
11
+ export * from "./utils/packageChecksum.js";
12
+ export * from "./utils/packageLink.js";
13
+ export * from "./store/packageSecretCache.js";
14
+ export * from "./recipientAddContext.js";
15
+ export * from "./store/keyStore.js";
16
+ export * from "./runTool.js";
17
+ export * from "./utils/sanitizeFilename.js";
18
+ export * from "./tools/index.js";
@@ -0,0 +1,17 @@
1
+ export * from "./sdk/sdkPromise.js";
2
+ export * from "./sdk/oauthError.js";
3
+ export * from "./constants.js";
4
+ export * from "./instructions.js";
5
+ export * from "./jsonResult.js";
6
+ export * from "./safeHandler.js";
7
+ export * from "./approval.js";
8
+ export * from "./context.js";
9
+ export * from "./sdk/clientFactory.js";
10
+ export * from "./utils/packageChecksum.js";
11
+ export * from "./utils/packageLink.js";
12
+ export * from "./store/packageSecretCache.js";
13
+ export * from "./recipientAddContext.js";
14
+ export * from "./store/keyStore.js";
15
+ export * from "./runTool.js";
16
+ export * from "./utils/sanitizeFilename.js";
17
+ export * from "./tools/index.js";
@@ -0,0 +1 @@
1
+ export declare const SERVER_INSTRUCTIONS: string;
@@ -0,0 +1,17 @@
1
+ export const SERVER_INSTRUCTIONS = [
2
+ "SendSafely is an end-to-end encrypted file exchange platform. Use these tools to send/receive encrypted packages, manage recipients, and view recipient activity related to your packages.",
3
+ "Key workflows:",
4
+ "- Send: create_package -> add_recipient(s) -> upload_file(s) and/or add_package_message -> finalize_package. A package is NOT delivered until finalize_package succeeds and returns a secure link.",
5
+ "- Receive: get_received_packages -> download_package_files -> read_downloaded_file. Downloads land in a server-managed directory that may be outside your sandbox or on a different host, so the local_path the download tools return is NOT guaranteed to be openable by your own file-reading tools. To view a downloaded file's contents you MUST go through read_downloaded_file (after asking the user's permission) — it reads the file even when the path is outside your sandbox. Never try to open the path directly or treat a download whose path your file tools can't see as failed. Use list_downloaded_files to enumerate what has been downloaded rather than guessing paths. The same applies to download_file_from_directory for workspace files.",
6
+ "- Workspaces / directories: create_workspace returns a packageId you then manage with create_directory, upload_file, download_file_from_directory, etc.",
7
+ "Always surface the resulting secure link or status to the user.",
8
+ "Recipient authentication options when sending: email verification is the default; choose add_recipient_with_sms for SMS-code verification; finalize_undisclosed_package gates access with a password instead of a named recipient list (do NOT also add named recipients in that case); recipients with a registered Trusted Device can also unlock packages without re-using the original secure link.",
9
+ "Before suggesting actions on an existing package, classify it by reading `packageType` from the package info response. Call get_package_information_from_link when a link is available (this also populates the secret cache for downstream calls), otherwise get_package_information. `packageType` is the single discriminator and has exactly three values:",
10
+ '- packageType === "WORKSPACE" (a virtual data room): supports directories (create_directory, move_directory, rename_directory), per-directory uploads/downloads (download_file_from_directory), and per-package Activity Logs. Does NOT use the flat file flow.',
11
+ '- packageType === "TRANSFER": an ordinary Transfer Package. `files[]` lists top-level files. Use download_package_files and the standard send-flow tools. Does NOT support directories.',
12
+ '- packageType === "DROPZONE": submitted via a Dropzone. Generally the same supported actions as TRANSFER packages.',
13
+ "Orthogonally, if `files[]` is empty and `packageContainsMessage` is true, the package is message-only — suggest get_package_message rather than download tools regardless of packageType.",
14
+ "Recipient download/view history (\"who downloaded what\") lives in different places by packageType. For WORKSPACE packages, call get_activity_log — this returns the package's Activity Log, the same audit stream visible to a Workspace owner in the SendSafely UI. For TRANSFER and DROPZONE packages, read `recipients[].confirmations` from get_package_information (or get_package_information_from_link); SendSafely surfaces this same data to senders as the recipient's \"Recipient History\". Do NOT call get_activity_log for non-workspace packages — it returns nothing useful.",
15
+ "Whenever you inspect a received or sent package, check `packageContainsMessage`. If a secure message exists, TELL the user the package contains one and ask whether they want it decrypted — secure messages are easy to miss and are often the primary payload. Do NOT call get_package_message on your own initiative: decrypting exposes the plaintext message to the AI assistant, so wait for the user to ask for the message before retrieving it.",
16
+ "If a downstream call fails with \"No cached secrets for packageId '...'\" and the user has a registered Trusted Device (private key in the keystore), you do not need the user to paste the keyed link — offer the Trusted Device unlock path instead. Calling get_package_keycode will prompt the user to approve using the Trusted Device for that package; on approval it caches the Keycode so you can retry the original call. Fall back to requesting the keyed link (get_package_information_from_link) if the user declines the unlock or Trusted Device unlock is unavailable or fails.",
17
+ ].join("\n");
@@ -0,0 +1,3 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
2
+ export declare function jsonResult(payload: Record<string, unknown>): CallToolResult;
3
+ export declare function jsonError(message: string, extra?: Record<string, unknown>): CallToolResult;
@@ -0,0 +1,15 @@
1
+ export function jsonResult(payload) {
2
+ return {
3
+ content: [{ type: "text", text: JSON.stringify(payload) }],
4
+ structuredContent: payload,
5
+ isError: false,
6
+ };
7
+ }
8
+ export function jsonError(message, extra) {
9
+ const payload = { status: "error", message, ...extra };
10
+ return {
11
+ content: [{ type: "text", text: JSON.stringify(payload) }],
12
+ structuredContent: payload,
13
+ isError: true,
14
+ };
15
+ }
@@ -0,0 +1,42 @@
1
+ import type { PackageInfo } from "@sendsafely/sendsafely";
2
+ import type { ChoiceOption } from "./approval.js";
3
+ import type { SendSafelyClient } from "./sdk/clientFactory.js";
4
+ import type { ToolContext } from "./context.js";
5
+ export type RecipientAddContext = {
6
+ kind: "block_deleted";
7
+ state: string;
8
+ } | {
9
+ kind: "active_workspace";
10
+ } | {
11
+ kind: "active_transfer_finalized";
12
+ state: string;
13
+ } | {
14
+ kind: "expired";
15
+ state: string;
16
+ } | {
17
+ kind: "unfinalized_or_unknown";
18
+ };
19
+ export declare function classifyRecipientAddContext(info: PackageInfo): RecipientAddContext;
20
+ export declare function tryBuildKeyedLink(client: SendSafelyClient, cachedKeyCode: string, cachedPackageCode: string | undefined): string | null;
21
+ export declare function buildShareLinkMessage(context: RecipientAddContext, recipientDescription: string, secureLink: string): string;
22
+ export declare const COLLABORATOR_ROLE_CHOICES: ChoiceOption[];
23
+ export interface RoleApplyOutcome {
24
+ recipient_id: string;
25
+ email?: string;
26
+ applied_role: string;
27
+ error?: string;
28
+ }
29
+ export interface RolePromptResult {
30
+ prompted: boolean;
31
+ chose_role: string | null;
32
+ prompt_outcome: "selected" | "kept_default" | "declined" | "cancelled" | "unsupported" | "error";
33
+ prompt_error?: string;
34
+ outcomes: RoleApplyOutcome[];
35
+ message: string;
36
+ }
37
+ interface AddedRecipient {
38
+ recipient_id: string;
39
+ email?: string | undefined;
40
+ }
41
+ export declare function promptAndApplyWorkspaceRole(ctx: ToolContext, client: SendSafelyClient, packageId: string, added: AddedRecipient[], recipientDescription: string): Promise<RolePromptResult>;
42
+ export {};
@@ -0,0 +1,182 @@
1
+ import { buildKeyedLink } from "./utils/packageLink.js";
2
+ import { updateRecipientRole as sdkUpdateRecipientRole } from "./sdk/sdkPromise.js";
3
+ function startsWith(state, prefix) {
4
+ return typeof state === "string" && state.startsWith(prefix);
5
+ }
6
+ function isWorkspace(info) {
7
+ if (info.packageType === "WORKSPACE")
8
+ return true;
9
+ if (info.isVDR === true)
10
+ return true;
11
+ return false;
12
+ }
13
+ export function classifyRecipientAddContext(info) {
14
+ const state = info.state;
15
+ if (startsWith(state, "PACKAGE_STATE_DELETED_")) {
16
+ return { kind: "block_deleted", state: state ?? "" };
17
+ }
18
+ if (isWorkspace(info)) {
19
+ return { kind: "active_workspace" };
20
+ }
21
+ if (startsWith(state, "PACKAGE_STATE_EXPIRED_")) {
22
+ return { kind: "expired", state: state ?? "" };
23
+ }
24
+ if (startsWith(state, "PACKAGE_STATE_ACTIVE_")) {
25
+ return { kind: "active_transfer_finalized", state: state ?? "" };
26
+ }
27
+ return { kind: "unfinalized_or_unknown" };
28
+ }
29
+ export function tryBuildKeyedLink(client, cachedKeyCode, cachedPackageCode) {
30
+ if (!cachedPackageCode)
31
+ return null;
32
+ return buildKeyedLink(client, cachedPackageCode, cachedKeyCode);
33
+ }
34
+ export function buildShareLinkMessage(context, recipientDescription, secureLink) {
35
+ if (context.kind === "active_workspace") {
36
+ return (`${recipientDescription} added as a collaborator. SendSafely does ` +
37
+ "NOT send automatic notifications for workspace collaborators — " +
38
+ "surface the secure_link below to the user and tell them they MUST " +
39
+ "share it with the new collaborator(s) so they can access the " +
40
+ `workspace.\nsecure_link: ${secureLink}`);
41
+ }
42
+ if (context.kind === "active_transfer_finalized") {
43
+ return (`${recipientDescription} added to an already-finalized package ` +
44
+ `(state ${context.state}). SendSafely does NOT auto-notify ` +
45
+ "recipients added after finalize — surface the secure_link below " +
46
+ "and tell the user they MUST share it with the new recipient(s) so " +
47
+ `they can access the package.\nsecure_link: ${secureLink}`);
48
+ }
49
+ if (context.kind === "expired") {
50
+ return (`${recipientDescription} added, but the package is currently ` +
51
+ `EXPIRED (state ${context.state}). The recipient(s) cannot access ` +
52
+ "the package until the user un-expires it (call update_package " +
53
+ "with a positive `expiration_days`, or 0 to set never-expires). " +
54
+ "After un-expiring, SendSafely will NOT " +
55
+ "auto-notify these recipient(s), so the user will also need to " +
56
+ "share secure_link below with them.\n" +
57
+ `secure_link: ${secureLink}`);
58
+ }
59
+ return `${recipientDescription} added.`;
60
+ }
61
+ export const COLLABORATOR_ROLE_CHOICES = [
62
+ { value: "VIEWER", label: "Viewer (keep default — read access only)" },
63
+ {
64
+ value: "CONTRIBUTOR",
65
+ label: "Contributor (upload + manage files)",
66
+ },
67
+ {
68
+ value: "MANAGER",
69
+ label: "Manager (full workspace control, including collaborators)",
70
+ },
71
+ ];
72
+ export async function promptAndApplyWorkspaceRole(ctx, client, packageId, added, recipientDescription) {
73
+ if (added.length === 0) {
74
+ return {
75
+ prompted: false,
76
+ chose_role: null,
77
+ prompt_outcome: "kept_default",
78
+ outcomes: [],
79
+ message: "",
80
+ };
81
+ }
82
+ const prompt = await ctx.requireUserChoice(`${recipientDescription} added to the workspace as VIEWER (the default ` +
83
+ "role — read access only). Would you like to keep them as Viewer, " +
84
+ "upgrade to Contributor (upload + manage files), or Manager (full " +
85
+ "workspace control)?", COLLABORATOR_ROLE_CHOICES);
86
+ if (prompt.outcome === "unsupported") {
87
+ return {
88
+ prompted: false,
89
+ chose_role: null,
90
+ prompt_outcome: "unsupported",
91
+ outcomes: added.map((a) => ({
92
+ recipient_id: a.recipient_id,
93
+ ...(a.email ? { email: a.email } : {}),
94
+ applied_role: "VIEWER",
95
+ })),
96
+ message: "Role-change prompt is unsupported by this MCP client; collaborators " +
97
+ "remain at the default VIEWER role. The user can call " +
98
+ "update_recipient_role later to upgrade them to CONTRIBUTOR or " +
99
+ "MANAGER.",
100
+ };
101
+ }
102
+ if (prompt.outcome === "declined" || prompt.outcome === "cancelled") {
103
+ return {
104
+ prompted: true,
105
+ chose_role: null,
106
+ prompt_outcome: prompt.outcome,
107
+ outcomes: added.map((a) => ({
108
+ recipient_id: a.recipient_id,
109
+ ...(a.email ? { email: a.email } : {}),
110
+ applied_role: "VIEWER",
111
+ })),
112
+ message: `User ${prompt.outcome} the role-change prompt; collaborators remain ` +
113
+ "at the default VIEWER role. They can be upgraded later via " +
114
+ "update_recipient_role.",
115
+ };
116
+ }
117
+ if (prompt.outcome === "error") {
118
+ return {
119
+ prompted: true,
120
+ chose_role: null,
121
+ prompt_outcome: "error",
122
+ prompt_error: prompt.message,
123
+ outcomes: added.map((a) => ({
124
+ recipient_id: a.recipient_id,
125
+ ...(a.email ? { email: a.email } : {}),
126
+ applied_role: "VIEWER",
127
+ })),
128
+ message: "Role-change prompt failed; collaborators remain at the default " +
129
+ "VIEWER role. The user can call update_recipient_role to change " +
130
+ "this later.",
131
+ };
132
+ }
133
+ const chosen = prompt.value;
134
+ if (chosen === "VIEWER") {
135
+ return {
136
+ prompted: true,
137
+ chose_role: "VIEWER",
138
+ prompt_outcome: "kept_default",
139
+ outcomes: added.map((a) => ({
140
+ recipient_id: a.recipient_id,
141
+ ...(a.email ? { email: a.email } : {}),
142
+ applied_role: "VIEWER",
143
+ })),
144
+ message: "User kept collaborators at the default VIEWER role. No role " +
145
+ "change applied.",
146
+ };
147
+ }
148
+ const outcomes = [];
149
+ let anyFailure = false;
150
+ for (const rec of added) {
151
+ try {
152
+ await sdkUpdateRecipientRole(client, packageId, rec.recipient_id, chosen);
153
+ outcomes.push({
154
+ recipient_id: rec.recipient_id,
155
+ ...(rec.email ? { email: rec.email } : {}),
156
+ applied_role: chosen,
157
+ });
158
+ }
159
+ catch (err) {
160
+ anyFailure = true;
161
+ const msg = err instanceof Error ? err.message : String(err);
162
+ outcomes.push({
163
+ recipient_id: rec.recipient_id,
164
+ ...(rec.email ? { email: rec.email } : {}),
165
+ applied_role: "VIEWER",
166
+ error: msg,
167
+ });
168
+ }
169
+ }
170
+ const message = anyFailure
171
+ ? `Selected role ${chosen} applied to some collaborators; one or more ` +
172
+ "role updates failed and those collaborators remain at VIEWER " +
173
+ "(see outcomes[].error). The user can retry via update_recipient_role."
174
+ : `Selected role ${chosen} applied to all added collaborator(s).`;
175
+ return {
176
+ prompted: true,
177
+ chose_role: chosen,
178
+ prompt_outcome: "selected",
179
+ outcomes,
180
+ message,
181
+ };
182
+ }
@@ -0,0 +1,2 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
2
+ export declare function runTool(toolName: string, failurePrefix: string, fn: () => Promise<CallToolResult>): Promise<CallToolResult>;
@@ -0,0 +1,22 @@
1
+ import { CredentialResolutionError } from "./context.js";
2
+ import { jsonError } from "./jsonResult.js";
3
+ import { oauthFailureKind } from "./sdk/oauthError.js";
4
+ import { MissingPackageSecretsError } from "./store/packageSecretCache.js";
5
+ export async function runTool(toolName, failurePrefix, fn) {
6
+ try {
7
+ return await fn();
8
+ }
9
+ catch (err) {
10
+ if (oauthFailureKind(err) !== undefined)
11
+ throw err;
12
+ if (err instanceof CredentialResolutionError) {
13
+ process.stderr.write(`[CREDS] ${toolName}: ${err.name}: ${err.message}\n`);
14
+ return jsonError("SendSafely credentials not available. See server logs for details.");
15
+ }
16
+ if (err instanceof MissingPackageSecretsError) {
17
+ return jsonError(err.message);
18
+ }
19
+ const msg = err instanceof Error ? err.message : String(err);
20
+ return jsonError(`${failurePrefix}: ${msg}`);
21
+ }
22
+ }
@@ -0,0 +1,17 @@
1
+ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
2
+ type HasSessionId = {
3
+ sessionId?: string;
4
+ authInfo?: {
5
+ extra?: Record<string, unknown>;
6
+ };
7
+ };
8
+ export interface ToolErrorLogEntry {
9
+ toolName: string;
10
+ sessionId?: string;
11
+ correlationId?: string;
12
+ message: string;
13
+ }
14
+ export type ToolErrorLogger = (entry: ToolErrorLogEntry) => void;
15
+ export declare function setToolErrorLogger(logger: ToolErrorLogger): void;
16
+ export declare function safeHandler<A, E extends HasSessionId>(toolName: string, fn: (args: A, extra: E) => Promise<CallToolResult>): (args: A, extra: E) => Promise<CallToolResult>;
17
+ export {};
@@ -0,0 +1,32 @@
1
+ import { jsonError } from "./jsonResult.js";
2
+ import { oauthFailureKind, recordOAuthFailure } from "./sdk/oauthError.js";
3
+ let toolErrorLogger = (entry) => {
4
+ process.stderr.write(`[ERROR] tool=${entry.toolName} session=${entry.sessionId ?? "stdio"}: ${entry.message}\n`);
5
+ };
6
+ export function setToolErrorLogger(logger) {
7
+ toolErrorLogger = logger;
8
+ }
9
+ export function safeHandler(toolName, fn) {
10
+ return async (args, extra) => {
11
+ try {
12
+ return await fn(args, extra);
13
+ }
14
+ catch (err) {
15
+ const msg = err instanceof Error ? err.message : String(err);
16
+ const correlationId = extra.authInfo?.extra?.["correlationId"];
17
+ const oauthKind = oauthFailureKind(err);
18
+ if (oauthKind !== undefined) {
19
+ recordOAuthFailure(extra.authInfo?.extra, oauthKind);
20
+ }
21
+ toolErrorLogger({
22
+ toolName,
23
+ ...(extra.sessionId !== undefined && { sessionId: extra.sessionId }),
24
+ ...(typeof correlationId === "string" && { correlationId }),
25
+ message: msg,
26
+ });
27
+ if (oauthKind !== undefined)
28
+ return jsonError(msg);
29
+ return jsonError(`Internal error in ${toolName}. See server logs.`);
30
+ }
31
+ };
32
+ }
@@ -0,0 +1,17 @@
1
+ import SendSafelyClient from "@sendsafely/sendsafely";
2
+ export interface SendSafelyCreds {
3
+ url: string;
4
+ apiKey: string;
5
+ apiSecret: string;
6
+ }
7
+ export interface SendSafelyBearerCreds {
8
+ url: string;
9
+ accessToken: string;
10
+ }
11
+ export type SendSafelyClientCreds = SendSafelyCreds | SendSafelyBearerCreds;
12
+ export declare function sdkSupportsBearerAuth(): boolean;
13
+ export declare function isAllowedPortalUrl(url: string): boolean;
14
+ export declare const INSECURE_URL_MESSAGE: string;
15
+ export declare function createSendSafelyClient(creds: SendSafelyClientCreds): SendSafelyClient;
16
+ export declare function setMcpClientVersion(version: string): void;
17
+ export type { default as SendSafelyClient } from "@sendsafely/sendsafely";
@@ -0,0 +1,29 @@
1
+ import SendSafelyClient from "@sendsafely/sendsafely";
2
+ import { MCP_REQUEST_API } from "../constants.js";
3
+ export function sdkSupportsBearerAuth() {
4
+ return typeof SendSafelyClient.withBearerToken === "function";
5
+ }
6
+ const LOOPBACK_URL = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/i;
7
+ export function isAllowedPortalUrl(url) {
8
+ return /^https:\/\//i.test(url) || LOOPBACK_URL.test(url);
9
+ }
10
+ export const INSECURE_URL_MESSAGE = "SENDSAFELY_URL must use https:// (plain http is only allowed for " +
11
+ "localhost). Credentials must not be sent in cleartext.";
12
+ export function createSendSafelyClient(creds) {
13
+ if (!isAllowedPortalUrl(creds.url)) {
14
+ throw new Error(INSECURE_URL_MESSAGE);
15
+ }
16
+ if ("accessToken" in creds) {
17
+ if (!sdkSupportsBearerAuth()) {
18
+ throw new Error("OAuth bearer authentication requires an @sendsafely/sendsafely " +
19
+ "build with withBearerToken support (4.0.1+); the installed " +
20
+ "version does not have it. Use API-key authentication, or " +
21
+ "upgrade the SDK dependency.");
22
+ }
23
+ return SendSafelyClient.withBearerToken(creds.url, creds.accessToken, MCP_REQUEST_API);
24
+ }
25
+ return new SendSafelyClient(creds.url, creds.apiKey, creds.apiSecret, MCP_REQUEST_API);
26
+ }
27
+ export function setMcpClientVersion(version) {
28
+ SendSafelyClient.setClientVersion(`SendSafely MCP/${version}`);
29
+ }
@@ -0,0 +1,9 @@
1
+ export type OAuthFailureKind = "invalid_token" | "insufficient_scope" | "temporarily_unavailable";
2
+ export declare class SendSafelyApiError extends Error {
3
+ readonly code: string;
4
+ constructor(message: string, code: string);
5
+ }
6
+ export declare function oauthFailureKind(err: unknown): OAuthFailureKind | undefined;
7
+ export declare const OAUTH_FAILURE_KEY = "oauthFailure";
8
+ export declare function recordOAuthFailure(bag: Record<string, unknown> | undefined, kind: OAuthFailureKind): void;
9
+ export declare function readOAuthFailure(bag: Record<string, unknown> | undefined): OAuthFailureKind | undefined;