tinywebui 0.1.1 → 0.1.2

package/src/routes/settings.js

@@ -1,6 +1,6 @@
 import { json, readJson } from '../http.js';
-import { isClosed, enabledEntries, publicEntry } from '../config/models.js';
-import { modelsFor } from '../access/policy.js';
+import { isClosed, enabledEntries, publicEntry, findConnector } from '../config/models.js';
+import { modelsFor, SECRET_PATCH_KEYS } from '../access/policy.js';
 import { audit } from '../audit.js';
 import { setOverride } from '../config/approval.js';
 import { actor } from '../access/auth_gate.js';
@@ -50,7 +50,12 @@ export function settingsRoutes({ config, configFor, hub, saveConfig, toolsView }
     }) },
 
     { method: 'POST', path: /^\/api\/config$/, feature: FEATURE.SETTINGS, handle: async ({ req, res, auth }) => {
-      saveConfig(await readJson(req), actor(auth));
+      const patch = await readJson(req);
+      // Credentials and routing: the sole user or an admin, not any role that
+      // was merely granted the settings feature.
+      const secret = Object.keys(patch).filter((k) => SECRET_PATCH_KEYS.has(k));
+      if (secret.length && !auth.isAdmin) return json(res, 403, { error: `only an admin can change: ${secret.join(', ')}` });
+      saveConfig(patch, actor(auth));
       audit('admin.config_changed', { by: auth.userId ?? null });
       return json(res, 200, configFor(auth));
     } },
@@ -74,6 +79,32 @@ export function settingsRoutes({ config, configFor, hub, saveConfig, toolsView }
       return json(res, 200, { supported: true, restricted: true, models: allowed.map((id) => byId.get(id) || { id, name: null }) });
     } },
 
