@safekb/mcp 0.14.1 → 0.15.0

package/README.md

@@ -333,7 +333,7 @@ and `import_seal_keys`, and for backups `export_backup` and
 What you type at the terminal for the command line, you type at the [sidecar](#the-sidecar) for a
 tool, while the call waits: the passphrase of an export file or a key export (twice for a new one),
 and the name or id that confirms `delete_seal_key`. It reaches this client only, never the conversation. Without a running sidecar such a tool fails and says
-to start one (`safekb-mcp --sidecar`); on Windows, which has no sidecar, it names the command to run
+to start one (`npx -y @safekb/mcp --sidecar`); on Windows, which has no sidecar, it names the command to run
 instead. File paths given to the tools must be absolute.
 
 ### Moving keys to another machine
@@ -375,11 +375,12 @@ custom fields and the key name of every custom field (sealed ones too) stay read
   field (`llm_field_visibility`, e.g. a card's number and CVC hidden, its expiry date visible).
   `reveal_sealed_credential` and `get_sealed_totp` work only on a `visible` field. New and migrated
   sealed credentials start with the tenant default (Settings → Sealed credentials; `use_only` until
-  set). Only you make anything more visible, in the SafeKB app; `set_sealed_credential_llm_visibility`
+  set). `insert_sealed_credential` requires `llm_visibility` (`use_only` or `visible`), which the agent
+  asks you for; an agent's `visible` is refused unless it is the tenant default. Only you make anything more visible, in the SafeKB app; `set_sealed_credential_llm_visibility`
   only tightens. The client enforces this: a client older than 0.11.0 reveals every sealed credential, and 0.11.0 ignores field overrides.
 - Entering a secret without the agent seeing it: `insert_sealed_credential` and
   `update_sealed_credential` take `typed_at_sidecar`, e.g. `["custom:number", "custom:cvc", "password"]`.
-  The call waits while you type each field at the sidecar (`safekb-mcp --sidecar`), hidden and twice;
+  The call waits while you type each field at the sidecar (`npx -y @safekb/mcp --sidecar`), hidden and twice;
   the agent passes only the visible fields. Or enter it in the SafeKB web app.
 - Using a secret without showing it: SafeKB only provides the value. `secret_exec` runs your own
   program with it in env, stdin or a temp file (`files`, mode 0600, deleted afterwards), never argv;
@@ -441,7 +442,7 @@ What an export holds:
 - Credentials with every secret field. Each secret of a server-encrypted credential is one audited
   reveal on the server.
 - Sealed folders, documents, attachments and credentials of every seal root that opens with a secret
-  this machine keeps or its sidecar holds (`safekb-mcp --sidecar`, then `add <name or id>` for a
+  this machine keeps or its sidecar holds (`npx -y @safekb/mcp --sidecar`, then `add <name or id>` for a
   passphrase root), decrypted on this machine.
 - Every other seal root as the server stores it, still sealed: the machine that makes the backup needs
   none of their keys. The export names these roots before it writes. Pending deposits in them are left

package/dist/safekb-mcp.js

@@ -2578,51 +2578,6 @@ var require_punycode = __commonJS((exports, module) => {
 // src/main.ts
 import { existsSync as existsSync5 } from "node:fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-// package.json
-var package_default = {
-  name: "@safekb/mcp",
-  version: "0.14.1",
-  description: "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
-  license: "SEE LICENSE IN LICENSE",
-  author: "Mustafa Öztürk",
-  type: "module",
-  bin: {
-    "safekb-mcp": "dist/safekb-mcp.js"
-  },
-  files: [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "THIRD-PARTY-NOTICES.md"
-  ],
-  engines: {
-    node: ">=20"
-  },
-  publishConfig: {
-    access: "public"
-  },
-  scripts: {
-    build: "bun build ./src/cli.ts --target=node --outfile=dist/safekb-mcp.js --external '@modelcontextprotocol/sdk/*' --external '@napi-rs/keyring'",
-    "build:mcpb": "bun scripts/build-mcpb.ts",
-    prepack: "bun run build",
-    test: "bun test",
-    typecheck: "tsc --noEmit",
-    lint: "biome check ."
-  },
-  dependencies: {
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@napi-rs/keyring": "2.1.0"
-  },
-  devDependencies: {
-    "@biomejs/biome": "2.4.6",
-    "@safekb/canvas-markdown": "workspace:*",
-    "@safekb/sealed-crypto": "workspace:*",
-    "@types/bun": "1.3.14",
-    "@types/node": "20.19.43",
-    typescript: "5.9.3",
-    zod: "4.3.6"
-  }
-};
 
 // src/errors.ts
 class ClientError extends Error {
@@ -6623,12 +6578,63 @@ async function writePrivateFile(path, content) {
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join as join2 } from "node:path";
+// package.json
+var package_default = {
+  name: "@safekb/mcp",
+  version: "0.15.0",
+  description: "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
+  license: "SEE LICENSE IN LICENSE",
+  author: "Mustafa Öztürk",
+  type: "module",
+  bin: {
+    "safekb-mcp": "dist/safekb-mcp.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "bun build ./src/cli.ts --target=node --outfile=dist/safekb-mcp.js --external '@modelcontextprotocol/sdk/*' --external '@napi-rs/keyring'",
+    "build:mcpb": "bun scripts/build-mcpb.ts",
+    prepack: "bun run build",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    lint: "biome check ."
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@napi-rs/keyring": "2.1.0"
+  },
+  devDependencies: {
+    "@biomejs/biome": "2.4.6",
+    "@safekb/canvas-markdown": "workspace:*",
+    "@safekb/sealed-crypto": "workspace:*",
+    "@types/bun": "1.3.14",
+    "@types/node": "20.19.43",
+    typescript: "5.9.3",
+    zod: "4.3.6"
+  }
+};
+
+// src/commandLine.ts
+var VERSION = package_default.version;
+var CLI = `npx -y @safekb/mcp@${VERSION}`;
+
+// src/tokenConfig.ts
 function defaultTokenConfigPath() {
   return join2(homedir(), ".config", "safekb", "mcp.json");
 }
 function requireString(value, field, path) {
   if (typeof value !== "string" || value.length === 0) {
-    throw new StartupError(`Token file ${path} has no '${field}'; run: safekb-mcp --authorize`);
+    throw new StartupError(`Token file ${path} has no '${field}'; run: ${CLI} --authorize`);
   }
   return value;
 }
@@ -6650,7 +6656,7 @@ function assertTokenConfig(value, source) {
 }
 async function loadTokenConfig(path) {
   if (!existsSync(path)) {
-    throw new StartupError(`No token file at ${path}; run: safekb-mcp --authorize`);
+    throw new StartupError(`No token file at ${path}; run: ${CLI} --authorize`);
   }
   let text;
   try {
@@ -8854,7 +8860,7 @@ ${countLines(report.created)}`);
     this.writeNotes("Seal roots the export holds as stored that had no key here, so everything in them was left out (to restore them, import again with --keys <their key export>; that creates everything else again too)", report.unopenedRoots.map(({ id, name, reason }) => `${name === null ? id : `"${name}" (${id})`}: ${reason}`));
     if (report.sealRoots.length === 0)
       return;
-    this.reader.write(`New seal roots, each with a newly generated key. Back the keys up (safekb-mcp --export-keys): a lost key cannot be recovered.
+    this.reader.write(`New seal roots, each with a newly generated key. Back the keys up (${CLI} --export-keys): a lost key cannot be recovered.
 `);
     for (const root of report.sealRoots) {
       this.reader.write(`  "${printable2(root.name)}" (${root.id}), key in ${root.kept}
@@ -10079,6 +10085,7 @@ class CredentialService {
       visible: save.visible,
       enc_fields: save.encFields,
       enc_dek: encDek,
+      llm_visibility: args.llm_visibility,
       sigs,
       ...args.display
     }));
@@ -11690,8 +11697,8 @@ class RawSealedExporter {
 
 // src/stores/secretStores.ts
 var HOW_TO_ENABLE = {
-  system: "The system keyring is not set up for this client; run: safekb-mcp --configure",
-  file: "No key file directory is set up; start the client with --keyring <dir>, or run: safekb-mcp --configure",
+  system: `The system keyring is not set up for this client; run: ${CLI} --configure`,
+  file: `No key file directory is set up; start the client with --keyring <dir>, or run: ${CLI} --configure`,
   sidecar: "The sidecar is not available on this platform"
 };
 
@@ -11722,7 +11729,7 @@ class SecretStores {
   }
   async findIn(stores, seal2) {
     if (stores.length === 0) {
-      throw new SecretLookupError("no-store", "No secret given and no secret store is set up", ": run safekb-mcp --configure or start the client with --keyring <dir>, or give a file holding the secret with provide_seal_secret (secret_file)");
+      throw new SecretLookupError("no-store", "No secret given and no secret store is set up", `: run ${CLI} --configure or start the client with --keyring <dir>, or give a file holding the secret with provide_seal_secret (secret_file)`);
     }
     const found = [];
     const notes = [];
@@ -11735,7 +11742,7 @@ class SecretStores {
     }
     const [first, ...others] = found;
     if (first === undefined) {
-      throw new SecretLookupError("not-found", `No secret for seal root ${seal2.rootId} was found: ${[...new Set(notes)].join("; ")}`, `. To open it, the user types its secret at the sidecar (safekb-mcp --sidecar, then: add ${seal2.rootId}) and the call is repeated, or a file holding it is given with provide_seal_secret (secret_file)`);
+      throw new SecretLookupError("not-found", `No secret for seal root ${seal2.rootId} was found: ${[...new Set(notes)].join("; ")}`, `. To open it, the user types its secret at the sidecar (${CLI} --sidecar, then: add ${seal2.rootId}) and the call is repeated, or a file holding it is given with provide_seal_secret (secret_file)`);
     }
     if (others.length > 0) {
       throw new SecretLookupError("ambiguous", `Seal root ${seal2.rootId} has a secret in more than one store (${found.map(({ store }) => store).join(", ")})`, "; name the one to use with provide_seal_secret (store)");
@@ -11747,7 +11754,7 @@ class SecretStores {
       return this.require(name);
     const { defaultKeyStore } = this.set;
     if (defaultKeyStore === null) {
-      throw new SecretLookupError("no-default", "No default store is set up for new keys", "; run: safekb-mcp --configure. Or pass store (system, file, sidecar), key_out_path or passphrase.");
+      throw new SecretLookupError("no-default", "No default store is set up for new keys", `; run: ${CLI} --configure. Or pass store (system, file, sidecar), key_out_path or passphrase.`);
     }
     return this.require(defaultKeyStore);
   }
@@ -25907,7 +25914,7 @@ var EXPOSURE_NOTE = "Everything this tool returns enters the conversation transc
 var PLAINTEXT_ARGUMENTS_NOTE = "The text you pass as arguments is plaintext: it is kept in the conversation transcript on this machine and has already been sent to the model provider. Sealing protects it on the server only.";
 var objectId2 = (what) => exports_external.string().regex(/^[0-9a-f]{24}$/, "must be a 24-character id").describe(what);
 var rootRef = (what) => exports_external.string().min(1).describe(`${what} Its id, or the name this machine knows it by (a name is accepted directly: no lookup needed).`);
-var SIDECAR_TYPING = "The user types it at the running sidecar (safekb-mcp --sidecar) while the call waits: tell them to look there. It never enters the conversation.";
+var SIDECAR_TYPING = `The user types it at the running sidecar (${CLI} --sidecar) while the call waits: tell them to look there. It never enters the conversation.`;
 var absolutePath = (what) => exports_external.string().min(1).refine(isAbsolute, "must be an absolute path").describe(what);
 var expectedSeq = exports_external.number().int().min(0).describe("The seal_seq you last read for this node (from list_sealed, read_sealed_document or the result of your last write). The write fails if it changed since; never guess it.");
 function shownError(error48) {
@@ -33407,7 +33414,7 @@ class HostedProxy {
       const session = await HostedProxy.open(endpoint, settings);
       return new HostedProxy(endpoint, settings, session);
     } catch (error48) {
-      throw new StartupError(`Cannot reach the hosted SafeKB MCP endpoint ${endpoint.href}: ${error48.message}. ` + "Check the URL and the token (safekb-mcp --authorize), or start with --sealed-only.");
+      throw new StartupError(`Cannot reach the hosted SafeKB MCP endpoint ${endpoint.href}: ${error48.message}. ` + `Check the URL and the token (${CLI} --authorize), or start with --sealed-only.`);
     }
   }
   instructions() {
@@ -33670,10 +33677,10 @@ var TOOL_VOCABULARY = {
   listKeys: "list_seal_keys",
   store: "store",
   howToGoOn: {
-    "no-store": ": run safekb-mcp --configure, or start the client with --keyring <dir> for a directory of key files",
+    "no-store": `: run ${CLI} --configure, or start the client with --keyring <dir> for a directory of key files`,
     "not-found": ". The key tools work with a key kept in the system keyring or in the key file directory (see list_seal_keys); a root opened by a passphrase is changed with change_seal_password.",
     ambiguous: "; run move_seal_key with store system or file to leave one copy",
-    "no-default": "; run safekb-mcp --configure, or pass store system|file"
+    "no-default": `; run ${CLI} --configure, or pass store system|file`
   }
 };
 
@@ -33855,10 +33862,10 @@ var COMMAND_LINE_VOCABULARY = {
   listKeys: "--list-keys",
   store: "--store",
   howToGoOn: {
-    "no-store": ": run safekb-mcp --configure, or pass --keyring <dir> for a directory of key files",
+    "no-store": `: run ${CLI} --configure, or pass --keyring <dir> for a directory of key files`,
     "not-found": ". The key modes work with a key kept in the system keyring or in the key file directory (see --list-keys); a root opened by a passphrase is changed with the MCP tools.",
     ambiguous: "; run --move-key with --store system or --store file to leave one copy",
-    "no-default": "; run safekb-mcp --configure, or pass --store system|file"
+    "no-default": `; run ${CLI} --configure, or pass --store system|file`
   }
 };
 function lines(...text2) {
@@ -34565,7 +34572,7 @@ function send(socketPath, request, timeoutMs) {
       resolve(received);
     });
     socket.once("error", (error48) => {
-      reject(NOT_RUNNING_CODES.has(error48.code ?? "") ? new SidecarNotRunningError(`No sidecar is running at ${socketPath}; start one in a terminal with: safekb-mcp --sidecar`) : error48);
+      reject(NOT_RUNNING_CODES.has(error48.code ?? "") ? new SidecarNotRunningError(`No sidecar is running at ${socketPath}; start one in a terminal with: ${CLI} --sidecar`) : error48);
     });
   });
 }
@@ -35309,7 +35316,7 @@ function assertStoreConfig(value, path2) {
   const systemKeyring = raw?.system_keyring;
   const keyDir = raw?.key_dir ?? null;
   if (typeof raw !== "object" || raw === null || !KEY_STORE_NAMES.includes(store) || typeof systemKeyring !== "boolean" || !(keyDir === null || typeof keyDir === "string" && keyDir.length > 0) || store === "file" && keyDir === null || store === "system" && !systemKeyring) {
-    throw new StartupError(`Store settings ${path2} are malformed; run: safekb-mcp --configure`);
+    throw new StartupError(`Store settings ${path2} are malformed; run: ${CLI} --configure`);
   }
   return {
     default_store: store,
@@ -35781,7 +35788,7 @@ function reportOf(report) {
   };
 }
 function commandLine(mode2, path2, flags) {
-  const words2 = [`safekb-mcp --${mode2} ${path2}`];
+  const words2 = [`${CLI} --${mode2} ${path2}`];
   for (const [flag, value] of flags) {
     if (value === undefined || value === false)
       continue;
@@ -35824,11 +35831,11 @@ function backupTools(parts) {
         note: "The file opens only with the passphrase the user typed: they should keep both, apart."
       };
     }),
-    defineTool("import_backup", "Restore from a file written by export_backup (or safekb-mcp --export): create what it holds in this token's account, as new things with new ids; nothing that exists is changed. There is no dry run. " + "Each exported space becomes a new space, each seal root a new seal root with a newly generated key. A seal root the file holds as stored is opened with a key from key_exports or one this machine keeps; without one, everything in it is left out and named in the result. " + `The passphrase of the file, and of each key export, is asked of the user: ${SIDECAR_TYPING} ${LONG_RUN}`, {
+    defineTool("import_backup", `Restore from a file written by export_backup (or ${CLI} --export): create what it holds in this token's account, as new things with new ids; nothing that exists is changed. There is no dry run. ` + "Each exported space becomes a new space, each seal root a new seal root with a newly generated key. A seal root the file holds as stored is opened with a key from key_exports or one this machine keeps; without one, everything in it is left out and named in the result. " + `The passphrase of the file, and of each key export, is asked of the user: ${SIDECAR_TYPING} ${LONG_RUN}`, {
       path: absolutePath("The export file."),
       into_space_id: exports_external.string().min(1).describe("Put everything into this one existing space instead of creating the exported spaces again.").optional(),
       store: exports_external.enum([...KEY_STORE_NAMES, "default"]).default("default").describe("Where the keys of the new seal roots are kept: system (the operating system's keyring), file (the key file directory), or the default store."),
-      key_exports: exports_external.array(absolutePath("A key export file.")).min(1).describe("Key exports (export_seal_keys, safekb-mcp --export-keys) whose keys open the seal roots the file holds as stored. Used for this import only; not kept.").optional()
+      key_exports: exports_external.array(absolutePath("A key export file.")).min(1).describe(`Key exports (export_seal_keys, ${CLI} --export-keys) whose keys open the seal roots the file holds as stored. Used for this import only; not kept.`).optional()
     }, async (args, progress) => {
       const keyExports = args.key_exports ?? [];
       const files = new BackupFiles(questions(commandLine("import", args.path, [
@@ -35860,7 +35867,7 @@ Imported before it stopped: ${JSON.stringify(reportOf(error48.report))}`);
 // src/tools/rootTools.ts
 var KEY_OUT_PATH = "Path for a new key file (created with mode 0600; must not exist). A key is generated and written there; it is never returned.";
 var PASSPHRASE_WARNING = "A passphrase passed here enters the conversation transcript and reaches the model provider; prefer store or key_out_path.";
-var NEW_SECRET_STORE = "Where this machine keeps the new secret, which is never returned. " + "default: the store chosen by safekb-mcp --configure. " + "system: a generated key in the operating system's keyring. " + "file: a generated key as a file (mode 0600) in the keyring directory. " + "sidecar: a passphrase the user types at the running sidecar (safekb-mcp --sidecar), held in its memory for a limited time; the call waits for them to type it.";
+var NEW_SECRET_STORE = "Where this machine keeps the new secret, which is never returned. " + `default: the store chosen by ${CLI} --configure. ` + "system: a generated key in the operating system's keyring. " + "file: a generated key as a file (mode 0600) in the keyring directory. " + `sidecar: a passphrase the user types at the running sidecar (${CLI} --sidecar), held in its memory for a limited time; the call waits for them to type it.`;
 var newSecretStore = exports_external.enum(NEW_SECRET_STORES).describe(NEW_SECRET_STORE).optional();
 function rootTools(roots, names) {
   const resolved = async (reference2) => reference2 === undefined ? undefined : names.resolve(reference2);
@@ -35967,7 +35974,7 @@ function keyTools(parts) {
       };
     })),
     defineTool("delete_seal_key", "Remove every key of a seal root from this machine's key stores and forget its name. The root and its content on the server are not touched (to delete the root itself, use delete_sealed_document). " + "The user is shown the keys and what removing them costs, and must type the root's name or id at the sidecar to go ahead; nothing is removed otherwise. " + `${SIDECAR_TYPING} A key that exists nowhere else is lost for good: content it alone opens can never be read again.`, { root_id: rootRef("The seal root.") }, (args) => managers.run(async (manager) => {
-      const deleted = await manager.delete(args.root_id, questions(`safekb-mcp --delete-key ${args.root_id}`));
+      const deleted = await manager.delete(args.root_id, questions(`${CLI} --delete-key ${args.root_id}`));
       return {
         root_id: deleted.rootId,
         removed_from: deleted.removed,
@@ -35976,7 +35983,7 @@ function keyTools(parts) {
       };
     })),
     defineTool("export_seal_keys", "Write every generated key this machine keeps to a new file, encrypted under a passphrase the user chooses: for moving the keys to another machine or keeping them safe. It holds no documents (for those: export_backup). " + `${SIDECAR_TYPING} Returns the seal roots whose keys are in the file, never a key. A seal root opened by a passphrase has no key here and is not in the file.`, { path: absolutePath("The new file; must not exist.") }, async (args) => {
-      const keys = await transfer.exportWith(args.path, questions(`safekb-mcp --export-keys ${args.path}`));
+      const keys = await transfer.exportWith(args.path, questions(`${CLI} --export-keys ${args.path}`));
       return {
         path: args.path,
         keys: keys.length,
@@ -35984,8 +35991,8 @@ function keyTools(parts) {
         note: "The file opens only with the passphrase the user typed: they should keep both, apart."
       };
     }),
-    defineTool("import_seal_keys", "Keep the keys of a file written by export_seal_keys (or safekb-mcp --export-keys) on this machine, in the default key store, so the sealed tools open the roots they belong to here. A key this machine already keeps is left as it is. To restore documents from a backup, use import_backup. " + `The file's passphrase is asked of the user: ${SIDECAR_TYPING}`, { path: absolutePath("The key export file.") }, async (args) => {
-      const { imported, store, present } = await transfer.importWith(args.path, questions(`safekb-mcp --import-keys ${args.path}`));
+    defineTool("import_seal_keys", `Keep the keys of a file written by export_seal_keys (or ${CLI} --export-keys) on this machine, in the default key store, so the sealed tools open the roots they belong to here. A key this machine already keeps is left as it is. To restore documents from a backup, use import_backup. ` + `The file's passphrase is asked of the user: ${SIDECAR_TYPING}`, { path: absolutePath("The key export file.") }, async (args) => {
+      const { imported, store, present } = await transfer.importWith(args.path, questions(`${CLI} --import-keys ${args.path}`));
       return {
         imported: await rootsOf(imported, names),
         kept_in: store === null ? null : KEY_STORE_LABELS[store],
@@ -36169,6 +36176,7 @@ var credentialId = objectId2("Id of the sealed credential.");
 var expectedVersion = exports_external.number().int().min(1).describe("The version you last read for this credential. The write fails if it changed since.");
 var CLEARABLE = "An empty string clears the field.";
 var SECRET_ARGUMENT_NOTE = "Secret values passed here are part of the conversation transcript and reach the model provider; the server never sees them.";
+var TYPED_NOTE = "For a secret you must not see (one the user has not given you, e.g. a card number, PIN or bank password), pass typed_at_sidecar with the field names instead of the value: the user types it at the sidecar while the call waits. Then use it with secret_exec, never by revealing it.";
 var visibleFields = {
   username: exports_external.string().describe(`Visible to the server. ${CLEARABLE}`).optional(),
   url: exports_external.string().describe(`Visible to the server. ${CLEARABLE}`).optional(),
@@ -36189,7 +36197,7 @@ var sealedFields = {
 function credentialTools(credentials, migration, names, entry) {
   const atSidecar = (fields2) => fields2 === undefined ? undefined : { fields: fields2, entry };
   return [
-    defineTool("reveal_sealed_credential", `Decrypt one sealed field of a sealed credential on this machine. The server only sees that the ciphertext was fetched. Find credentials and their visible fields with the standard credential tools (search_credentials, get_credential). Refused unless its llm_visibility is visible. ${EXPOSURE_NOTE}`, {
+    defineTool("reveal_sealed_credential", `Decrypt one sealed field of a sealed credential on this machine. The server only sees that the ciphertext was fetched. Find credentials and their visible fields with the standard credential tools (search_credentials, get_credential). Refused unless its llm_visibility is visible. To use a secret (log in, call an API, type it on a device), use secret_exec instead: it never shows the value. ${EXPOSURE_NOTE}`, {
       credential_id: credentialId,
       field: exports_external.string().min(1).describe("password, totp, sealed_notes, or custom:{key}.")
     }, (args) => credentials.reveal(args.credential_id, args.field)),
@@ -36199,10 +36207,11 @@ function credentialTools(credentials, migration, names, entry) {
       llm_visibility: exports_external.enum(["use_only", "human_only"]).describe("human_only is the more restrictive."),
       field: exports_external.string().min(1).describe("One sealed field: password, totp, sealed_notes or custom:{key}. Omit for the whole credential; a field without its own value follows the credential.").optional()
     }, (args) => credentials.setLlmVisibility(args.credential_id, args.llm_visibility, args.field)),
-    defineTool("insert_sealed_credential", `Create a sealed credential in a seal root. It is kept in the space of that root. Whether an LLM may reveal its secrets follows the default the user chose for the tenant; only the user changes it, in the SafeKB app. password, totp, sealed_notes and the values of sealed custom fields are encrypted on this machine; title, username, url, tags, notes, visible custom fields and the key name of every custom field (sealed ones too) stay readable by the server so search and duplicate detection work. ${SECRET_ARGUMENT_NOTE}`, {
+    defineTool("insert_sealed_credential", `Create a sealed credential in a seal root. ${TYPED_NOTE} It is kept in the space of that root. Ask the user for llm_visibility before the call. password, totp, sealed_notes and the values of sealed custom fields are encrypted on this machine; title, username, url, tags, notes, visible custom fields and the key name of every custom field (sealed ones too) stay readable by the server so search and duplicate detection work. ${SECRET_ARGUMENT_NOTE}`, {
       root_id: rootRef("The seal root that will own it."),
       title: exports_external.string().min(1).describe("Visible to the server."),
       folder_id: exports_external.string().min(1).describe("Group it belongs to.").optional(),
+      llm_visibility: exports_external.enum(["use_only", "visible"]).describe("What an LLM may do with its secrets. Ask the user before the call and never choose for them. use_only: never shown to an LLM; only secret_exec hands it to a program. visible: an LLM may also reveal it into the conversation (reveal_sealed_credential, get_sealed_totp). An agent may pick visible only when that is the account default; otherwise the call fails and nothing is created: tell the user, who makes it visible in the SafeKB app after you create it use_only."),
       ...visibleFields,
       ...sealedFields
     }, async (args) => credentials.insert({
@@ -36210,7 +36219,7 @@ function credentialTools(credentials, migration, names, entry) {
       root_id: await names.resolve(args.root_id),
       typed_at_sidecar: atSidecar(args.typed_at_sidecar)
     })),
-    defineTool("update_sealed_credential", `Change a sealed credential with its seal root's signature. Pass only the fields to change; the save also attests the visible fields as they are now. If visible fields were changed without the key since the last sealed save, the call fails and names them until accept_visible_changes is true. ${SECRET_ARGUMENT_NOTE}`, {
+    defineTool("update_sealed_credential", `Change a sealed credential with its seal root's signature. Pass only the fields to change; the save also attests the visible fields as they are now. If visible fields were changed without the key since the last sealed save, the call fails and names them until accept_visible_changes is true. ${TYPED_NOTE} ${SECRET_ARGUMENT_NOTE}`, {
       credential_id: credentialId,
       expected_version: expectedVersion,
       accept_visible_changes: exports_external.boolean().describe("Attest visible fields that were changed without the key, after reviewing them.").optional(),
@@ -36399,9 +36408,9 @@ var SEALED_INSTRUCTIONS = `# Sealed documents (local, zero-knowledge)
 Sealed documents and folders are encrypted on this machine; the SafeKB server stores only ciphertext. Only the *_sealed* tools can read or write them. The standard tools show them as locked placeholders.
 
 - Each sealed tool opens the seal root (a sealed folder, or a standalone sealed document) it needs by itself, with the secret the local store that has it keeps: the system keyring, a key file, or the sidecar the user typed it into. There is no unlock step. Any session on this machine that uses these key stores can read every root whose secret is kept here.
-- A root whose secret no store holds fails with an error that says how the user supplies it: typed at the sidecar (safekb-mcp --sidecar, then: add <root>), after which the call is repeated, or as a file given to provide_seal_secret (secret_file).
+- A root whose secret no store holds fails with an error that says how the user supplies it: typed at the sidecar (${CLI} --sidecar, then: add <root>), after which the call is repeated, or as a file given to provide_seal_secret (secret_file).
 - Never ask the user to paste a secret and never pass one as text: text arguments and results are kept in the local transcript and sent to the model provider.
-- A new seal root gets its secret from store (default, system, file or sidecar) or key_out_path. With store "sidecar" the user types a passphrase in the sidecar's terminal (safekb-mcp --sidecar) while the call waits: tell them to look there.
+- A new seal root gets its secret from store (default, system, file or sidecar) or key_out_path. With store "sidecar" the user types a passphrase in the sidecar's terminal (${CLI} --sidecar) while the call waits: tell them to look there.
 - A seal root is named by its id or by the name this machine knows it by (the title it was created or last opened with): every root_id and new_root_id takes either. Documents and folders inside a root are named by id only.
 - Finding roots and ids: list_seal_keys shows the roots this machine holds a key for (id, name, status). The standard tools (list_documents, get_space_tree) show sealed folders and documents as locked placeholders, whose ids work as root_id, parent_id or document_id here. Ids are never guessed: look them up.
 - Workflow: search_sealed or list_sealed → get_sealed_section / read_sealed_document → update_sealed_document or replace_in_sealed_document with the seal_seq you read. Writes and deletes of a node take the seal_seq of your last read: read first.
@@ -36413,7 +36422,7 @@ Sealed documents and folders are encrypted on this machine; the SafeKB server st
 
 The keys of this machine, and backups, are handled by tools that never take or return a secret: list_seal_keys, rename_seal_key, rotate_seal_key, move_seal_key, delete_seal_key, export_seal_keys, import_seal_keys, export_backup and import_backup.
 
-- Every passphrase they need (of an export file or a key export), and the confirmation of delete_seal_key, are typed by the user at the sidecar (safekb-mcp --sidecar) while the call waits: tell them to look there, and to start the sidecar first if the call says none is running. Never ask for a passphrase in the conversation.
+- Every passphrase they need (of an export file or a key export), and the confirmation of delete_seal_key, are typed by the user at the sidecar (${CLI} --sidecar) while the call waits: tell them to look there, and to start the sidecar first if the call says none is running. Never ask for a passphrase in the conversation.
 - File paths must be absolute. An export never overwrites a file.
 - seal_document and unseal_document copy a document between hosted and sealed form without its text passing through you: pass ids, never read a document and retype it with insert_sealed_document. Both default to dry_run: true (report only) and delete_original: false: call once as is, read problems and not_carried, then call again with dry_run: false. Pass delete_original: true only when the user asked to move the document or to delete the original; the original is deleted only after the copy has been verified. They check the copy against the original before reporting it, and say what exists when something fails. When the target folder is in another space than the document, or several documents match the title the user gave, ask the user: never move a document to another space or pick one of several yourself. seal_document is not available with --sealed-only.
 - unseal_document is not a backup: it turns a sealed document into a plain one the server can read. export_backup writes an encrypted copy of everything the token reaches, and no key; export_seal_keys writes the keys.
@@ -36421,9 +36430,16 @@ The keys of this machine, and backups, are handled by tools that never take or r
 
 ## Sealed credentials
 
+Every credential is stored sealed (insert_sealed_credential). Use the standard insert_credential only when the user asks for an unsealed one. When the sidecar is needed and not running, ask the user to start it (${CLI} --sidecar) and repeat the call: never store the credential unsealed instead.
+
+Secrets in short:
+1. Ask the user whether LLMs may see its secrets: use_only (only secret_exec uses them) or visible (an LLM may also reveal them). Pass the answer as llm_visibility; never choose for them.
+2. Store it: insert_sealed_credential with the visible fields and, for a secret you must not see, typed_at_sidecar: ["password"] (or custom:{key}, totp, sealed_notes). The user types it at the sidecar (${CLI} --sidecar, started from a folder outside the knowledge-base repo) while the call waits. Never ask for it in the conversation.
+3. Use it: secret_exec with a handle {{secret://<credential_id>/<field>}} in env, stdin or files; your own program does the rest (HTTP, browser, adb, ssh, ...).
+
 A credential with \`sealed: true\` belongs to a seal root. Its title, username, url, tags, notes and visible custom fields are readable by the server: find it with the standard credential tools. Its password, TOTP seed, sealed_notes and sealed custom fields open only here: reveal_sealed_credential, get_sealed_totp, insert_sealed_credential, update_sealed_credential.
 
-- A secret the user has not given you yet (a card number, a PIN, a new password): never ask for it in the conversation. Call insert_sealed_credential or update_sealed_credential with typed_at_sidecar naming the fields; the user types them at the sidecar (safekb-mcp --sidecar) while the call waits. Or they enter it in the SafeKB web app.
+- A secret the user has not given you yet (a card number, a PIN, a new password): never ask for it in the conversation. Call insert_sealed_credential or update_sealed_credential with typed_at_sidecar naming the fields; the user types them at the sidecar (${CLI} --sidecar) while the call waits. Or they enter it in the SafeKB web app.
 - Reveal a secret only when the task needs it, and prefer get_sealed_totp over revealing a TOTP seed.
 - llm_visibility is set per credential, and llm_field_visibility overrides it for single sealed fields. reveal_sealed_credential and get_sealed_totp work only on a field that is visible. Only the user makes anything visible, in the SafeKB app.
 - To use a secret without seeing it (visible or use_only fields): secret_exec runs your own program with it in env, stdin or a temp file; every integration (HTTP, browser, adb, ssh, ...) is that program. Name it by handle, {{secret://<credential_id>/<field>}}; a totp handle becomes the current code. Prefer this over revealing, even for a visible field. A human_only field is never used by a tool: ask the user to enter it.
@@ -36566,7 +36582,6 @@ class KeyTransfer {
 }
 
 // src/main.ts
-var VERSION = package_default.version;
 function parsed(value) {
   if (value === null) {
     throw new Error("an option its mode requires was not parsed");
@@ -36711,7 +36726,7 @@ function apiUrlFor(options, config3) {
   const issuedFor = new URL(config3.url).origin;
   const requested = new URL(options.url).origin;
   if (requested !== issuedFor) {
-    throw new StartupError(`The token in ${options.configPath} was issued for ${issuedFor} and is not sent to ${requested}. To use ${requested} instead, run: safekb-mcp --authorize --url ${options.url}`);
+    throw new StartupError(`The token in ${options.configPath} was issued for ${issuedFor} and is not sent to ${requested}. To use ${requested} instead, run: ${CLI} --authorize --url ${options.url}`);
   }
   return options.url;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@safekb/mcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "SafeKB local MCP client: proxies the hosted SafeKB tools and adds zero-knowledge sealed documents.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Mustafa Öztürk",
@@ -34,8 +34,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.6",
-    "@safekb/canvas-markdown": "0.1.0",
-    "@safekb/sealed-crypto": "0.1.0",
+    "@safekb/canvas-markdown": "workspace:*",
+    "@safekb/sealed-crypto": "workspace:*",
     "@types/bun": "1.3.14",
     "@types/node": "20.19.43",
     "typescript": "5.9.3",