dsh-mcp-servers 1.260930.4 → 1.261121.3

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.
package/README.md CHANGED
@@ -8,11 +8,14 @@ Made with DeepSeek V4 Flash.
8
8
 
9
9
  - **stdio, streamable http, and legacy SSE** transports — one shared endpoint field, tabs in the UI
10
10
  - **Tools registered automatically** under `mcp__<serverId>__<toolName>` — the same server-qualified shape the official `@deepseek-ai/dsh-mcp-client` and Claude Code use (e.g. server id `shadcn` → `mcp__shadcn__get_component`); names are normalized to `[A-Za-z0-9_-]`, capped at 64 chars, and get a deterministic 12-hex hash suffix when normalization/truncation would collide
11
- - **`tools/list_changed` re-sync** — when a server signals its tool list changed, the generation re-registers in place (old tools stay live until the new set registers)
11
+ - **Adaptive loading** — automatic, no setting: catalogs of **six tools or fewer register directly** (their schemas are cheap and skip the find/load round trip); **larger catalogs index** behind a small `mcp__tools__find` / `mcp__tools__load` / `mcp__tools__unload` gateway, and the model activates individual tools on demand (each schema lands in the context only once loaded, complete — no trimming, no accuracy loss). Big catalogs (100+ tools) stop costing ~100× their use while small ones stay friction-free
12
+ - **Tool whitelist** — a global *Enabled tools* regex over raw tool names (the Modes tab); only matching tools register (or index). Empty = all; an invalid regex is ignored with a warning. The whitelist filters before the adaptive count, so it can also push a big server under the eager threshold
13
+ - **`tools/list_changed` re-sync** — when a server signals its tool list changed, the generation re-registers in place (old tools stay live until the new set registers); indexed servers rebuild their index and keep loaded tools live, dropping ones the server removed — and a server whose catalog crosses the eager threshold flips modes by reconnecting
12
14
  - **Live status dots** — green when connected, red with the reason on failure; auto-reconnects with backoff when a connection drops (idle SSE streams, crashed processes)
13
15
  - **Test button** per card — probes connect + tool listing against the current draft without registering anything
14
16
  - **Edit cards** — type tabs, command/args textarea, env variables (or http headers) as key/value rows with show/hide values, paste `.env` from the clipboard, enabled switch
15
- - **Tabs**: All / Local / Remote / Backup & Restore
17
+ - **Modes tab** — one card with the adaptive-loading explainer and the global *Enabled tools* regex (commits on blur). There is no loading mode to pick — the behavior is always adaptive
18
+ - **Tabs**: All / Local / Remote / Modes / Backup & Restore
16
19
  - **Backup & Restore**: export/import the server list as JSON (with inline preview), and optional **WebDAV sync** (push/pull, https-only, Basic auth) plus an optional **daily automatic backup at 12:00 PM** — password stored server-side as a secret, never sent back to the browser
17
20
 
18
21
  ## Install
@@ -49,6 +52,32 @@ Rebuild after changes with `npm run build` — profiles load the built `dist/` a
49
52
  | command args | `-y`<br>`@modelcontextprotocol/server-everything` (one per line, first line is the command) |
50
53
  | env | key/value rows, e.g. `API_KEY` / your token |
51
54
 
55
+ ### Global settings (Modes tab)
56
+
57
+ | field | example |
58
+ | --- | --- |
59
+ | enabled tools | regex over raw tool names, e.g. `^(analyze\|trace)_`; empty = all; filters before the adaptive count |
60
+
61
+ ### Adaptive loading
62
+
63
+ Loading is decided per server at connect time — there is no mode setting:
64
+
65
+ - **≤ 6 tools after the whitelist filter** → all register directly, full schemas, no gateway indirection.
66
+ - **> 6 tools** → the catalog indexes behind four gateway tools (~resident cost a few hundred tokens, regardless of catalog size):
67
+
68
+ - `mcp__tools__find { query?, server?, schema? }` — keyword/regex search over the indexed catalogs; omit `query` to list the indexed servers; `schema: true` prints each match's parameter signature (`(a, b*)` — `*` = required) and full JSON schema
69
+ - `mcp__tools__load { names[] }` — register exact tools (`mcp__<serverId>__<toolName>` from find) into the live catalog
70
+ - `mcp__tools__unload { names[] }` — retire loaded tools
71
+ - `mcp__tools__exec { code }` — run one sandboxed JS snippet against every indexed tool (Code Mode, see below)
72
+
73
+ Loaded schemas are always complete — nothing is trimmed — so the model calls tools with native schema guidance on every path (100% accuracy). The eager/lazy split re-evaluates on every `tools/list_changed` re-sync and reconnect; a server whose catalog crosses the threshold switches modes automatically. The gateway disappears when no indexed server remains. If a server id is literally `tools`, the gateway renames itself to `mcp__dsh_tools__*` to avoid a collision.
74
+
75
+ **Connect on first use** — an indexed server's child process exits right after its index is built (zero idle RAM; a stdio MCP server typically costs 50–150 MB resident). The index stays in memory, so `find` works without a connection; the first `load` / `exec` / re-sync reconnects on demand (~one handshake), re-registers any tools that were loaded before parking, and the server then stays awake. Eager (≤ 6 tools) servers stay connected from boot by design — their tools are registered and callable immediately.
76
+
77
+ ### Code Mode (`exec`)
78
+
79
+ For composed or bulk work (3+ dependent calls, loops, batch traversal) the model can skip per-call round trips entirely: it discovers tools with `find`, reads schemas with `find {schema:true}`, then runs ONE sandboxed JavaScript snippet. `SERVER.tool(args)` / `mcp.call('server','tool',args)` dispatch the real MCP tools; intermediate results stay inside the code and only the captured `console.log` output (tail-preserved when capped, ~30s deadline) returns to the model. The sandbox is a bare V8 context — no `require`, `process`, or `fetch`. Unknown tool names error with nearest matches, so discovery mistakes self-correct. For 1–2 simple calls the native find/load path stays cheaper and schema-guided; the model picks per task, no setting involved.
80
+
52
81
  ### http / sse server
53
82
 
54
83
  | field | example |
@@ -78,7 +107,7 @@ The client UI follows the Harness design system: primitives are host-injected ex
78
107
 
79
108
  ## Notes / limitations
80
109
 
81
- - Tool input schemas are whitelist-stripped to the Harness-supported JSON Schema subset (`src/sanitize.ts`); unsupported keywords (`minLength`, `format`, `anyOf`, schema-form `additionalProperties`) are dropped.
110
+ - Tool input schemas are whitelist-stripped to the Harness-supported JSON Schema subset (`src/sanitize.ts`); unsupported keywords (`minLength`, `format`, `anyOf`, schema-form `additionalProperties`) are dropped. Schemas are never trimmed further — descriptions and annotations ship complete.
82
111
  - MCP results render as text; image/resource blocks collapse to JSON/text, not rich blocks.
83
112
  - WebDAV requires an https endpoint; credentials in the URL are rejected (passed separately).