+    // "Test connection" for the connector editor. A key typed into the form is
+    // used as is; a blank one means the stored key of that connector ('default'
+    // is the top-level baseUrl/apiKey), since the page never holds keys.
+    { method: 'POST', path: /^\/api\/connectors\/test$/, feature: FEATURE.SETTINGS, handle: async ({ req, res, auth }) => {
+      if (!auth.isAdmin) return json(res, 403, { error: 'only an admin can test connectors' });
+      const body = await readJson(req);
+      const cfg = config();
+      const stored = body.id && body.id !== 'default' ? findConnector(cfg, body.id) : { baseUrl: cfg.baseUrl, apiKey: cfg.apiKey };
+      const baseUrl = String(body.baseUrl || stored?.baseUrl || '').replace(/\/+$/, '');
+      const apiKey = body.apiKey || stored?.apiKey || '';
+      if (!/^https?:\/\//.test(baseUrl)) return json(res, 400, { error: 'baseUrl must be an http(s) URL' });
+      try {
+        const r = await fetch(`${baseUrl}/models`, {
+          headers: apiKey ? { authorization: `Bearer ${apiKey}` } : {},
+          signal: AbortSignal.timeout(8000)
+        });
+        if (r.status === 401 || r.status === 403) return json(res, 200, { ok: false, error: `${r.status}: the endpoint rejected the key` });
+        // Not every OpenAI-compatible server lists models; reachable is the point.
+        const list = r.ok ? await r.json().catch(() => null) : null;
+        const rows = Array.isArray(list?.data) ? list.data : Array.isArray(list?.models) ? list.models : null;
+        return json(res, 200, { ok: r.status < 500, status: r.status, models: rows ? rows.length : null });
+      } catch (err) {
+        return json(res, 200, { ok: false, error: err.message });
+      }
+    } },
+
     // The grouped view behind the tools panel: built-ins, and every MCP
     // server's tools under it with that server's connection health.
     { method: 'GET', path: /^\/api\/tools$/, feature: FEATURE.TOOLS, handle: ({ res }) => json(res, 200, toolsView()) },

package/src/server.js

@@ -3,11 +3,11 @@ import { readFile } from 'node:fs/promises';
 import { watch, existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 
-import { createConfigSource, LockedError, configProblems } from './config/config.js';
-import { McpHub } from './mcp.js';
+import { createConfigSource, LockedError, configProblems, redactSecrets } from './config/config.js';
+import { McpHub, missingCommand } from './mcp.js';
 import { isClosed, findEntry } from './config/models.js';
 import { Store, SCHEMA_VERSION } from './store/index.js';
-import { fingerprint, featuresFor, modelsFor } from './access/policy.js';
+import { fingerprint, featuresFor, modelsFor, resolveAccess } from './access/policy.js';
 import { hashPassword, applyAccessPolicy } from './access/auth.js';
 import { audit } from './audit.js';
 import { logger } from './log.js';
@@ -18,6 +18,7 @@ import { documentToolDef, callReadDocument } from './tools/document_tool.js';
 import { askToolDef, callAskUser } from './tools/ask_tool.js';
 import { chatSearchToolDef, callSearchChats } from './tools/chat_search_tool.js';
 import { taskToolDef, callManageTasks } from './tools/task_tool.js';
+import { mcpToolDef, callManageMcp, MANAGE_MCP } from './tools/mcp_tool.js';
 import { automationToolDef, manageAutomation } from './automations/automation.js';
 import { overrideFor } from './config/approval.js';
 import { Retrieval } from './retrieval/retrieval.js';
@@ -56,6 +57,7 @@ function routeTable(app) {
     saveConfig: (patch, by) => app.saveConfig(patch, by), refreshConfig: () => app.refreshConfig(),
     auditMcp: (by, before) => app.auditMcp(by, before), swapHub: (servers) => app.swapHub(servers),
     multiUser: () => app.multiUser(), modelFor: (userId, role) => app.modelFor(userId, role),
+    instructionsFor: (userId) => app.instructionsFor(userId),
     toolsFor: (features) => app.toolsFor(features), toolsView: () => app.toolsView(), configFor: (auth) => app.configFor(auth)
   };
   return [
@@ -69,7 +71,7 @@ export const API_ROUTES = routeTable({}).map((r) => [r.method, r.path, r.feature
 
 // Fields a non-admin never sees: credentials, and where the deployment's
 // trust boundary sits.
-const ADMIN_ONLY_FIELDS = /^(apiKey|authPassword|sessionSecret|google|baseUrl|trusted|adminEmails|models$)/;
+const ADMIN_ONLY_FIELDS = /^(apiKey|keyHint|connectors|authPassword|sessionSecret|google|baseUrl|trusted|adminEmails|models$)/;
 
 /**
  * Starts an instance. Everything but port/host is optional and passed to
@@ -81,6 +83,9 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
   const initial = source.load();
   const problems = configProblems(initial);
   if (problems.length) throw new Error(problems.join('\n'));
+  if (initial.authMode === 'none' && !['127.0.0.1', '::1', 'localhost'].includes(host)) {
+    throw new Error("authMode 'none' is limited to loopback; use password login or a trusted-header gateway for network access");
+  }
 
   const store = new Store(source.dbPath(initial), { migrate: initial.autoMigrate !== false });
   // Runs live in this process, so nothing from before it can still be waiting.
@@ -126,14 +131,39 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
     saveConfig(patch, by) {
       const before = fingerprint(app.cfg, source.loadMcpServers());
       app.cfg = source.save(patch);
-      audit('config.changed', { by: by ?? 'local', keys: Object.keys(patch), values: patch, before, after: fingerprint(app.cfg, source.loadMcpServers()) });
+      audit('config.changed', { by: by ?? 'local', keys: Object.keys(patch), values: redactSecrets(patch), before, after: fingerprint(app.cfg, source.loadMcpServers()) });
       return app.cfg;
     },
     /** Re-reads the config after something other than saveConfig wrote the file. */
     refreshConfig() {
       app.cfg = source.load();
     },
-    auditMcp: (by, before) => audit('mcp.changed', { by: by ?? 'local', before, after: fingerprint(app.cfg, source.loadMcpServers()) }),
+    // `change` (action and server name, never a value) says what the assistant did.
+    auditMcp: (by, before, change) => audit('mcp.changed', { by: by ?? 'local', ...(change ? { change } : {}), before, after: fingerprint(app.cfg, source.loadMcpServers()) }),
+
+    /** What manage_mcp may do. It works on the file, not the live hub, so it sees what the next connect will. */
+    mcpEdit: {
+      locked: () => source.mcpLocked,
+      servers() {
+        let parsed;
+        try { parsed = JSON.parse(source.readMcpFile()); }
+        catch (err) { throw new Error(`mcp.json is not valid JSON (${err.message}); ask the user to fix it before anything is changed`); }
+        return structuredClone(parsed.mcpServers || parsed);
+      },
+      save(servers, { by, change }) {
+        const before = fingerprint(app.cfg, source.loadMcpServers());
+        source.saveMcpFile(JSON.stringify({ mcpServers: servers }, null, 2));
+        app.auditMcp(by, before, change);
+        // Noted now so the file watcher takes this write for our own. The
+        // reconnect waits for the reply to finish (onRunIdle): swapping now
+        // would close the servers the running turn is still calling.
+        mcpText = source.readMcpFile();
+        mcpDirty = true;
+      },
+      status: () => Object.fromEntries(app.hub.inventory(app.cfg.disabledTools).servers
+        .map((s) => [s.name, { status: s.status, error: s.error, tools: s.tools.length }])),
+      check: (spec) => missingCommand(spec)?.message ?? null
+    },
 
     multiUser: () => app.cfg.authMode === 'trusted-header',
 
@@ -158,10 +188,18 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
       return allowed.map(known).find(Boolean) || fallback;
     },
 
+    /** A person's own instructions, added after the system prompt, when an admin lets users set them. */
+    instructionsFor(userId) {
+      if (!userId || app.cfg.authMode !== 'trusted-header') return null;
+      if (!resolveAccess(app.cfg).customize.includes('instructions')) return null;
+      return store.users.getPrefs(userId).instructions || null;
+    },
+
     /** The tools a turn gets: what is switched on, minus manage_automation for
      * anyone whose role has no automations. */
     toolsFor: (features) => app.hub.activeTools(app.cfg.disabledTools)
-      .filter((t) => features.has(FEATURE.AUTOMATIONS) || t.function.name !== 'manage_automation'),
+      .filter((t) => features.has(FEATURE.AUTOMATIONS) || t.function.name !== 'manage_automation')
+      .filter((t) => features.has(FEATURE.MCP) || t.function.name !== MANAGE_MCP),
 
     /** A stored owner's features: null (tiers 1-2) is the one person. */
     ownerFeatures: (userId) => featuresFor(app.cfg, userId ? store.users.get(userId)?.role : null),
@@ -182,7 +220,13 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
 
     configFor(auth) {
       const pub = source.public(app.cfg);
-      if (auth.features.has(FEATURE.SETTINGS)) return pub;
+      if (auth.features.has(FEATURE.SETTINGS) && auth.isAdmin) return pub;
+      if (auth.features.has(FEATURE.SETTINGS)) {
+        // Allowed to edit settings, but not to see where the deployment's keys point.
+        const out = {};
+        for (const [k, v] of Object.entries(pub)) if (!ADMIN_ONLY_FIELDS.test(k)) out[k] = v;
+        return out;
+      }
       const out = {};
       for (const [k, v] of Object.entries(pub)) if (!ADMIN_ONLY_FIELDS.test(k)) out[k] = v;
       return { ...out, readOnly: true };
@@ -207,7 +251,15 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
       return run;
     },
 
-    onRunIdle: (chatId) => app.scheduler.drain(chatId)
+    onRunIdle: (chatId) => {
+      app.scheduler.drain(chatId);
+      // manage_mcp saved mcp.json during that run. Re-read the file rather than
+      // reuse what it saved: someone may have edited it since.
+      if (mcpDirty) {
+        mcpDirty = false;
+        app.swapHub(source.loadMcpServers()).catch((err) => log.error(`mcp reconnect failed: ${err.message}`));
+      }
+    }
   };
   app.runs = createRuns(app);
   app.scheduler = createScheduler(app);
@@ -230,12 +282,21 @@ export async function start({ port = 7777, host = '127.0.0.1', ...sourceOpts } =
         const out = manageAutomation(args, { ...ctx, store, triggerAutomation: scheduler.trigger });
         scheduler.arm();
         return out;
+      })
+      // Unlike the tools above it asks before anything but "list": a local
+      // server is a command run on this machine, and mcp.json holds credentials.
+      .registerLocal(mcpToolDef(), (args, ctx) => callManageMcp(args, { ...ctx, mcp: app.mcpEdit }), {
+        readOnly: (args) => args?.action === 'list',
+        gated: (args) => args?.action !== 'list',
+        executionMode: 'sequential'
       });
 
   app.hub = await connectHub(source.loadMcpServers());
   // What mcp.json said when the hub was last (re)built, so a reload can tell
   // a real edit from the echo of the UI's own save.
   let mcpText = source.readMcpFile();
+  // Set when manage_mcp has saved mcp.json and the hub still has to follow.
+  let mcpDirty = false;
   // The hub swap in progress, if any, and whether shutdown has begun.
   let swapping = Promise.resolve();
   let stopping = false;

package/src/set-password.js

@@ -1,7 +1,8 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, chmodSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { createConfigSource } from './config/config.js';
 import { hashPassword } from './access/auth.js';
+import { MIN_PASSWORD_LENGTH } from './access/policy.js';
 
 /** Reads one line without echoing it when attached to a terminal. */
 function ask(prompt) {
@@ -17,16 +18,26 @@ function ask(prompt) {
  * config file and switches authMode to 'single'. Existing sessions are
  * signed with sessionSecret, which is rotated so they all end here too.
  */
-export async function setPassword() {
-  const file = createConfigSource().path();
+export async function setPassword(opts = {}) {
+  if (opts.config && Object.hasOwn(opts.config, 'authMode') && opts.config.authMode !== 'single') {
+    throw new Error('authMode is set in code; change the JS config to use password login');
+  }
+  if (opts.config && Object.hasOwn(opts.config, 'authPassword')) {
+    throw new Error('authPassword is set in code; change the JS config to update the password');
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('set-password needs an interactive terminal; for headless startup set TINYWEBUI_PASSWORD');
+  }
+  const file = createConfigSource(opts).path();
   if (!file) throw new Error('no config file to write to');
   const pw = await ask('New password: ');
-  if (pw.length < 8) throw new Error('use at least 8 characters');
-  if (process.stdin.isTTY && (await ask('Repeat password: ')) !== pw) throw new Error('passwords do not match');
+  if (pw.length < MIN_PASSWORD_LENGTH) throw new Error(`use at least ${MIN_PASSWORD_LENGTH} characters`);
+  if ((await ask('Repeat password: ')) !== pw) throw new Error('passwords do not match');
   const current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
   current.authMode = 'single';
   current.authPassword = hashPassword(pw);
   delete current.sessionSecret; // regenerated on next start: every old session ends
-  writeFileSync(file, JSON.stringify(current, null, 2) + '\n');
-  console.log(`[tinywebui] password set in ${file}; restart TinyWebUI to apply`);
+  if (existsSync(file) && process.platform !== 'win32') chmodSync(file, 0o600);
+  writeFileSync(file, JSON.stringify(current, null, 2) + '\n', { mode: 0o600 });
+  console.log(`[tinywebui] password set in ${file}`);
 }

package/src/store/schema.js

@@ -2,7 +2,7 @@
 
 export const SCHEMA = `
 -- Optional auth/RBAC (config authMode 'single'/'multiuser'). Unused and
--- empty when authMode is 'none', the default -- these tables cost nothing
+-- empty when authMode is explicitly 'none' -- these tables cost nothing
 -- to have around.
 CREATE TABLE IF NOT EXISTS users (
   id            TEXT PRIMARY KEY,

package/src/tools/mcp_tool.js

@@ -0,0 +1,311 @@
+/**
+ * manage_mcp -- lets the model add, change, remove and switch MCP servers in
+ * mcp.json on the user's behalf.
+ *
+ * Two things make this tool different from the other built-ins:
+ *
+ * 1. A stdio server is a command run on this machine, so every call that
+ *    changes something asks first (see `gated` in registerLocal and
+ *    approvalFor), and an unattended run cannot use it at all.
+ * 2. mcp.json holds credentials (headers, env, tokens in URLs). The model gets
+ *    to write them but never to read them back: results carry the *names* of
+ *    headers and env variables, never their values, and an update to either is
+ *    a patch, so a key is never echoed back to change something next to it. A
+ *    value written as `${NAME}` is filled in from TinyWebUI's environment at
+ *    connect time (see expandRefs in mcp.js), which keeps the key out of the
+ *    file and out of the chat altogether.
+ *
+ * The file is saved at once; the servers reconnect when the reply is finished
+ * (server.js), so a turn never loses the tools it is in the middle of using.
+ */
+
+export const MANAGE_MCP = 'manage_mcp';
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/;
+const HEADER_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// A value that is only a reference to the environment holds no secret, so it
+// may be shown. Anything else about a header or env value is hidden.
+const REF_ONLY = /^(?:(?:Bearer|Basic|Token)\s+)?\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+const SECRETISH = /key|token|secret|pass|auth|bearer|credential/i;
+const HIDDEN = '<hidden>';
+
+const MAX_SERVERS = 30;
+const MAX_ENTRIES = 20;
+const MAX_ARGS = 50;
+const MAX_VALUE = 4000;
+
+export function mcpToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: MANAGE_MCP,
+      description: [
+        'Add, change, remove, enable or disable the MCP tool servers in mcp.json. The user is',
+        'asked to approve every change, so say what you are about to do and why in your reply.',
+        'Use "list" first to see what is configured and whether each server is connected.',
+        '',
+        'A server is either local ("command", optional "args", "env", "cwd": a program this',
+        'machine runs) or remote ("url", optional "headers", "transport": "sse" for SSE servers,',
+        'default Streamable HTTP). Never give both.',
+        '',
+        'Secrets. You can write API keys but never read them back: results show header and env',
+        'NAMES only. To change one header, pass just that header; the others are kept. Pass null',
+        'to remove one. Prefer "${NAME}" over a literal key, e.g. {"Authorization": "Bearer',
+        '${GITHUB_TOKEN}"}: TinyWebUI fills it in from its own environment, so the key is never',
+        'stored in mcp.json or in this chat. Use a literal value only if the user gave you the key',
+        'in this conversation, and never repeat a key in your replies.',
+        '',
+        'Changes are saved immediately but take effect when your reply is finished: a new',
+        "server's tools are available from the user's next message, so tell them that rather",
+        'than trying to call them now. Only add servers the user asked for, and only commands',
+        'they named or clearly approved: a local server runs as a program on their machine.',
+        '',
+        'Actions and what each needs:',
+        '- list: nothing.',
+        '- add: name, plus command or url (and optionally args, env, cwd, headers, transport).',
+        '- update: name, plus only the fields to change. args replaces the whole list. env and',
+        '  headers merge by name. You cannot switch a server between local and remote; remove and add.',
+        '- remove: name. Permanent.',
+        '- enable / disable: name. Disabling keeps the entry and drops the connection.'
+      ].join('\n'),
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'add', 'update', 'remove', 'enable', 'disable'] },
+          name: { type: 'string', description: 'Server name: letters, digits, "-" and "_", up to 32. It prefixes the names of its tools.' },
+          command: { type: 'string', description: 'Local server: the program to run, e.g. "npx" or "uvx".' },
+          args: { type: 'array', items: { type: 'string' }, description: 'Local server: its arguments.' },
+          cwd: { type: 'string', description: 'Local server: working directory.' },
+          env: { type: 'object', additionalProperties: { type: ['string', 'null'] }, description: 'Local server: environment variables to set. null removes one.' },
+          url: { type: 'string', description: 'Remote server: its http(s) URL.' },
+          transport: { type: 'string', enum: ['http', 'sse'], description: 'Remote server: "sse" only for SSE servers; the default is Streamable HTTP.' },
+          headers: { type: 'object', additionalProperties: { type: ['string', 'null'] }, description: 'Remote server: request headers, e.g. an Authorization header. null removes one.' }
+        },
+        required: ['action']
+      }
+    }
+  };
+}
+
+/* ---------- what the model is allowed to see ---------- */
+
+const shown = (v) => (REF_ONLY.test(String(v)) ? String(v) : HIDDEN);
+const maskMap = (obj) => obj && Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, shown(v)]));
+
+/** Arguments, with the value of anything that looks like a credential flag hidden. */
+function maskArgs(args = []) {
+  let afterSecretFlag = false;
+  return args.map((a) => {
+    const s = String(a);
+    const inline = /^(--?[\w-]+)=([\s\S]*)$/.exec(s);
+    if (inline) return SECRETISH.test(inline[1]) && !REF_ONLY.test(inline[2]) ? `${inline[1]}=${HIDDEN}` : s;
+    const isFlag = /^--?[\w-]+$/.test(s);
+    const hide = afterSecretFlag && !isFlag && !REF_ONLY.test(s);
+    afterSecretFlag = isFlag && SECRETISH.test(s);
+    return hide ? HIDDEN : s;
+  });
+}
+
+/** A URL without credentials: userinfo, query values and token-length path segments are hidden. */
+function maskUrl(raw) {
+  let u;
+  try { u = new URL(raw); } catch { return HIDDEN; }
+  const path = u.pathname.split('/').map((seg) => (seg.length >= 20 && !REF_ONLY.test(decodeURIComponent(seg)) ? HIDDEN : seg)).join('/');
+  const query = [...u.searchParams].map(([k, v]) => `${k}=${REF_ONLY.test(v) ? v : HIDDEN}`).join('&');
+  return `${u.protocol}//${u.host}${path}${query ? `?${query}` : ''}`;
+}
+
+/** Every literal secret value in a spec, so an error message that quotes one can be cleaned. */
+function literalSecrets(spec) {
+  const values = [...Object.values(spec.headers || {}), ...Object.values(spec.env || {})].map(String);
+  try {
+    const u = new URL(spec.url);
+    if (u.password) values.push(u.password);
+    values.push(...[...u.searchParams.values()], ...u.pathname.split('/').filter((s) => s.length >= 20));
+  } catch { /* a local server, or a URL that does not parse */ }
+  return values.filter((v) => v.length >= 6 && !REF_ONLY.test(v));
+}
+
+const scrub = (text, spec) => literalSecrets(spec).reduce((t, secret) => t.split(secret).join(HIDDEN), String(text));
+
+function describe(name, spec, live) {
+  const out = { name, type: spec.command ? 'local' : 'remote', enabled: !spec.disabled };
+  if (spec.command) {
+    out.command = spec.command;
+    if (spec.args?.length) out.args = maskArgs(spec.args);
+    if (spec.cwd) out.cwd = spec.cwd;
+    if (spec.env && Object.keys(spec.env).length) out.env = maskMap(spec.env);
+  } else {
+    out.url = maskUrl(spec.url);
+    out.transport = spec.transport === 'sse' ? 'sse' : 'http';
+    if (spec.headers && Object.keys(spec.headers).length) out.headers = maskMap(spec.headers);
+  }
+  if (live) {
+    out.status = live.status;
+    if (live.error) out.error = scrub(live.error, spec);
+    out.tools = live.tools;
+  }
+  return out;
+}
+
+/* ---------- checking what the model wrote ---------- */
+
+function plainMap(value, what, nameRule) {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`"${what}" must be an object of name: value`);
+  const entries = Object.entries(value);
+  if (entries.length > MAX_ENTRIES) throw new Error(`"${what}" can hold at most ${MAX_ENTRIES} entries`);
+  for (const [k, v] of entries) {
+    if (!nameRule.test(k)) throw new Error(`"${what}" has an invalid name`);
+    if (v === null) continue;
+    if (typeof v !== 'string' || v.length > MAX_VALUE || /[\r\n]/.test(v)) throw new Error(`"${what}.${k}" must be a single-line string, or null to remove it`);
+  }
+  return value;
+}
+
+/** Applies a name -> value | null patch to the current map; an empty result is dropped. */
+function patched(current, patch) {
+  if (patch === undefined) return current;
+  const out = { ...(current || {}) };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === null) delete out[k]; else out[k] = v;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function checkUrl(raw) {
+  if (typeof raw !== 'string' || !raw) throw new Error('"url" must be a string');
+  let u;
+  try { u = new URL(raw); } catch { throw new Error('"url" is not a valid URL'); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('"url" must start with http:// or https://');
+  return u;
+}
+
+const LOCAL_ONLY = ['command', 'args', 'cwd', 'env'];
+const REMOTE_ONLY = ['url', 'transport', 'headers'];
+
+function rejectOther(args, fields, kind) {
+  const given = fields.filter((f) => args[f] !== undefined);
+  if (given.length) throw new Error(`${given.map((f) => `"${f}"`).join(', ')} cannot be used with a ${kind} server`);
+}
+
+/** Folds the call's fields into a server entry, validating as it goes. `base` is the current entry for an update. */
+function build(args, base) {
+  const local = base ? Boolean(base.command) : Boolean(args.command);
+  if (!base && Boolean(args.command) === Boolean(args.url)) {
+    throw new Error('give either "command" (a local program) or "url" (a remote server), not both and not neither');
+  }
+  const spec = { ...(base || {}) };
+  if (local) {
+    rejectOther(args, REMOTE_ONLY, 'local');
+    if (args.command !== undefined) {
+      if (typeof args.command !== 'string' || !args.command.trim()) throw new Error('"command" must be a non-empty string');
+      spec.command = args.command.trim();
+    }
+    if (args.args !== undefined) {
+      if (!Array.isArray(args.args) || args.args.length > MAX_ARGS || args.args.some((a) => typeof a !== 'string' || a.length > MAX_VALUE)) {
+        throw new Error(`"args" must be a list of at most ${MAX_ARGS} strings`);
+      }
+      spec.args = args.args;
+    }
+    if (args.cwd !== undefined) {
+      if (typeof args.cwd !== 'string') throw new Error('"cwd" must be a string');
+      spec.cwd = args.cwd;
+    }
+    const env = patched(spec.env, plainMap(args.env, 'env', ENV_NAME));
+    if (env) spec.env = env; else delete spec.env;
+  } else {
+    rejectOther(args, LOCAL_ONLY, 'remote');
+    if (args.url !== undefined) { checkUrl(args.url); spec.url = args.url; }
+    if (args.transport !== undefined) {
+      if (!['http', 'sse'].includes(args.transport)) throw new Error('"transport" must be "http" or "sse"');
+      if (args.transport === 'sse') spec.transport = 'sse'; else delete spec.transport;
+    }
+    const headers = patched(spec.headers, plainMap(args.headers, 'headers', HEADER_NAME));
+    if (headers) spec.headers = headers; else delete spec.headers;
+  }
+  return spec;
+}
+
+/** Notes worth telling the model about a spec it just wrote. */
+function notes(spec, wrote) {
+  const out = {};
+  const plain = Object.entries({ ...(spec.headers || {}), ...(spec.env || {}) })
+    .filter(([k, v]) => wrote.includes(k) && SECRETISH.test(k) && !REF_ONLY.test(String(v)) && !String(v).includes('${'))
+    .map(([k]) => k);
+  if (plain.length) {
+    out.hint = `${plain.join(', ')} is stored as plain text in mcp.json. To keep a key out of the file, set an environment`
+      + ' variable for TinyWebUI and use "${NAME}" as the value instead.';
+  }
+  if (spec.url && spec.headers && new URL(spec.url).protocol === 'http:' && !/^(localhost|127\.|\[::1\])/.test(new URL(spec.url).hostname)) {
+    out.warning = 'This URL is plain http to another machine, so its headers travel unencrypted. Prefer https.';
+  }
+  return out;
+}
+
+/**
+ * `mcp`: { servers(), save(servers, change), locked(), status(), check(spec) }.
+ * `servers()` throws when mcp.json is not valid JSON, so a broken file is
+ * never overwritten with one new entry.
+ */
+export function callManageMcp(args, { mcp, chatId } = {}) {
+  if (!mcp) return 'Error: this tool is not available here.';
+  const { action } = args || {};
+  const known = ['list', 'add', 'update', 'remove', 'enable', 'disable'];
+  if (!known.includes(action)) return `Error: action must be one of ${known.join(', ')}.`;
+
+  let servers;
+  try { servers = mcp.servers(); } catch (err) { return `Error: ${err.message}`; }
+  const live = mcp.status();
+
+  if (action === 'list') {
+    return JSON.stringify({
+      editable: !mcp.locked(),
+      servers: Object.keys(servers).sort().map((n) => describe(n, servers[n], live[n]))
+    });
+  }
+  if (mcp.locked()) {
+    return 'Error: the MCP servers are locked in this deployment (set in code, or frozen), so they cannot be changed from here. Tell the user to edit mcp.json themselves.';
+  }
+
+  const name = args.name;
+  if (typeof name !== 'string' || !NAME.test(name)) return 'Error: "name" must be 1-32 letters, digits, "-" or "_".';
+  const exists = Object.hasOwn(servers, name);
+
+  try {
+    let wrote = [];
+    if (action === 'add') {
+      if (exists) return `Error: a server named "${name}" already exists. Use update to change it.`;
+      if (Object.keys(servers).length >= MAX_SERVERS) return `Error: at most ${MAX_SERVERS} servers can be configured.`;
+      servers[name] = build(args, null);
+      wrote = [...Object.keys(args.headers || {}), ...Object.keys(args.env || {})];
+    } else if (!exists) {
+      return `Error: no server named "${name}". Use list to see what is configured.`;
+    } else if (action === 'update') {
+      const fields = [...LOCAL_ONLY, ...REMOTE_ONLY, 'args'].filter((f) => args[f] !== undefined);
+      if (!fields.length) return 'Error: update needs at least one field to change.';
+      servers[name] = build(args, servers[name]);
+      wrote = [...Object.keys(args.headers || {}), ...Object.keys(args.env || {})];
+    } else if (action === 'remove') {
+      delete servers[name];
+    } else {
+      const on = action === 'enable';
+      if (on) delete servers[name].disabled; else servers[name].disabled = true;
+    }
+
+    mcp.save(servers, { by: `assistant (chat ${chatId ?? '?'})`, change: { action, name } });
+
+    const result = { saved: true, action, name, takes_effect: 'when this reply is finished; new tools are available from the next message' };
+    if (action !== 'remove') {
+      result.server = describe(name, servers[name]);
+      Object.assign(result, notes(servers[name], wrote));
+      const missing = servers[name].command && !servers[name].disabled ? mcp.check?.(servers[name]) : null;
+      if (missing) result.warning = missing;
+    }
+    return JSON.stringify(result);
+  } catch (err) {
+    // Validation messages name fields, never values; save errors name the file.
+    return `Error: ${err.message}`;
+  }
+}