84
- - Config/WebDAV routes are loopback-only.
113
+ - Config/WebDAV routes answer any caller; a web UI exposed over HTTP/S works like on loopback.
package/client/client.js CHANGED
@@ -10,8 +10,10 @@ window.__ModuleLoader__.load({
10
10
  //#region src/client/index.tsx
11
11
  /**
12
12
  * dsh-mcp-servers client: "MCP Servers" settings section. Each card shows a
13
- * read-only summary (status dot | id | endpoint | transport icon); Edit
14
- * switches to fields, and Save persists that card. Tokens match the Harness
13
+ * read-only summary (status dot | id | endpoint | transport icon | mode chip);
14
+ * Edit switches to fields, and Save persists that card. The Modes tab manages
15
+ * adaptive tool loading (≤6 tools register, larger catalogs index behind
16
+ * find/load) and the global tool whitelist. Tokens match the Harness
15
17
  * settings conventions; primitives are host-injected externals.
16
18
  */
17
19
  const name = "dsh-mcp-servers";
@@ -247,6 +249,7 @@ window.__ModuleLoader__.load({
247
249
  ["all", "All"],
248
250
  ["local", "Local"],
249
251
  ["remote", "Remote"],
252
+ ["modes", "Modes"],
250
253
  ["backup", "Backup & Restore"]
251
254
  ].map(([value, label]) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
252
255
  type: "button",
@@ -657,6 +660,8 @@ window.__ModuleLoader__.load({
657
660
  const [webdavUser, setWebdavUser] = (0, react.useState)("");
658
661
  const [webdavPass, setWebdavPass] = (0, react.useState)("");
659
662
  const [webdavDaily, setWebdavDaily] = (0, react.useState)(false);
663
+ const [enabledTools, setEnabledTools] = (0, react.useState)("");
664
+ const [toolsDraft, setToolsDraft] = (0, react.useState)("");
660
665
  const [error, setError] = (0, react.useState)("");
661
666
  const [notice, setNotice] = (0, react.useState)("");
662
667
  const [busy, setBusy] = (0, react.useState)(false);
@@ -665,6 +670,12 @@ window.__ModuleLoader__.load({
665
670
  const restoreRef = (0, react.useRef)(null);
666
671
  const keyRef = (0, react.useRef)(0);
667
672
  const newKey = () => `new-${++keyRef.current}`;
673
+ const applyGlobals = (g) => {
674
+ if (typeof g.enabledTools === "string") {
675
+ setEnabledTools(g.enabledTools);
676
+ setToolsDraft(g.enabledTools);
677
+ }
678
+ };
668
679
  const load = (alive = true) => {
669
680
  return fetch("/mcp-servers/config", { cache: "no-store" }).then((r) => {
670
681
  if (!r.ok) throw new Error("HTTP " + r.status);
@@ -678,6 +689,7 @@ window.__ModuleLoader__.load({
678
689
  if (typeof d?.webdavUrl === "string") setWebdavUrl(d.webdavUrl);
679
690
  if (typeof d?.webdavUser === "string") setWebdavUser(d.webdavUser);
680
691
  if (typeof d?.webdavDaily === "boolean") setWebdavDaily(d.webdavDaily);
692
+ applyGlobals(d);
681
693
  });
682
694
  };
683
695
  (0, react.useEffect)(() => {
@@ -710,7 +722,8 @@ window.__ModuleLoader__.load({
710
722
  servers: list,
711
723
  webdavUrl,
712
724
  webdavUser,
713
- webdavDaily
725
+ webdavDaily,
726
+ enabledTools
714
727
  };
715
728
  if (webdavPass !== "") body.webdavPass = webdavPass;
716
729
  const res = await fetch("/mcp-servers/config", {
@@ -752,7 +765,8 @@ window.__ModuleLoader__.load({
752
765
  };
753
766
  const backup = () => {
754
767
  const blob = new Blob([JSON.stringify({
755
- version: 1,
768
+ version: 2,
769
+ enabledTools,
756
770
  servers
757
771
  }, null, 2)], { type: "application/json" });
758
772
  const url = URL.createObjectURL(blob);
@@ -772,6 +786,7 @@ window.__ModuleLoader__.load({
772
786
  try {
773
787
  const parsed = JSON.parse(await file.text());
774
788
  if (!Array.isArray(parsed.servers)) throw new Error("backup has no servers list");
789
+ applyGlobals(parsed);
775
790
  setServers(parsed.servers);
776
791
  setCardKeys(parsed.servers.map((s) => s.id || newKey()));
777
792
  await persist(parsed.servers);
@@ -794,7 +809,8 @@ window.__ModuleLoader__.load({
794
809
  direction: direction === "push" ? "upload" : "download"
795
810
  };
796
811
  if (direction === "push") body.body = JSON.stringify({
797
- version: 1,
812
+ version: 2,
813
+ enabledTools,
798
814
  servers
799
815
  });
800
816
  const res = await fetch("/mcp-servers/webdav", {
@@ -807,6 +823,7 @@ window.__ModuleLoader__.load({
807
823
  if (direction === "pull") {
808
824
  const parsed = JSON.parse(d.body ?? "");
809
825
  if (!Array.isArray(parsed.servers)) throw new Error("backup has no servers list");
826
+ applyGlobals(parsed);
810
827
  setServers(parsed.servers);
811
828
  setCardKeys(parsed.servers.map((s) => s.id || newKey()));
812
829
  await persist(parsed.servers);
@@ -874,7 +891,7 @@ window.__ModuleLoader__.load({
874
891
  },
875
892
  children: error
876
893
  }) : null,
877
- tab !== "backup" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
894
+ tab === "all" || tab === "local" || tab === "remote" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
878
895
  variant: "outline",
879
896
  size: "sm",
880
897
  disabled: busy,
@@ -892,7 +909,56 @@ window.__ModuleLoader__.load({
892
909
  remote: servers.filter((s) => s.type !== "stdio").length
893
910
  }
894
911
  }),
895
- tab === "backup" ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
912
+ tab === "modes" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
913
+ style: {
914
+ flex: 1,
915
+ overflowY: "auto",
916
+ overflowX: "hidden",
917
+ padding: "12px 4px 24px",
918
+ display: "flex",
919
+ flexDirection: "column",
920
+ gap: 12,
921
+ maxWidth: 720
922
+ },
923
+ children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
924
+ className: "dshmcp-card",
925
+ style: card,
926
+ children: [
927
+ /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
928
+ style: {
929
+ fontWeight: 500,
930
+ fontSize: 13,
931
+ color: "var(--dsw-alias-label-primary)"
932
+ },
933
+ children: "Tool loading"
934
+ }),
935
+ /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
936
+ style: {
937
+ fontSize: 12,
938
+ lineHeight: "18px",
939
+ color: "var(--dsw-alias-label-tertiary, #8b93a1)"
940
+ },
941
+ children: "Automatic — nothing to pick. Catalogs of six tools or fewer register directly; larger ones index behind a find/load gateway, and loaded schemas are always complete, so accuracy never degrades and resident cost stays near zero."
942
+ }),
943
+ /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
944
+ value: toolsDraft,
945
+ placeholder: "Enabled tools (regex, optional) — e.g. ^(analyze|trace)_",
946
+ onChange: (e) => setToolsDraft(e.target.value),
947
+ onBlur: () => {
948
+ if (toolsDraft !== enabledTools) {
949
+ setEnabledTools(toolsDraft);
950
+ persist(servers);
951
+ }
952
+ },
953
+ style: {
954
+ ...fieldStyle,
955
+ padding: "4px 8px",
956
+ fontSize: 12
957
+ }
958
+ })
959
+ ]
960
+ })
961
+ }) : tab === "backup" ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
896
962
  style: {
897
963
  flex: 1,
898
964
  overflowY: "auto",
@@ -975,7 +1041,8 @@ window.__ModuleLoader__.load({
975
1041
  color: "var(--dsw-alias-label-primary, #1f2328)"
976
1042
  },
977
1043
  children: JSON.stringify({
978
- version: 1,
1044
+ version: 2,
1045
+ enabledTools,
979
1046
  servers
980
1047
  }, null, 2)
981
1048
  }) : null
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Code Mode: one sandboxed JS execution against every lazily-indexed MCP
3
+ * tool, in the spirit of Cloudflare's server-side Code Mode. Composed and
4
+ * bulk tasks run as ONE tool call — intermediate results stay inside the
5
+ * code and only the captured console output returns to the model.
6
+ */
7
+ /** Minimal structural shape of an MCP client — keeps this module testable. */
8
+ export type McpCaller = (request: {
9
+ name: string;
10
+ arguments: Record<string, unknown>;
11
+ }, signal?: AbortSignal) => Promise<unknown>;
12
+ export interface CallTarget {
13
+ serverId: string;
14
+ client: McpCaller;
15
+ /** Lazy index: public name -> wire name + description (mirrors LazyState.tools). */
16
+ index: Map<string, {
17
+ rawName: string;
18
+ description?: string;
19
+ }>;
20
+ }
21
+ export interface RunOptions {
22
+ signal?: AbortSignal;
23
+ deadlineMs?: number;
24
+ maxOutput?: number;
25
+ }
26
+ /** Render an MCP callTool result exactly like native tool registration does. */
27
+ export declare const renderCallResult: (value: unknown) => string;
28
+ /**
29
+ * Resolve (server, tool) against the live indexes. Accepts the public name
30
+ * (`mcp__rea__analyze_function`) or the raw wire name (`analyze_function`);
31
+ * errors list the nearest index matches so the model can self-correct.
32
+ */
33
+ export declare const resolveCall: (targets: CallTarget[], serverId: string, toolName: string) => {
34
+ target: CallTarget;
35
+ rawName: string;
36
+ };
37
+ /**
38
+ * Run user code in a bare V8 context: no require, no process, no fetch —
39
+ * only console (captured), timer bridges, `mcp.call(...)`, and one namespace
40
+ * object per indexed server whose members dispatch to the real tools.
41
+ */
42
+ export declare const runCode: (code: string, targets: CallTarget[], options?: RunOptions) => Promise<string>;
@@ -0,0 +1,160 @@
1
+ import vm from 'node:vm';
2
+ import { searchTools } from './lazy.js';
3
+ const DEFAULT_DEADLINE_MS = 30_000;
4
+ const DEFAULT_MAX_OUTPUT = 8_000;
5
+ // Keep the TAIL of long output: the last lines usually carry the result,
6
+ // while truncated heads are typically repeated framing the model wrote.
7
+ const capTail = (text, max) => {
8
+ if (text.length <= max)
9
+ return text;
10
+ const dropped = text.length - max;
11
+ return `[…${dropped} chars truncated…]\n${text.slice(text.length - max)}`;
12
+ };
13
+ const stringify = (value) => {
14
+ if (typeof value === 'string')
15
+ return value;
16
+ try {
17
+ return JSON.stringify(value, null, 2) ?? String(value);
18
+ }
19
+ catch {
20
+ return String(value);
21
+ }
22
+ };
23
+ /** Render an MCP callTool result exactly like native tool registration does. */
24
+ export const renderCallResult = (value) => {
25
+ const r = value;
26
+ if (!r || !Array.isArray(r.content))
27
+ return stringify(value);
28
+ const texts = r.content.filter((b) => b.type === 'text' && b.text).map((b) => b.text);
29
+ if (texts.length)
30
+ return texts.join('\n');
31
+ if (r.structuredContent !== undefined)
32
+ return stringify(r.structuredContent);
33
+ return stringify(value);
34
+ };
35
+ const shortErr = (err) => (err instanceof Error ? err.message : String(err));
36
+ /** True when every char of needle appears in hay, in order (typo-tolerant). */
37
+ const isSubsequence = (needle, hay) => {
38
+ let i = 0;
39
+ for (const ch of hay) {
40
+ if (ch === needle[i])
41
+ i++;
42
+ if (i >= needle.length)
43
+ return true;
44
+ }
45
+ return i >= needle.length;
46
+ };
47
+ /**
48
+ * Resolve (server, tool) against the live indexes. Accepts the public name
49
+ * (`mcp__rea__analyze_function`) or the raw wire name (`analyze_function`);
50
+ * errors list the nearest index matches so the model can self-correct.
51
+ */
52
+ export const resolveCall = (targets, serverId, toolName) => {
53
+ const target = targets.find((t) => t.serverId === serverId);
54
+ if (target === undefined) {
55
+ const known = targets.map((t) => t.serverId).join(', ') || '(none indexed)';
56
+ throw new Error(`Unknown server "${serverId}". Indexed servers: ${known}`);
57
+ }
58
+ const entries = [];
59
+ for (const [name, tool] of target.index) {
60
+ entries.push({ server: serverId, name, rawName: tool.rawName, description: tool.description ?? '', loaded: false });
61
+ }
62
+ const hit = target.index.get(toolName) ??
63
+ [...target.index.values()].find((tool) => tool.rawName === toolName);
64
+ if (hit === undefined) {
65
+ let near = searchTools(entries, toolName, serverId).slice(0, 5).map((m) => m.name);
66
+ if (near.length === 0) {
67
+ const needle = toolName.toLowerCase();
68
+ near = entries.filter((e) => isSubsequence(needle, e.name.toLowerCase())).slice(0, 5).map((e) => e.name);
69
+ }
70
+ const hint = near.length ? ` Nearest matches: ${near.join(', ')}.` : '';
71
+ throw new Error(`Tool "${toolName}" is not indexed on server "${serverId}".${hint}`);
72
+ }
73
+ return { target, rawName: hit.rawName };
74
+ };
75
+ /**
76
+ * Run user code in a bare V8 context: no require, no process, no fetch —
77
+ * only console (captured), timer bridges, `mcp.call(...)`, and one namespace
78
+ * object per indexed server whose members dispatch to the real tools.
79
+ */
80
+ export const runCode = async (code, targets, options = {}) => {
81
+ const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
82
+ const maxOutput = options.maxOutput ?? DEFAULT_MAX_OUTPUT;
83
+ const callTool = async (serverId, toolName, args, signal) => {
84
+ const { target, rawName } = resolveCall(targets, serverId, toolName);
85
+ return target.client({ name: rawName, arguments: (args ?? {}) }, signal ?? options.signal);
86
+ };
87
+ // Namespace proxy: any property access returns an async dispatch function,
88
+ // validated against the index at call time (so discovery errors stay local).
89
+ const namespaceFor = (serverId) => new Proxy({ __serverId: serverId }, {
90
+ get: (_t, prop) => {
91
+ if (typeof prop !== 'string' || prop === 'then')
92
+ return undefined;
93
+ return async (args, signal) => renderCallResult(await callTool(serverId, prop, args, signal));
94
+ },
95
+ });
96
+ const namespaces = {};
97
+ for (const target of targets)
98
+ namespaces[target.serverId] = namespaceFor(target.serverId);
99
+ const mcp = {
100
+ call: async (serverId, toolName, args, signal) => renderCallResult(await callTool(serverId, toolName, args, signal)),
101
+ servers: () => targets.map((t) => t.serverId),
102
+ };
103
+ const lines = [];
104
+ const record = (prefix, parts) => {
105
+ lines.push((prefix ? prefix + ' ' : '') + parts.map((p) => stringify(p)).join(' '));
106
+ };
107
+ const sandboxConsole = {
108
+ log: (...parts) => record('', parts),
109
+ info: (...parts) => record('', parts),
110
+ warn: (...parts) => record('[warn]', parts),
111
+ error: (...parts) => record('[error]', parts),
112
+ };
113
+ const timers = new Set();
114
+ const sandboxSetTimeout = (fn, ms) => {
115
+ const t = setTimeout(() => { timers.delete(t); fn(); }, ms);
116
+ timers.add(t);
117
+ return t;
118
+ };
119
+ const sandboxClearTimeout = (t) => { clearTimeout(t); timers.delete(t); };
120
+ const context = vm.createContext({
121
+ console: sandboxConsole,
122
+ setTimeout: sandboxSetTimeout,
123
+ clearTimeout: sandboxClearTimeout,
124
+ mcp,
125
+ ...namespaces,
126
+ });
127
+ // Bare top-level await is not valid in a vm Script; wrap once. The sync
128
+ // deadline catches infinite loops; the outer race catches hung awaits.
129
+ // Errors (throw, ReferenceError, timeouts) become output text — the model
130
+ // keeps any partial console output and can self-correct on the next call.
131
+ const script = new vm.Script(`(async () => {\n${code}\n})()`, { filename: 'mcp-exec.js' });
132
+ let result;
133
+ try {
134
+ const promise = script.runInContext(context, { timeout: deadlineMs });
135
+ // If the deadline or abort wins the race, a later rejection of the user
136
+ // promise must not surface as an unhandled rejection.
137
+ promise.catch(() => { });
138
+ const deadline = new Promise((_, reject) => {
139
+ const t = setTimeout(() => reject(new Error(`exec timed out after ${Math.round(deadlineMs / 1000)}s`)), deadlineMs);
140
+ timers.add(t);
141
+ // The reject timer is unconditional: it also fires while user awaits.
142
+ });
143
+ const abort = new Promise((_, reject) => {
144
+ options.signal?.addEventListener('abort', () => reject(new Error('exec aborted')), { once: true });
145
+ });
146
+ result = await Promise.race([promise, deadline, abort]);
147
+ }
148
+ catch (err) {
149
+ lines.push(`[error] ${shortErr(err)}`);
150
+ }
151
+ finally {
152
+ for (const t of timers)
153
+ clearTimeout(t);
154
+ }
155
+ if (result !== undefined)
156
+ lines.push(`=> ${stringify(result)}`);
157
+ if (lines.length === 0)
158
+ return '(no output — use console.log to emit results)';
159
+ return capTail(lines.join('\n'), maxOutput);
160
+ };
package/dist/index.d.ts CHANGED
@@ -18,6 +18,8 @@ export interface McpServerConfig {
18
18
  * live reference, and business consumers read `.get()` on their own refs.
19
19
  */
20
20
  export interface Config {
21
+ /** One whitelist for every server. */
22
+ enabledTools: Volatile<string>;
21
23
  servers: Volatile<McpServerConfig[]>;
22
24
  webdavUrl: Volatile<string | undefined>;
23
25
  webdavUser: Volatile<string | undefined>;
@@ -29,6 +31,7 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
29
31
  webdavUser: Schema<string, string, "volatile">;
30
32
  webdavPass: Schema<string, string, "volatile">;
31
33
  webdavDaily: Schema<boolean, boolean, "volatile-defined">;
34
+ enabledTools: Schema<string, string, "volatile-defined">;
32
35
  servers: Schema<NoInfer<({
33
36
  id?: string | null | undefined;
34
37
  enabled?: boolean | null | undefined;
@@ -53,6 +56,7 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
53
56
  webdavUser: Schema<string, string, "volatile">;
54
57
  webdavPass: Schema<string, string, "volatile">;
55
58
  webdavDaily: Schema<boolean, boolean, "volatile-defined">;
59
+ enabledTools: Schema<string, string, "volatile-defined">;
56
60
  servers: Schema<NoInfer<({
57
61
  id?: string | null | undefined;
58
62
  enabled?: boolean | null | undefined;
package/dist/index.js CHANGED
@@ -7,6 +7,8 @@ import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
7
7
  import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
8
8
  import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
9
9
  import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
10
+ import { compileWhitelist, formatMatches, formatMatchesDetailed, formatServerOverview, searchTools, toolAllowed } from './lazy.js';
11
+ import { runCode } from './codemode.js';
10
12
  import { publicToolName } from './naming.js';
11
13
  import { sanitizeSchema } from './sanitize.js';
12
14
  export const name = 'mcp-servers';
@@ -30,11 +32,6 @@ function readJson(req) {
30
32
  req.on('error', reject);
31
33
  });
32
34
  }
33
- /** The config route carries env/headers that may hold tokens — loopback only. */
34
- function isLoopback(req) {
35
- const host = req.headers.host ?? '';
36
- return /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
37
- }
38
35
  /** Keep error surfaces readable (e.g. a Cloudflare challenge page dumped as the body). */
39
36
  function shortErr(err) {
40
37
  const msg = err instanceof Error ? err.message : String(err);
@@ -96,6 +93,7 @@ export const Config = Schema.object({
96
93
  webdavUser: Schema.string().description('WebDAV username (optional).').volatile(),
97
94
  webdavPass: Schema.string().role('secret').description('WebDAV password (stored locally, never sent to the browser).').volatile(),
98
95
  webdavDaily: Schema.boolean().default(false).description('Push a backup to WebDAV every day at 12:00 PM.').volatile(),
96
+ enabledTools: Schema.string().default('').description('Regex over tool names; only matching tools register or index. Empty = all. Applies to every server.').volatile(),
99
97
  servers: Schema.array(Schema.object({
100
98
  id: Schema.string().required().description('Unique server id; also the tool-name prefix.'),
101
99
  enabled: Schema.boolean().default(true),
@@ -218,6 +216,7 @@ export function apply(ctx, config) {
218
216
  ctx.effect(() => ctx.settings.configure({ auto: false }, ctx.fiber));
219
217
  /** Capture the live config refs as an immutable snapshot — replaces `scope.get()`. */
220
218
  const readConfig = () => ({
219
+ enabledTools: config.enabledTools.get(),
221
220
  servers: config.servers.get(),
222
221
  webdavUrl: config.webdavUrl.get(),
223
222
  webdavUser: config.webdavUser.get(),
@@ -291,59 +290,169 @@ export function apply(ctx, config) {
291
290
  scheduleReconnect(id);
292
291
  }
293
292
  };
293
+ // Adaptive threshold: catalogs at or below this size register directly —
294
+ // their schemas are cheap and skip the find/load round trip. Bigger ones
295
+ // index behind the find/load gateway instead.
296
+ const AUTO_EAGER_TOOLS = 6;
294
297
  const connectServer = async (server) => {
295
298
  const client = new Client({ name: 'dsh-mcp', version: '1.0.0' });
296
299
  await client.connect(createTransport(server));
297
300
  const conn = { client, disposers: [], toolCount: 0, closing: false };
298
- conn.disposers = await registerTools(server, client);
299
- conn.toolCount = conn.disposers.length;
301
+ // Adaptive loading — the only behavior, no setting: a small filtered
302
+ // catalog registers directly (its schemas are cheap and skip the find/load
303
+ // round trip); a large one indexes behind the find/load gateway instead.
304
+ // Loaded schemas are always complete, so accuracy never degrades either way.
305
+ const tools = await fetchTools(client);
306
+ if (tools.length > AUTO_EAGER_TOOLS) {
307
+ conn.lazy = buildLazyIndex(server, client, tools);
308
+ conn.toolCount = conn.lazy.tools.size;
309
+ }
310
+ else {
311
+ conn.disposers = registerTools(server, client, tools);
312
+ conn.toolCount = conn.disposers.length;
313
+ }
300
314
  // Real-time status: a dropped transport (child process exit, network loss)
301
315
  // unregisters the tools and marks the server down until the next start().
302
- client.onclose = () => { if (!conn.closing)
303
- onDisconnect(server.id, 'connection closed'); };
304
- client.onerror = (err) => { if (!conn.closing)
305
- onDisconnect(server.id, shortErr(err)); };
306
- // Re-sync the tool generation when the server signals a changed tool list.
307
- client.setNotificationHandler(ToolListChangedNotificationSchema, () => { void resync(server.id); });
316
+ attachConnHandlers(server, conn);
317
+ // Connect-on-first-use: a lazily indexed catalog needed the transport only
318
+ // to build its index, so hibernate right away — the child process exits
319
+ // (zero idle RAM) and the gateway wakes it on the first load/exec.
320
+ if (conn.lazy !== undefined)
321
+ hibernate(conn);
308
322
  return conn;
309
323
  };
324
+ // Global whitelist over raw tool names; an invalid pattern warns once per
325
+ // read and allows everything, never silently hiding tools.
326
+ const compileWhitelistFor = () => {
327
+ const compiled = compileWhitelist(readConfig().enabledTools);
328
+ if (compiled !== undefined && 'error' in compiled) {
329
+ ctx.logger?.warn(`[mcp] invalid enabledTools regex ignored (${compiled.error})`);
330
+ return undefined;
331
+ }
332
+ return compiled;
333
+ };
334
+ // Register a single tool generation; throws when the schema is rejected, so
335
+ // callers decide whether one bad tool drops a whole server or just itself.
336
+ const registerOne = (server, client, tool) => {
337
+ const fallbackDescription = `MCP tool ${tool.rawName} (server ${server.id})`;
338
+ const fullName = publicToolName(server.id, tool.rawName);
339
+ const definition = {
340
+ name: fullName,
341
+ description: tool.description ?? fallbackDescription,
342
+ parameters: sanitizeSchema(tool.inputSchema),
343
+ output: {
344
+ schema: {},
345
+ render: (_args, value) => [{ type: 'text', text: renderResult(value) }],
346
+ },
347
+ async execute(args, exec) {
348
+ return client.callTool({ name: tool.rawName, arguments: args }, undefined, { signal: exec.signal });
349
+ },
350
+ };
351
+ return ctx.tools.register(definition);
352
+ };
310
353
  // Register one full generation of a server's tools; used by connect and by
311
354
  // the list_changed re-sync. The old generation is disposed only AFTER a new
312
355
  // one registers, so a failed fetch keeps the previous tools live.
313
- const registerTools = async (server, client) => {
314
- const { tools } = await client.listTools();
356
+ const registerTools = (server, client, tools) => {
315
357
  const disposers = [];
316
358
  for (const tool of tools) {
317
- const fullName = publicToolName(server.id, tool.name);
318
- const definition = {
319
- name: fullName,
320
- description: tool.description ?? `MCP tool ${tool.name} (server ${server.id})`,
321
- parameters: sanitizeSchema(tool.inputSchema),
322
- output: {
323
- schema: {},
324
- render: (_args, value) => [{ type: 'text', text: renderResult(value) }],
325
- },
326
- async execute(args, exec) {
327
- return client.callTool({ name: tool.name, arguments: args }, undefined, { signal: exec.signal });
328
- },
329
- };
330
359
  try {
331
- disposers.push(ctx.tools.register(definition));
360
+ disposers.push(registerOne(server, client, tool));
332
361
  }
333
362
  catch (err) {
334
363
  // one bad schema must not drop the whole server; register the rest
335
- ctx.logger?.warn(`[mcp] ${server.id}: skipped tool ${tool.name}: ${err instanceof Error ? err.message : err}`);
364
+ ctx.logger?.warn(`[mcp] ${server.id}: skipped tool ${tool.rawName}: ${err instanceof Error ? err.message : err}`);
336
365
  }
337
366
  }
338
367
  return disposers;
339
368
  };
369
+ // Adaptive mode: fetch the whitelist-filtered tool list once, then either
370
+ // register it or index it. (Schemas ship complete either way.)
371
+ const fetchTools = async (client) => {
372
+ const { tools } = await client.listTools();
373
+ const whitelist = compileWhitelistFor();
374
+ return tools
375
+ .filter((tool) => toolAllowed(whitelist, tool.name))
376
+ .map((tool) => ({ rawName: tool.name, description: tool.description, inputSchema: tool.inputSchema }));
377
+ };
378
+ // Lazy mode: index the (already fetched, whitelist-filtered) tool list
379
+ // without registering anything, so find/load never surface excluded tools.
380
+ const buildLazyIndex = (server, client, tools) => {
381
+ const index = new Map();
382
+ for (const tool of tools) {
383
+ const fallbackDescription = `MCP tool ${tool.rawName} (server ${server.id})`;
384
+ index.set(publicToolName(server.id, tool.rawName), {
385
+ rawName: tool.rawName,
386
+ description: tool.description ?? fallbackDescription,
387
+ inputSchema: tool.inputSchema,
388
+ });
389
+ }
390
+ return { tools: index, loaded: new Map() };
391
+ };
340
392
  const resync = async (id) => {
341
393
  const conn = connections.get(id);
342
394
  const server = serverConfig(id);
343
395
  if (!conn || !server || conn.closing)
344
396
  return;
397
+ if (conn.hibernating) {
398
+ // Parked server: wake first so re-sync talks to a live transport. A
399
+ // failed wake is already reflected in status — stay parked quietly.
400
+ try {
401
+ await wake(id);
402
+ }
403
+ catch {
404
+ return;
405
+ }
406
+ }
345
407
  try {
346
- const disposers = await registerTools(server, conn.client);
408
+ const tools = await fetchTools(conn.client);
409
+ if ((tools.length > AUTO_EAGER_TOOLS) !== (conn.lazy !== undefined)) {
410
+ // The catalog crossed the adaptive threshold: switch modes by
411
+ // reconnecting, so both paths share one code path.
412
+ ctx.logger?.info(`[mcp] ${id}: catalog crossed the eager threshold (${tools.length} tools), reconnecting`);
413
+ conn.closing = true;
414
+ connections.delete(id);
415
+ for (const dispose of conn.disposers) {
416
+ try {
417
+ dispose();
418
+ }
419
+ catch { /* already gone */ }
420
+ }
421
+ void conn.client.close().catch(() => { });
422
+ void reconnectServer(id);
423
+ return;
424
+ }
425
+ if (conn.lazy) {
426
+ // Lazy re-sync rebuilds the index, keeps loaded tools live, and drops
427
+ // ones the server removed. Register the new generation BEFORE disposing
428
+ // the old one so surviving tools never blink out of the catalog.
429
+ const fresh = buildLazyIndex(server, conn.client, tools);
430
+ const nextLoaded = new Map();
431
+ for (const [name, tool] of conn.lazy.loaded) {
432
+ const replacement = fresh.tools.get(name);
433
+ if (replacement === undefined)
434
+ continue; // removed by the server
435
+ try {
436
+ nextLoaded.set(name, registerOne(server, conn.client, replacement));
437
+ }
438
+ catch (err) {
439
+ ctx.logger?.warn(`[mcp] ${id}: re-sync dropped tool ${name}: ${err instanceof Error ? err.message : err}`);
440
+ }
441
+ }
442
+ for (const dispose of conn.lazy.loaded.values()) {
443
+ try {
444
+ dispose();
445
+ }
446
+ catch { /* already gone */ }
447
+ }
448
+ conn.lazy = { tools: fresh.tools, loaded: nextLoaded };
449
+ conn.disposers = [...nextLoaded.values()];
450
+ conn.toolCount = fresh.tools.size;
451
+ ctx.logger?.info(`[mcp] ${id}: lazy re-synced, ${fresh.tools.size} indexed, ${nextLoaded.size} loaded`);
452
+ syncGateway();
453
+ return;
454
+ }
455
+ const disposers = registerTools(server, conn.client, tools);
347
456
  for (const dispose of conn.disposers) {
348
457
  try {
349
458
  dispose();
@@ -359,6 +468,300 @@ export function apply(ctx, config) {
359
468
  }
360
469
  };
361
470
  const serverConfig = (id) => readConfig().servers.find((s) => s.id === id);
471
+ // Lifecycle handlers shared by every fresh transport (connect and wake).
472
+ // Hibernation silences them: the transport is closed on purpose, so neither
473
+ // a drop nor an error may trigger teardown or re-sync while parked.
474
+ const attachConnHandlers = (server, conn) => {
475
+ conn.client.onclose = () => { if (!conn.closing && !conn.hibernating)
476
+ onDisconnect(server.id, 'connection closed'); };
477
+ conn.client.onerror = (err) => { if (!conn.closing && !conn.hibernating)
478
+ onDisconnect(server.id, shortErr(err)); };
479
+ conn.client.setNotificationHandler(ToolListChangedNotificationSchema, () => { void resync(server.id); });
480
+ };
481
+ // Connect-on-first-use, step 1: park a lazily indexed server. The index
482
+ // stays in memory while the transport closes, so the child process exits
483
+ // (zero idle RAM). Loaded tools are retired but remembered by name — wake
484
+ // re-registers them against the fresh index.
485
+ const hibernate = (conn) => {
486
+ conn.hibernating = true;
487
+ const pending = new Set();
488
+ const loaded = conn.lazy?.loaded;
489
+ if (loaded !== undefined) {
490
+ for (const [name, dispose] of loaded) {
491
+ pending.add(name);
492
+ try {
493
+ dispose();
494
+ }
495
+ catch { /* already gone */ }
496
+ }
497
+ loaded.clear();
498
+ }
499
+ conn.disposers = [];
500
+ conn.pendingLoaded = pending;
501
+ void conn.client.close().catch(() => { });
502
+ };
503
+ // Connect-on-first-use, step 2: revive a hibernating server on the first
504
+ // gateway call that needs a live transport (load/unload/exec/resync; find
505
+ // is index-only and never wakes). Concurrent callers share one wake.
506
+ const waking = new Map();
507
+ const wake = (id) => {
508
+ const existing = waking.get(id);
509
+ if (existing !== undefined)
510
+ return existing;
511
+ // Visible to the failure path: a late wake error (after a successful
512
+ // connect) must close the fresh client or its child process leaks.
513
+ let freshClient;
514
+ const task = (async () => {
515
+ const conn = connections.get(id);
516
+ if (conn === undefined || !conn.hibernating)
517
+ return;
518
+ const server = serverConfig(id);
519
+ if (server === undefined)
520
+ return;
521
+ const client = new Client({ name: 'dsh-mcp', version: '1.0.0' });
522
+ freshClient = client;
523
+ await client.connect(createTransport(server));
524
+ // Handlers bind lazily (they read conn.client at fire time) and stay
525
+ // silenced by hibernating until the wake fully succeeds.
526
+ attachConnHandlers(server, conn);
527
+ const tools = await fetchTools(client);
528
+ const fresh = buildLazyIndex(server, client, tools);
529
+ const nextLoaded = new Map();
530
+ const pending = conn.pendingLoaded;
531
+ if (pending !== undefined) {
532
+ for (const name of pending) {
533
+ const replacement = fresh.tools.get(name);
534
+ if (replacement === undefined)
535
+ continue; // removed while hibernating
536
+ try {
537
+ nextLoaded.set(name, registerOne(server, client, replacement));
538
+ }
539
+ catch (err) {
540
+ ctx.logger?.warn(`[mcp] ${id}: wake dropped tool ${name}: ${err instanceof Error ? err.message : err}`);
541
+ }
542
+ }
543
+ }
544
+ conn.lazy = { tools: fresh.tools, loaded: nextLoaded };
545
+ conn.disposers = [...nextLoaded.values()];
546
+ conn.pendingLoaded = undefined;
547
+ conn.toolCount = fresh.tools.size;
548
+ conn.client = client;
549
+ conn.hibernating = false;
550
+ status.set(id, { ok: true });
551
+ ctx.logger?.info(`[mcp] ${id}: woken on first use (${fresh.tools.size} indexed, ${nextLoaded.size} re-registered)`);
552
+ })()
553
+ .catch((err) => {
554
+ // A late failure (listTools/registration after a successful connect)
555
+ // would orphan the new child process — close it; if connect itself
556
+ // failed the close is a harmless no-op. Keep the hibernation
557
+ // bookkeeping so the next use retries instead of giving up.
558
+ if (freshClient !== undefined)
559
+ void freshClient.close().catch(() => { });
560
+ const conn = connections.get(id);
561
+ if (conn !== undefined) {
562
+ conn.hibernating = true;
563
+ conn.pendingLoaded ??= new Set();
564
+ }
565
+ status.set(id, { ok: false, error: shortErr(err) });
566
+ throw err;
567
+ })
568
+ .finally(() => { waking.delete(id); });
569
+ waking.set(id, task);
570
+ return task;
571
+ };
572
+ const wakeSleepy = async () => {
573
+ const sleepy = lazyConns().filter(({ conn }) => conn.hibernating === true);
574
+ await Promise.all(sleepy.map(({ server }) => wake(server.id)));
575
+ };
576
+ // ---- Lazy gateway -------------------------------------------------------
577
+ // One small tool set stands in for every lazily-indexed server's catalog:
578
+ // find searches the indexes, load/unload register and retire individual
579
+ // tools, and exec runs composed or bulk tasks as one sandboxed script.
580
+ // Adaptive mode decides per server at connect time, so the gateway
581
+ // tracks live connections rather than config.
582
+ let gatewayDisposers = [];
583
+ const gatewayPrefix = () => readConfig().servers.some((s) => s.id === 'tools') ? 'mcp__dsh_tools' : 'mcp__tools';
584
+ const lazyConns = () => {
585
+ const out = [];
586
+ for (const s of readConfig().servers) {
587
+ const conn = connections.get(s.id);
588
+ if (!s.enabled || conn?.lazy === undefined)
589
+ continue;
590
+ out.push({ server: s, conn: conn });
591
+ }
592
+ return out;
593
+ };
594
+ const syncGateway = () => {
595
+ const anyLazy = readConfig().servers.some((s) => s.enabled && connections.get(s.id)?.lazy !== undefined);
596
+ if (!anyLazy) {
597
+ if (gatewayDisposers.length === 0)
598
+ return;
599
+ for (const dispose of gatewayDisposers) {
600
+ try {
601
+ dispose();
602
+ }
603
+ catch { /* already gone */ }
604
+ }
605
+ gatewayDisposers = [];
606
+ return;
607
+ }
608
+ if (gatewayDisposers.length > 0)
609
+ return;
610
+ const prefix = gatewayPrefix();
611
+ const registerTextTool = (name, description, parameters, run) => ctx.tools.register({
612
+ name,
613
+ description,
614
+ parameters: parameters,
615
+ output: { schema: {}, render: (_args, value) => [{ type: 'text', text: String(value) }] },
616
+ execute: async (args, exec) => run(args, exec),
617
+ });
618
+ const allEntries = () => {
619
+ const out = [];
620
+ for (const { server, conn } of lazyConns()) {
621
+ for (const [name, tool] of conn.lazy.tools) {
622
+ out.push({ server: server.id, name, rawName: tool.rawName, description: tool.description, loaded: conn.lazy.loaded.has(name), inputSchema: tool.inputSchema });
623
+ }
624
+ }
625
+ return out;
626
+ };
627
+ gatewayDisposers = [
628
+ registerTextTool(`${prefix}__find`, `Search indexed MCP tools by keyword or regex (case-insensitive, matches names and descriptions). Large catalogs stay out of the model's context: call this first, then ${prefix}__load with exact names to make tools directly callable. Omit query to list the indexed servers.`, {
629
+ type: 'object',
630
+ properties: {
631
+ query: { type: 'string', description: 'Keyword or regex to match against tool names and descriptions. Omit to list indexed servers.' },
632
+ server: { type: 'string', description: 'Restrict the search to one server id.' },
633
+ schema: { type: 'boolean', description: `Also print each match's JSON schema and parameter signature (a preview before loading).` },
634
+ },
635
+ required: [],
636
+ }, async (args) => {
637
+ const conns = lazyConns();
638
+ const serverFilter = typeof args.server === 'string' ? args.server : undefined;
639
+ const scoped = serverFilter !== undefined && serverFilter !== ''
640
+ ? conns.filter((c) => c.server.id === serverFilter)
641
+ : conns;
642
+ const query = typeof args.query === 'string' ? args.query : '';
643
+ if (query.trim() === '') {
644
+ return formatServerOverview(scoped.map(({ server, conn }) => ({
645
+ id: server.id, indexed: conn.lazy.tools.size, loaded: conn.lazy.loaded.size,
646
+ })));
647
+ }
648
+ const matches = searchTools(allEntries(), query, serverFilter);
649
+ // Schema mode caps tighter: each match carries a full JSON schema.
650
+ return args.schema === true ? formatMatchesDetailed(matches, 20) : formatMatches(matches, 50);
651
+ }),
652
+ registerTextTool(`${prefix}__load`, `Activate lazily-loaded MCP tools by exact public name (from ${prefix}__find). Loaded tools join the tool catalog for subsequent turns and stay loaded until unloaded or the server disconnects.`, {
653
+ type: 'object',
654
+ properties: {
655
+ names: { type: 'array', items: { type: 'string' }, description: 'Exact public tool names, e.g. mcp__rea__analyze_function.' },
656
+ },
657
+ required: ['names'],
658
+ }, async (args) => {
659
+ const names = Array.isArray(args.names) ? args.names.filter((n) => typeof n === 'string') : [];
660
+ if (names.length === 0)
661
+ return 'No names given. Call find first, then pass exact public names.';
662
+ // Connect-on-first-use: registration binds a live client, so wake
663
+ // every hibernating server before touching their catalogs.
664
+ try {
665
+ await wakeSleepy();
666
+ }
667
+ catch (err) {
668
+ return `wake failed — ${err instanceof Error ? err.message : String(err)}`;
669
+ }
670
+ const lines = [];
671
+ let active = 0;
672
+ for (const name of names) {
673
+ const owner = lazyConns().find(({ conn }) => conn.lazy.tools.has(name));
674
+ if (owner === undefined) {
675
+ lines.push(`${name}: unknown (not in any lazy index — run find)`);
676
+ continue;
677
+ }
678
+ if (owner.conn.lazy.loaded.has(name)) {
679
+ lines.push(`${name}: already loaded`);
680
+ active++;
681
+ continue;
682
+ }
683
+ const tool = owner.conn.lazy.tools.get(name);
684
+ try {
685
+ const dispose = registerOne(owner.server, owner.conn.client, tool);
686
+ owner.conn.lazy.loaded.set(name, dispose);
687
+ owner.conn.disposers = [...owner.conn.lazy.loaded.values()];
688
+ lines.push(`${name}: loaded`);
689
+ active++;
690
+ }
691
+ catch (err) {
692
+ lines.push(`${name}: failed — ${err instanceof Error ? err.message : String(err)}`);
693
+ }
694
+ }
695
+ lines.push(`${active}/${names.length} tools active — call them directly on your next turn.`);
696
+ return lines.join('\n');
697
+ }),
698
+ registerTextTool(`${prefix}__unload`, 'Deactivate previously loaded lazy MCP tools by exact public name.', {
699
+ type: 'object',
700
+ properties: {
701
+ names: { type: 'array', items: { type: 'string' }, description: 'Exact public tool names to unload.' },
702
+ },
703
+ required: ['names'],
704
+ }, async (args) => {
705
+ const names = Array.isArray(args.names) ? args.names.filter((n) => typeof n === 'string') : [];
706
+ if (names.length === 0)
707
+ return 'No names given.';
708
+ const lines = [];
709
+ for (const name of names) {
710
+ const owner = lazyConns().find(({ conn }) => conn.lazy.loaded.has(name) || conn.pendingLoaded?.has(name) === true);
711
+ if (owner === undefined) {
712
+ lines.push(`${name}: not loaded`);
713
+ continue;
714
+ }
715
+ if (owner.conn.hibernating) {
716
+ // Server parked: the tool only lives in pendingLoaded — retire
717
+ // the memory, no transport needed.
718
+ owner.conn.pendingLoaded?.delete(name);
719
+ lines.push(`${name}: unloaded (was pending while the server hibernates)`);
720
+ continue;
721
+ }
722
+ const dispose = owner.conn.lazy.loaded.get(name);
723
+ try {
724
+ dispose();
725
+ }
726
+ catch { /* already gone */ }
727
+ owner.conn.lazy.loaded.delete(name);
728
+ owner.conn.disposers = [...owner.conn.lazy.loaded.values()];
729
+ lines.push(`${name}: unloaded`);
730
+ }
731
+ return lines.join('\n');
732
+ }),
733
+ registerTextTool(`${prefix}__exec`, `Run ONE sandboxed JavaScript snippet against every lazily-indexed MCP tool. Use it for composed or bulk tasks (3+ dependent calls, loops, batch traversal); for 1-2 simple calls prefer ${prefix}__find + ${prefix}__load and call natively. Loop: ${prefix}__find to discover tools, ${prefix}__find {query, schema:true} to read a tool's parameter schema, then run code here. Inside the code: await SERVER.tool(args) or await mcp.call('server', 'toolName', args) — both dispatch the real MCP tool and return its text result; mcp.servers() lists indexed servers; tool names not yet seen resolve by exact name, and unknown names error with nearest matches. Emit results with console.log: intermediate values never leave the code, only the captured output (tail-preserved when capped) returns. No require/process/fetch; ~30s deadline.`, {
734
+ type: 'object',
735
+ properties: {
736
+ code: { type: 'string', description: "JavaScript (top-level await OK). Example: for (const q of queries) console.log(q, await rea.searxng_web_search({ query: q }))" },
737
+ },
738
+ required: ['code'],
739
+ }, async (args, exec) => {
740
+ const code = typeof args.code === 'string' ? args.code : '';
741
+ if (code.trim() === '')
742
+ return 'No code given.';
743
+ // Connect-on-first-use: the sandbox dispatches over live transports.
744
+ try {
745
+ await wakeSleepy();
746
+ }
747
+ catch (err) {
748
+ return `exec failed — wake: ${err instanceof Error ? err.message : String(err)}`;
749
+ }
750
+ const targets = lazyConns().map(({ server, conn }) => ({
751
+ serverId: server.id,
752
+ client: (request, signal) => conn.client.callTool({ name: request.name, arguments: request.arguments }, undefined, { signal }),
753
+ index: conn.lazy.tools,
754
+ }));
755
+ try {
756
+ return await runCode(code, targets, { signal: exec.signal });
757
+ }
758
+ catch (err) {
759
+ return `exec failed — ${err instanceof Error ? err.message : String(err)}`;
760
+ }
761
+ }),
762
+ ];
763
+ ctx.logger?.info(`[mcp] gateway registered (${prefix}__find / ${prefix}__load / ${prefix}__unload / ${prefix}__exec)`);
764
+ };
362
765
  const onDisconnect = (id, reason) => {
363
766
  const conn = connections.get(id);
364
767
  if (!conn)
@@ -420,7 +823,9 @@ export function apply(ctx, config) {
420
823
  connections.set(server.id, conn);
421
824
  status.set(server.id, { ok: true });
422
825
  reconnectAttempts.delete(server.id);
423
- ctx.logger?.info(`[mcp] ${server.id}: registered ${conn.toolCount} tools`);
826
+ ctx.logger?.info(`[mcp] ${server.id}: ${conn.lazy
827
+ ? `indexed ${conn.toolCount} tools (large catalog — hibernating until first use)`
828
+ : `registered ${conn.toolCount} tools`}`);
424
829
  }
425
830
  catch (err) {
426
831
  status.set(server.id, { ok: false, error: shortErr(err) });
@@ -428,6 +833,9 @@ export function apply(ctx, config) {
428
833
  scheduleReconnect(server.id);
429
834
  }
430
835
  }));
836
+ // Adaptive laziness is decided per server at connect time, so the gateway
837
+ // syncs after the connect round completes (and on every re-sync).
838
+ syncGateway();
431
839
  };
432
840
  // Daily WebDAV backup at 12:00 PM local time; reschedules itself on each run.
433
841
  let dailyTimer = null;
@@ -435,7 +843,7 @@ export function apply(ctx, config) {
435
843
  const cfg = readConfig();
436
844
  if (!cfg.webdavUrl)
437
845
  return;
438
- const payload = JSON.stringify({ version: 1, servers: cfg.servers });
846
+ const payload = JSON.stringify({ version: 2, enabledTools: cfg.enabledTools ?? '', servers: cfg.servers });
439
847
  if (Buffer.byteLength(payload) > MAX_UPLOAD_BYTES) {
440
848
  ctx.logger?.warn('[mcp] daily backup too large, skipping');
441
849
  return;
@@ -487,16 +895,13 @@ export function apply(ctx, config) {
487
895
  kind: 'exact',
488
896
  path: '/mcp-servers/config',
489
897
  handler: (req, res) => {
490
- if (!isLoopback(req)) {
491
- sendJson(res, 403, { error: 'loopback only' });
492
- return;
493
- }
494
898
  if (req.method === 'GET') {
495
899
  const cfg = readConfig();
496
900
  // webdavPass is a secret — never sent to the browser.
497
901
  sendJson(res, 200, {
498
902
  servers: cfg.servers,
499
903
  status: Object.fromEntries(status),
904
+ enabledTools: cfg.enabledTools ?? '',
500
905
  webdavUrl: cfg.webdavUrl ?? '',
501
906
  webdavUser: cfg.webdavUser ?? '',
502
907
  webdavDaily: cfg.webdavDaily === true,
@@ -545,6 +950,13 @@ export function apply(ctx, config) {
545
950
  }
546
951
  patch.webdavDaily = body.webdavDaily;
547
952
  }
953
+ if ('enabledTools' in body) {
954
+ if (typeof body.enabledTools !== 'string') {
955
+ sendJson(res, 400, { error: 'enabledTools must be a string' });
956
+ return;
957
+ }
958
+ patch.enabledTools = body.enabledTools;
959
+ }
548
960
  if (Object.keys(patch).length === 0) {
549
961
  sendJson(res, 400, { error: 'empty update' });
550
962
  return;
@@ -559,10 +971,6 @@ export function apply(ctx, config) {
559
971
  kind: 'exact',
560
972
  path: '/mcp-servers/test',
561
973
  handler: (req, res) => {
562
- if (!isLoopback(req)) {
563
- sendJson(res, 403, { error: 'loopback only' });
564
- return;
565
- }
566
974
  if (req.method !== 'POST') {
567
975
  sendJson(res, 405, { error: 'method not allowed' });
568
976
  return;
@@ -601,10 +1009,6 @@ export function apply(ctx, config) {
601
1009
  kind: 'exact',
602
1010
  path: '/mcp-servers/webdav',
603
1011
  handler: (req, res) => {
604
- if (!isLoopback(req)) {
605
- sendJson(res, 403, { error: 'loopback only' });
606
- return;
607
- }
608
1012
  if (req.method !== 'POST') {
609
1013
  sendJson(res, 405, { error: 'method not allowed' });
610
1014
  return;
package/dist/lazy.d.ts ADDED
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Lazy tool loading: instead of registering every MCP tool up front (which
3
+ * ships hundreds of schemas into every model turn), a lazy server indexes its
4
+ * tools and exposes a small find/load gateway. These helpers are the pure,
5
+ * testable half — searching the index, formatting results, and the per-server
6
+ * name whitelist.
7
+ */
8
+ /** One indexed tool from a lazily-loaded MCP server, keyed by public name. */
9
+ export interface LazyTool {
10
+ rawName: string;
11
+ description: string;
12
+ inputSchema: unknown;
13
+ }
14
+ /** Compiled whitelist over raw tool names; `undefined` means "allow all". */
15
+ export type Whitelist = RegExp | {
16
+ error: string;
17
+ } | undefined;
18
+ export declare function compileWhitelist(pattern: string | undefined): Whitelist;
19
+ export declare function toolAllowed(whitelist: Whitelist, rawName: string): boolean;
20
+ export interface MatchEntry {
21
+ /** Owning server id. */
22
+ server: string;
23
+ /** Public tool name (`mcp__<serverId>__<tool>`), as load expects it. */
24
+ name: string;
25
+ rawName: string;
26
+ description: string;
27
+ loaded: boolean;
28
+ /** Present when the caller wants schema detail (find with schema=true). */
29
+ inputSchema?: unknown;
30
+ }
31
+ /**
32
+ * Search entries by a keyword or regex (case-insensitive, matched against the
33
+ * public name, raw name, and description). An invalid regex degrades to a
34
+ * literal substring match instead of failing the call. An empty query matches
35
+ * nothing — callers render the server overview in that case.
36
+ */
37
+ export declare function searchTools(entries: MatchEntry[], query: string, server?: string): MatchEntry[];
38
+ /** Collapse whitespace and hard-cap the length with an ellipsis. */
39
+ export declare function truncate(text: string, max: number): string;
40
+ /**
41
+ * One line per match, exact name first (it is the load argument), description
42
+ * truncated, `[loaded]` marker for tools already in the catalog.
43
+ */
44
+ export declare function formatMatches(matches: MatchEntry[], cap: number): string;
45
+ /** Empty-query response: one line per connected lazily-indexed server. */
46
+ export declare function formatServerOverview(servers: {
47
+ id: string;
48
+ indexed: number;
49
+ loaded: number;
50
+ }[]): string;
51
+ /** Compact parameter signature from a tool's inputSchema: `(a, b*, c)` — `*` marks required. */
52
+ export declare function formatParams(schema: unknown): string;
53
+ /**
54
+ * Like formatMatches, but each match also carries its parameter signature and
55
+ * full JSON schema (used by find with schema=true, to preview a tool before
56
+ * loading it).
57
+ */
58
+ export declare function formatMatchesDetailed(matches: MatchEntry[], cap: number): string;
package/dist/lazy.js ADDED
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Lazy tool loading: instead of registering every MCP tool up front (which
3
+ * ships hundreds of schemas into every model turn), a lazy server indexes its
4
+ * tools and exposes a small find/load gateway. These helpers are the pure,
5
+ * testable half — searching the index, formatting results, and the per-server
6
+ * name whitelist.
7
+ */
8
+ export function compileWhitelist(pattern) {
9
+ const trimmed = pattern?.trim() ?? '';
10
+ if (trimmed === '')
11
+ return undefined;
12
+ try {
13
+ return new RegExp(trimmed, 'i');
14
+ }
15
+ catch (err) {
16
+ return { error: err instanceof Error ? err.message : String(err) };
17
+ }
18
+ }
19
+ export function toolAllowed(whitelist, rawName) {
20
+ // A compile error object never allows anything to be filtered — callers are
21
+ // expected to have warned and fallen back to `undefined` (allow all).
22
+ return !(whitelist instanceof RegExp) || whitelist.test(rawName);
23
+ }
24
+ /**
25
+ * Search entries by a keyword or regex (case-insensitive, matched against the
26
+ * public name, raw name, and description). An invalid regex degrades to a
27
+ * literal substring match instead of failing the call. An empty query matches
28
+ * nothing — callers render the server overview in that case.
29
+ */
30
+ export function searchTools(entries, query, server) {
31
+ let pool = entries;
32
+ if (server !== undefined && server !== '')
33
+ pool = pool.filter((e) => e.server === server);
34
+ const q = query.trim();
35
+ if (q === '')
36
+ return [];
37
+ let re;
38
+ try {
39
+ re = new RegExp(q, 'i');
40
+ }
41
+ catch {
42
+ const needle = q.toLowerCase();
43
+ return pool.filter((e) => `${e.name} ${e.description}`.toLowerCase().includes(needle));
44
+ }
45
+ return pool.filter((e) => re.test(e.name) || re.test(e.rawName) || re.test(e.description));
46
+ }
47
+ /** Collapse whitespace and hard-cap the length with an ellipsis. */
48
+ export function truncate(text, max) {
49
+ const one = text.replace(/\s+/g, ' ').trim();
50
+ return one.length <= max ? one : one.slice(0, Math.max(1, max - 1)) + '…';
51
+ }
52
+ /**
53
+ * One line per match, exact name first (it is the load argument), description
54
+ * truncated, `[loaded]` marker for tools already in the catalog.
55
+ */
56
+ export function formatMatches(matches, cap) {
57
+ if (matches.length === 0)
58
+ return 'No matching tools. Call find without a query to list the indexed servers.';
59
+ const shown = matches.slice(0, cap);
60
+ const lines = shown.map((m) => `${m.name} — ${truncate(m.description || '(no description)', 120)}${m.loaded ? ' [loaded]' : ''}`);
61
+ if (matches.length > cap) {
62
+ lines.push(`(${matches.length - cap} more — narrow the query or pass the server parameter)`);
63
+ }
64
+ return lines.join('\n');
65
+ }
66
+ /** Empty-query response: one line per connected lazily-indexed server. */
67
+ export function formatServerOverview(servers) {
68
+ if (servers.length === 0) {
69
+ return 'No indexed MCP servers are connected. Catalogs above six tools index here automatically; check the server status in the MCP Servers settings.';
70
+ }
71
+ return servers
72
+ .map((s) => `${s.id}: ${s.indexed} tools indexed, ${s.loaded} loaded — call find with {"query":"…"} or {"server":"${s.id}"}`)
73
+ .join('\n');
74
+ }
75
+ /** Compact parameter signature from a tool's inputSchema: `(a, b*, c)` — `*` marks required. */
76
+ export function formatParams(schema) {
77
+ if (!schema || typeof schema !== 'object')
78
+ return '()';
79
+ const node = schema;
80
+ if (!node.properties || typeof node.properties !== 'object')
81
+ return '()';
82
+ const names = Object.keys(node.properties);
83
+ if (names.length === 0)
84
+ return '()';
85
+ const req = Array.isArray(node.required) ? node.required.filter((r) => typeof r === 'string') : [];
86
+ return `(${names.map((n) => `${n}${req.includes(n) ? '*' : ''}`).join(', ')})`;
87
+ }
88
+ /**
89
+ * Like formatMatches, but each match also carries its parameter signature and
90
+ * full JSON schema (used by find with schema=true, to preview a tool before
91
+ * loading it).
92
+ */
93
+ export function formatMatchesDetailed(matches, cap) {
94
+ if (matches.length === 0)
95
+ return 'No matching tools. Call find without a query to list the indexed servers.';
96
+ const shown = matches.slice(0, cap);
97
+ const lines = [];
98
+ for (const m of shown) {
99
+ lines.push(`${m.name} — ${truncate(m.description || '(no description)', 120)} ${formatParams(m.inputSchema)}${m.loaded ? ' [loaded]' : ''}`);
100
+ if (m.inputSchema !== undefined && m.inputSchema !== null)
101
+ lines.push(` ${JSON.stringify(m.inputSchema)}`);
102
+ }
103
+ if (matches.length > cap) {
104
+ lines.push(`(${matches.length - cap} more — narrow the query or pass the server parameter)`);
105
+ }
106
+ lines.push('(* marks required parameters)');
107
+ return lines.join('\n');
108
+ }
@@ -1 +1,9 @@
1
+ /**
2
+ * MCP input schemas are JSON Schema draft 2020-12; the Harness tool registry
3
+ * enforces a narrower subset (see the `JsonSchemaNode` reference). This
4
+ * whitelist-strips every node down to the supported keys so registration
5
+ * never rejects a schema the MCP server only annotated.
6
+ */
7
+ /** Whitelist of JSON Schema keywords the Harness tool registry supports. */
8
+ export declare const SUPPORTED_KEYS: Set<string>;
1
9
  export declare function sanitizeSchema(schema: unknown): unknown;
package/dist/sanitize.js CHANGED
@@ -4,7 +4,8 @@
4
4
  * whitelist-strips every node down to the supported keys so registration
5
5
  * never rejects a schema the MCP server only annotated.
6
6
  */
7
- const SUPPORTED_KEYS = new Set([
7
+ /** Whitelist of JSON Schema keywords the Harness tool registry supports. */
8
+ export const SUPPORTED_KEYS = new Set([
8
9
  'type', 'oneOf', 'properties', 'required', 'additionalProperties',
9
10
  'items', 'enum', 'const', 'description', 'title', 'default', 'examples',
10
11
  ]);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-mcp-servers",
3
- "version": "1.260930.4",
3
+ "version": "1.261121.3",
4
4
  "description": "DeepSeek Harness bundle that exposes Model Context Protocol (MCP) servers — stdio, streamable HTTP and legacy SSE — as native Harness tools, with a settings UI, live status, auto-reconnect, and backup/restore via local files or WebDAV.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -24,7 +24,7 @@
24
24
  "build": "npm run version && tsc -p tsconfig.json && tsdown",
25
25
  "prepack": "npm run build",
26
26
  "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
27
- "check": "npm run typecheck && tsx test/sanitize.test.ts && tsx test/naming.test.ts && tsx test/settings-api.test.ts",
27
+ "check": "npm run typecheck && tsx test/sanitize.test.ts && tsx test/naming.test.ts && tsx test/lazy.test.ts && tsx test/codemode.test.ts && tsx test/settings-api.test.ts",
28
28
  "pack": "npm pack",
29
29
  "publish:npm": "npm publish"
30
30
  },