@jini-ai/mcp 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @jini-ai/mcp
 
+## 0.4.4 — 2026-10-22
+
+- 2026-10-22: Typed tools from the launched bridge, concrete describe schemas, list-changed, diagnostic error codes, coverage.
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -58,6 +58,7 @@ engine nor retries a challenged request automatically.
 returning a discriminated `InstallPlan` (`CliInstallPlan` | `JsonInstallPlan` | `ManualInstallPlan`),
 and `applyJsonInstall` / `removeJsonInstall` to execute the JSON-file variant. Plus
 `buildMcpInstallPayload` for the install-info payload a UI renders.
+For an explicit UI check, pass `CHROME_DEVTOOLS_MCP_PRESET` to `planAgentInstall` with `ctx.serverName: "chrome-devtools"`; it pins 1.10.1 and disables usage statistics and CrUX. See the [on-demand recipe](../diagnostics/docs/ui-performance-check.md).
 
 **Client-side runtime helpers** — `extractRelativeRefs`, `isTextualMime`.
 

package/dist/agent-install/chrome-devtools.d.ts

@@ -0,0 +1,4 @@
+import type { McpLaunchSpec } from './install.js';
+/** Explicit on-demand launch preset; importing it never registers or launches a browser. */
+export declare const CHROME_DEVTOOLS_MCP_PRESET: McpLaunchSpec;
+//# sourceMappingURL=chrome-devtools.d.ts.map

package/dist/agent-install/chrome-devtools.js

@@ -0,0 +1,7 @@
+/** Explicit on-demand launch preset; importing it never registers or launches a browser. */
+export const CHROME_DEVTOOLS_MCP_PRESET = {
+    command: 'npx',
+    args: ['-y', 'chrome-devtools-mcp@1.10.1', '--no-usage-statistics', '--no-performance-crux'],
+    env: {},
+};
+//# sourceMappingURL=chrome-devtools.js.map

package/dist/agent-install/index.d.ts

@@ -6,4 +6,5 @@
  * apply/remove primitives. Pure planning logic; no sibling MCP imports.
  */
 export * from './install.js';
+export { CHROME_DEVTOOLS_MCP_PRESET } from './chrome-devtools.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/agent-install/index.js

@@ -6,4 +6,5 @@
  * apply/remove primitives. Pure planning logic; no sibling MCP imports.
  */
 export * from './install.js';
+export { CHROME_DEVTOOLS_MCP_PRESET } from './chrome-devtools.js';
 //# sourceMappingURL=index.js.map

package/dist/agent-install/install.js

@@ -84,205 +84,122 @@ function envFlags(env, flag) {
     }
     return out;
 }
+// Attaches the env map under `key` only when non-empty, so configs stay clean.
+function withEnv(entry, env, key) {
+    if (Object.keys(env).length > 0)
+        entry[key] = env;
+    return entry;
+}
 /** JSON server entry shared by the `env`-style agents (cursor / copilot /
  *  cline / openclaw / antigravity / trae). `extra` carries per-agent
  *  fields; env is only attached when non-empty so configs stay clean. */
-function jsonEntry(spec, extra = {}, envKey = 'env') {
-    const entry = {
-        command: spec.command,
-        args: spec.args,
-        ...extra,
-    };
-    if (Object.keys(spec.env).length > 0) {
-        entry[envKey] = spec.env;
-    }
-    return entry;
+function jsonEntry(spec, extra = {}) {
+    return withEnv({ command: spec.command, args: spec.args, ...extra }, spec.env, 'env');
+}
+function cliPlan(slug, bin, argv, serverName) {
+    return { kind: 'cli', slug, bin, ...argv, getArgv: ['mcp', 'get', serverName] };
+}
+function jsonPlan(slug, configPath, keyPath, serverKey, entry) {
+    return { kind: 'json', slug, configPath, keyPath, serverKey, entry };
 }
+// One planner per slug. Typed as a total map over `AgentSlug`, so adding a slug
+// without a planner is a compile error (the role the old switch's `never` default played).
+const AGENT_PLANNERS = {
+    // ----- CLI-driven agents (idempotent via the agent's own tool) -----
+    claude: ({ spec, ctx: { serverName } }) => cliPlan('claude', 'claude', {
+        addArgv: [
+            'mcp', 'add', '--scope', 'user',
+            serverName,
+            ...envFlags(spec.env, '-e'),
+            '--', spec.command, ...spec.args,
+        ],
+        removeArgv: ['mcp', 'remove', '--scope', 'user', serverName],
+    }, serverName),
+    codex: ({ spec, ctx: { serverName } }) => cliPlan('codex', 'codex', {
+        addArgv: [
+            'mcp', 'add', serverName,
+            ...envFlags(spec.env, '--env'),
+            '--', spec.command, ...spec.args,
+        ],
+        removeArgv: ['mcp', 'remove', serverName],
+    }, serverName),
+    kimi: ({ spec, ctx: { serverName } }) => cliPlan('kimi', 'kimi', {
+        addArgv: [
+            'mcp', 'add', '--transport', 'stdio',
+            ...envFlags(spec.env, '--env'),
+            serverName, '--', spec.command, ...spec.args,
+        ],
+        removeArgv: ['mcp', 'remove', serverName],
+    }, serverName),
+    // ----- JSON config-file agents (safe deep-merge) -----
+    cursor: ({ spec, ctx: { home, serverName } }) => jsonPlan('cursor', path.join(home, '.cursor', 'mcp.json'), ['mcpServers'], serverName, jsonEntry(spec, { type: 'stdio' })),
+    // GitHub Copilot CLI: ~/.copilot/mcp-config.json, type "local".
+    // (VS Code Copilot uses a different `servers` key in
+    // .vscode/mcp.json; the terminal installer targets the CLI.)
+    copilot: ({ spec, ctx: { home, serverName } }) => jsonPlan('copilot', path.join(home, '.copilot', 'mcp-config.json'), ['mcpServers'], serverName, jsonEntry(spec, { type: 'local', tools: ['*'] })),
+    cline: ({ spec, ctx: { home, platform, serverName }, appData }) => jsonPlan('cline', clineConfigPath(home, platform, appData), ['mcpServers'], serverName, jsonEntry(spec, { disabled: false, autoApprove: [] })),
+    // OpenCode nests under `mcp`, folds command+args into one array,
+    // and gates the server with `enabled`.
+    opencode: ({ spec, ctx: { home, serverName } }) => jsonPlan('opencode', path.join(home, '.config', 'opencode', 'opencode.json'), ['mcp'], serverName, withEnv({ type: 'local', command: [spec.command, ...spec.args], enabled: true }, spec.env, 'environment')),
+    openclaw: ({ spec, ctx: { home, serverName } }) => jsonPlan('openclaw', path.join(home, '.openclaw', 'openclaw.json'), ['mcp', 'servers'], serverName, jsonEntry(spec)),
+    antigravity: ({ spec, ctx: { home, serverName } }) => jsonPlan('antigravity', path.join(home, '.gemini', 'antigravity', 'mcp_config.json'), ['mcpServers'], serverName, jsonEntry(spec)),
+    trae: ({ spec, ctx: { home, platform, serverName }, appData }) => jsonPlan('trae', traeConfigPath(home, platform, appData), ['mcpServers'], serverName, jsonEntry(spec)),
+    // ----- Unverified formats: print-only, never write -----
+    vibe: ({ spec, ctx: { home, serverName } }) => ({
+        kind: 'manual',
+        slug: 'vibe',
+        format: 'toml',
+        configPath: path.join(home, '.vibe', 'config.toml'),
+        snippet: vibeTomlSnippet(spec, serverName),
+        reason: 'Vibe uses a TOML array-of-tables ([[mcp_servers]]); ' +
+            'its exact schema is unverified, so append this block by hand ' +
+            'to avoid corrupting an existing config.',
+    }),
+    pi: ({ spec, ctx: { home, serverName } }) => ({
+        kind: 'manual',
+        slug: 'pi',
+        format: 'json',
+        configPath: path.join(home, '.pi', 'agent', 'mcp.json'),
+        snippet: JSON.stringify({ mcpServers: { [serverName]: jsonEntry(spec) } }, null, 2),
+        reason: 'The pi coding agent exposes MCP, but its config path/schema is ' +
+            'not authoritatively documented. Paste this into pi’s MCP ' +
+            'config (check `pi --help` for the exact location).',
+    }),
+    hermes: ({ spec, ctx: { home, serverName } }) => ({
+        kind: 'manual',
+        slug: 'hermes',
+        format: 'yaml',
+        configPath: path.join(home, '.hermes', 'config.yaml'),
+        snippet: hermesYamlSnippet(spec, serverName),
+        reason: 'Hermes config format is unverified. Add this under your Hermes ' +
+            'MCP server configuration by hand.',
+    }),
+};
 /**
  * Build the registration plan for one agent. Pure — all IO happens in the
  * executor. Throws on an unknown slug so callers surface a clear error.
  */
 export function planAgentInstall({ slug, spec, ctx }, { env = process.env } = {}) {
-    const { home, platform, serverName } = ctx;
-    switch (slug) {
-        // ----- CLI-driven agents (idempotent via the agent's own tool) -----
-        case 'claude':
-            return {
-                kind: 'cli',
-                slug,
-                bin: 'claude',
-                addArgv: [
-                    'mcp', 'add', '--scope', 'user',
-                    serverName,
-                    ...envFlags(spec.env, '-e'),
-                    '--', spec.command, ...spec.args,
-                ],
-                removeArgv: ['mcp', 'remove', '--scope', 'user', serverName],
-                getArgv: ['mcp', 'get', serverName],
-            };
-        case 'codex':
-            return {
-                kind: 'cli',
-                slug,
-                bin: 'codex',
-                addArgv: [
-                    'mcp', 'add', serverName,
-                    ...envFlags(spec.env, '--env'),
-                    '--', spec.command, ...spec.args,
-                ],
-                removeArgv: ['mcp', 'remove', serverName],
-                getArgv: ['mcp', 'get', serverName],
-            };
-        case 'kimi':
-            return {
-                kind: 'cli',
-                slug,
-                bin: 'kimi',
-                addArgv: [
-                    'mcp', 'add', '--transport', 'stdio',
-                    ...envFlags(spec.env, '--env'),
-                    serverName, '--', spec.command, ...spec.args,
-                ],
-                removeArgv: ['mcp', 'remove', serverName],
-                getArgv: ['mcp', 'get', serverName],
-            };
-        // ----- JSON config-file agents (safe deep-merge) -----
-        case 'cursor':
-            return {
-                kind: 'json',
-                slug,
-                configPath: path.join(home, '.cursor', 'mcp.json'),
-                keyPath: ['mcpServers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec, { type: 'stdio' }),
-            };
-        case 'copilot':
-            // GitHub Copilot CLI: ~/.copilot/mcp-config.json, type "local".
-            // (VS Code Copilot uses a different `servers` key in
-            // .vscode/mcp.json; the terminal installer targets the CLI.)
-            return {
-                kind: 'json',
-                slug,
-                configPath: path.join(home, '.copilot', 'mcp-config.json'),
-                keyPath: ['mcpServers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec, { type: 'local', tools: ['*'] }),
-            };
-        case 'cline':
-            return {
-                kind: 'json',
-                slug,
-                configPath: clineConfigPath(home, platform, env.APPDATA),
-                keyPath: ['mcpServers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec, { disabled: false, autoApprove: [] }),
-            };
-        case 'opencode':
-            // OpenCode nests under `mcp`, folds command+args into one array,
-            // and gates the server with `enabled`.
-            return {
-                kind: 'json',
-                slug,
-                configPath: path.join(home, '.config', 'opencode', 'opencode.json'),
-                keyPath: ['mcp'],
-                serverKey: serverName,
-                entry: (() => {
-                    const e = {
-                        type: 'local',
-                        command: [spec.command, ...spec.args],
-                        enabled: true,
-                    };
-                    if (Object.keys(spec.env).length > 0)
-                        e.environment = spec.env;
-                    return e;
-                })(),
-            };
-        case 'openclaw':
-            return {
-                kind: 'json',
-                slug,
-                configPath: path.join(home, '.openclaw', 'openclaw.json'),
-                keyPath: ['mcp', 'servers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec),
-            };
-        case 'antigravity':
-            return {
-                kind: 'json',
-                slug,
-                configPath: path.join(home, '.gemini', 'antigravity', 'mcp_config.json'),
-                keyPath: ['mcpServers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec),
-            };
-        case 'trae':
-            return {
-                kind: 'json',
-                slug,
-                configPath: traeConfigPath(home, platform, env.APPDATA),
-                keyPath: ['mcpServers'],
-                serverKey: serverName,
-                entry: jsonEntry(spec),
-            };
-        // ----- Unverified formats: print-only, never write -----
-        case 'vibe':
-            return {
-                kind: 'manual',
-                slug,
-                format: 'toml',
-                configPath: path.join(home, '.vibe', 'config.toml'),
-                snippet: vibeTomlSnippet(spec, serverName),
-                reason: 'Vibe uses a TOML array-of-tables ([[mcp_servers]]); ' +
-                    'its exact schema is unverified, so append this block by hand ' +
-                    'to avoid corrupting an existing config.',
-            };
-        case 'pi':
-            return {
-                kind: 'manual',
-                slug,
-                format: 'json',
-                configPath: path.join(home, '.pi', 'agent', 'mcp.json'),
-                snippet: genericMcpServersSnippet(spec, serverName),
-                reason: 'The pi coding agent exposes MCP, but its config path/schema is ' +
-                    'not authoritatively documented. Paste this into pi’s MCP ' +
-                    'config (check `pi --help` for the exact location).',
-            };
-        case 'hermes':
-            return {
-                kind: 'manual',
-                slug,
-                format: 'yaml',
-                configPath: path.join(home, '.hermes', 'config.yaml'),
-                snippet: hermesYamlSnippet(spec, serverName),
-                reason: 'Hermes config format is unverified. Add this under your Hermes ' +
-                    'MCP server configuration by hand.',
-            };
-        default: {
-            const exhaustive = slug;
-            throw new Error(`unknown agent slug: ${String(exhaustive)}`);
-        }
+    // Own-property lookup only: a slug such as `constructor` or `__proto__` must not
+    // resolve to an inherited Object.prototype member and be called as a planner.
+    if (!Object.prototype.hasOwnProperty.call(AGENT_PLANNERS, slug)) {
+        throw new Error(`unknown agent slug: ${String(slug)}`);
     }
+    return AGENT_PLANNERS[slug]({ spec, ctx, appData: env.APPDATA });
+}
+// VS Code-family editors keep per-user state under one platform-specific root.
+function editorUserDir(app, home, platform, suppliedAppData) {
+    if (platform === 'darwin')
+        return path.join(home, 'Library', 'Application Support', app, 'User');
+    if (platform === 'win32')
+        return path.join(suppliedAppData ?? path.join(home, 'AppData', 'Roaming'), app, 'User');
+    return path.join(home, '.config', app, 'User');
 }
 function clineConfigPath(home, platform, suppliedAppData) {
-    const rel = path.join('globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
-    if (platform === 'darwin') {
-        return path.join(home, 'Library', 'Application Support', 'Code', 'User', rel);
-    }
-    if (platform === 'win32') {
-        const appData = suppliedAppData ?? path.join(home, 'AppData', 'Roaming');
-        return path.join(appData, 'Code', 'User', rel);
-    }
-    return path.join(home, '.config', 'Code', 'User', rel);
+    return path.join(editorUserDir('Code', home, platform, suppliedAppData), 'globalStorage', 'saoudrizwan.claude-dev', 'settings', 'cline_mcp_settings.json');
 }
 function traeConfigPath(home, platform, suppliedAppData) {
-    if (platform === 'darwin') {
-        return path.join(home, 'Library', 'Application Support', 'Trae', 'User', 'mcp.json');
-    }
-    if (platform === 'win32') {
-        const appData = suppliedAppData ?? path.join(home, 'AppData', 'Roaming');
-        return path.join(appData, 'Trae', 'User', 'mcp.json');
-    }
-    return path.join(home, '.config', 'Trae', 'User', 'mcp.json');
+    return path.join(editorUserDir('Trae', home, platform, suppliedAppData), 'mcp.json');
 }
 // --- Pure JSON merge / removal (the heart of the 'json' strategy) -------
 // CR-007: `JsonInstallPlan` is a public shape and `applyJsonInstall` /
@@ -372,15 +289,6 @@ function parseJsonObject(text, where) {
     return parsed;
 }
 // --- Snippets for the manual (print-only) strategy ----------------------
-function genericMcpServersSnippet(spec, name) {
-    const server = {
-        command: spec.command,
-        args: spec.args,
-    };
-    if (Object.keys(spec.env).length > 0)
-        server.env = spec.env;
-    return JSON.stringify({ mcpServers: { [name]: server } }, null, 2);
-}
 function hermesYamlSnippet(spec, name) {
     const lines = [
         'mcp_servers:',

package/dist/bin/serve.d.ts

@@ -67,6 +67,8 @@ export declare const DAEMON_TOKEN_ENV_VAR = "JINI_DAEMON_TOKEN";
  * policy that would make a given number correct, so it must not refuse to boot over one.
  */
 export declare const DELEGATED_TOOL_TIMEOUT_ENV_VAR = "JINI_DELEGATED_TOOL_TIMEOUT_MS";
+/** JSON array of host-selected visible registry IDs; never sourced from diagnostic IDs. */
+export declare const STARTUP_TOOL_IDS_ENV_VAR = "JINI_STARTUP_TOOL_IDS";
 export interface ServeDeps {
     /** @default process.env */
     readonly env?: NodeJS.ProcessEnv;
@@ -105,7 +107,8 @@ export interface McpDaemonUrlOptions {
  * has no meaningful default run to serve) plus `DAEMON_URL_ENV_VAR` resolution, then hosts
  * `RUN_TOOLS` (run-agnostic) alongside a fresh `execute_delegated_tool` def scoped to the resolved
  * `runId`, and `KERNEL_RESOURCES`. Resolves once the client disconnects (stdin EOF) or the
- * idle-exit window elapses (`createMcpToolServer`'s own default) — never bare-throws: every error
+ * idle-exit window elapses (`createMcpToolServer`'s own default). Enables describe publication and
+ * resolves startup descriptors before connecting stdio. Never bare-throws: every error
  * path below writes a message to `writeErr` and calls `exit(1)` instead.
  */
 export declare function serve(_requiredArgs: Record<string, never>, deps?: ServeDeps): Promise<void>;

package/dist/bin/serve.js

@@ -3,10 +3,11 @@ import { fileURLToPath } from 'node:url';
 import { isLoopbackHostname } from '@jini-ai/platform/net';
 import { createMcpToolServer as createMcpToolServerDefault } from '../server/tool-server.js';
 import { RUN_TOOLS } from '../server/tools/run-tools.js';
-import { TOOL_CATALOG_TOOLS } from '../server/tools/tool-catalog-tools.js';
+import { describeToolTool, TOOL_CATALOG_TOOLS } from '../server/tools/tool-catalog-tools.js';
 import { COMPONENT_CATALOG_TOOLS } from '../server/tools/component-catalog-tools.js';
 import { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool } from '../server/tools/delegated-tool.js';
 import { KERNEL_RESOURCES } from '../server/resources/active-resource.js';
+import { createSiteGuideResource } from '../server/resources/site-guide-resource.js';
 /** The one run this process is scoped to for its entire lifetime. Set by the spawning daemon, never by the MCP client. */
 export const RUN_ID_ENV_VAR = 'JINI_RUN_ID';
 /** Checked (only) when resolving the daemon HTTP base URL — see `resolveDaemonUrl`'s own docs; matches the CLI entry point's identically-named constant. */
@@ -36,18 +37,26 @@ export const DAEMON_TOKEN_ENV_VAR = 'JINI_DAEMON_TOKEN';
  * policy that would make a given number correct, so it must not refuse to boot over one.
  */
 export const DELEGATED_TOOL_TIMEOUT_ENV_VAR = 'JINI_DELEGATED_TOOL_TIMEOUT_MS';
+/** JSON array of host-selected visible registry IDs; never sourced from diagnostic IDs. */
+export const STARTUP_TOOL_IDS_ENV_VAR = 'JINI_STARTUP_TOOL_IDS';
 const SERVER_NAME = 'jini-mcp';
 const SERVER_VERSION = '0.0.0';
 const INSTRUCTIONS = 'Tools proxying this host\'s Jini daemon over loopback HTTP, scoped to the run that spawned this MCP server process. ' +
     'Use execute_delegated_tool to invoke a Jini-registered tool (never an agent-vendor-specific tool name) against that run — ' +
-    'every call is routed through the daemon\'s deny-by-default ToolExecutor gate.';
+    'every call is routed through the daemon\'s deny-by-default ToolExecutor gate. ' +
+    'Concrete operation tools accept their own arguments directly. describe_tool publishes a concrete definition; ' +
+    'refresh tools/list when supported, or use the delegated gateways as the compatibility fallback. ' +
+    'When the host provides site_guide, consult jini://site-guide or call site_guide with operation overview ' +
+    'through execute_readonly_delegated_tool; follow with explain for the relevant topic ids. ' +
+    'If the host does not provide site_guide, report that availability gap.';
 // Keep the bin's environment-only assembly here; a general CLI resolver would introduce a
 // runtime dependency on another shell. No discovery/default URL is selected for a run child.
 async function resolveDaemonUrlDefault(_required, options) {
     const url = options.env[options.envVarName];
-    if (!url)
-        throw new Error('no daemon URL resolved: pass flagUrl, set envVarName on a populated env var, ' +
-            'supply a discover() probe, or provide defaultUrl.');
+    if (!url) {
+        throw new Error(`no daemon URL resolved: ${options.envVarName} is unset or empty; ` +
+            'the spawning Jini daemon must set it to its HTTP base URL.');
+    }
     let parsed;
     try {
         parsed = new URL(url);
@@ -56,16 +65,18 @@ async function resolveDaemonUrlDefault(_required, options) {
         return url;
     }
     if (parsed.protocol !== 'https:' && !isLoopbackHostname({ hostname: parsed.hostname })) {
-        let display = url;
-        if (parsed.username || parsed.password) {
-            parsed.username = '';
-            parsed.password = '';
-            display = parsed.toString();
-        }
-        options.warn({ message: `daemon URL ${display} is neither loopback nor HTTPS; traffic to a remote, non-HTTPS daemon is not encrypted.` });
+        options.warn({ message: `daemon URL ${redactUserinfo(url, parsed)} is neither loopback nor HTTPS; traffic to a remote, non-HTTPS daemon is not encrypted.` });
     }
     return url;
 }
+// Keeps credentials out of the warning; a URL without userinfo is shown exactly as given.
+function redactUserinfo(url, parsed) {
+    if (!parsed.username && !parsed.password)
+        return url;
+    parsed.username = '';
+    parsed.password = '';
+    return parsed.toString();
+}
 function defaultWriteErr({ text }) {
     process.stderr.write(text);
 }
@@ -74,35 +85,76 @@ function defaultWriteErr({ text }) {
  * has no meaningful default run to serve) plus `DAEMON_URL_ENV_VAR` resolution, then hosts
  * `RUN_TOOLS` (run-agnostic) alongside a fresh `execute_delegated_tool` def scoped to the resolved
  * `runId`, and `KERNEL_RESOURCES`. Resolves once the client disconnects (stdin EOF) or the
- * idle-exit window elapses (`createMcpToolServer`'s own default) — never bare-throws: every error
+ * idle-exit window elapses (`createMcpToolServer`'s own default). Enables describe publication and
+ * resolves startup descriptors before connecting stdio. Never bare-throws: every error
  * path below writes a message to `writeErr` and calls `exit(1)` instead.
  */
 export async function serve(_requiredArgs, deps = {}) {
-    const env = deps.env ?? process.env;
-    const writeErr = deps.writeErr ?? defaultWriteErr;
-    const exit = deps.exit ?? (({ code }) => process.exit(code));
-    const resolveDaemonUrlFn = deps.resolveDaemonUrl ?? resolveDaemonUrlDefault;
-    const createMcpToolServerFn = deps.createMcpToolServer ?? createMcpToolServerDefault;
+    const { env, writeErr, exit, resolveDaemonUrlFn, createMcpToolServerFn } = withProcessDefaults(deps);
     const runId = env[RUN_ID_ENV_VAR];
     if (typeof runId !== 'string' || runId.length === 0) {
         writeErr({ text: `${SERVER_NAME}: missing required ${RUN_ID_ENV_VAR} environment variable (this process must be spawned by a Jini daemon, which sets it)\n` });
         return exit({ code: 1 });
     }
+    let baseUrlResolution;
     const resolveBaseUrl = () => {
         const options = { flagUrl: null, env, envVarName: DAEMON_URL_ENV_VAR, warn: ({ message }) => writeErr({ text: message }) };
-        return resolveDaemonUrlFn({}, options);
+        // Startup discovery and subsequent execution must use the same resolved daemon.
+        return baseUrlResolution ??= resolveDaemonUrlFn({}, options);
+    };
+    const delegatedGatewayOptions = buildDelegatedGatewayOptions({ env }, deps);
+    const requiredArgs = {
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        tools: buildTools({ runId, delegatedGatewayOptions }),
+        resolveBaseUrl,
+    };
+    const serverOptions = buildServerOptions({ env, runId, delegatedGatewayOptions }, deps);
+    try {
+        const diagnosticToolIds = parseLaunchToolIds({ env, key: 'JINI_DIAGNOSTIC_TOOL_IDS' });
+        if (diagnosticToolIds.length)
+            Object.assign(serverOptions, { diagnosticToolIds });
+        const initialTools = await resolveStartupTools({
+            toolIds: parseLaunchToolIds({ env, key: STARTUP_TOOL_IDS_ENV_VAR }), resolveBaseUrl, serverOptions,
+        });
+        Object.assign(serverOptions, { delegatedTools: { runId, ...delegatedGatewayOptions, initialTools } });
+        await createMcpToolServerFn(requiredArgs, serverOptions).run({});
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeErr({ text: `${SERVER_NAME}: ${message}\n` });
+        return exit({ code: 1 });
+    }
+}
+// The process-bound fallbacks for every injectable seam `serve()` itself calls.
+function withProcessDefaults(deps) {
+    return {
+        env: deps.env ?? process.env,
+        writeErr: deps.writeErr ?? defaultWriteErr,
+        exit: deps.exit ?? (({ code }) => process.exit(code)),
+        resolveDaemonUrlFn: deps.resolveDaemonUrl ?? resolveDaemonUrlDefault,
+        createMcpToolServerFn: deps.createMcpToolServer ?? createMcpToolServerDefault,
     };
-    // Shared by both gateways so their run scope, correlation-id source, and deadline cannot diverge
-    // — the only difference between the two defs is the read-only constraint each declares.
-    const delegatedGatewayOptions = {
-        ...(deps.generateToolUseId !== undefined ? { generateToolUseId: deps.generateToolUseId } : {}),
+}
+// Drops `undefined` values so an absent dependency leaves no key at all — required under
+// `exactOptionalPropertyTypes`, and it keeps built option objects byte-identical to the
+// pre-injection shape when nothing is overridden.
+function definedOnly(entries) {
+    return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+}
+// Shared by both gateways so their run scope, correlation-id source, and deadline cannot diverge
+// — the only difference between the two defs is the read-only constraint each declares.
+function buildDelegatedGatewayOptions({ env }, deps) {
+    const rawTimeout = env[DELEGATED_TOOL_TIMEOUT_ENV_VAR];
+    return definedOnly({
+        generateToolUseId: deps.generateToolUseId,
         // Parsed, not validated: `createExecuteDelegatedToolTool` already rejects a non-finite or
         // non-positive value back to the default, so `NaN` from a malformed env var lands there too.
-        ...(env[DELEGATED_TOOL_TIMEOUT_ENV_VAR] !== undefined
-            ? { delegatedToolTimeoutMs: Number(env[DELEGATED_TOOL_TIMEOUT_ENV_VAR]) }
-            : {}),
-    };
-    const tools = [
+        delegatedToolTimeoutMs: rawTimeout === undefined ? undefined : Number(rawTimeout),
+    });
+}
+function buildTools({ runId, delegatedGatewayOptions }) {
+    return [
         ...RUN_TOOLS,
         ...TOOL_CATALOG_TOOLS,
         ...COMPONENT_CATALOG_TOOLS,
@@ -112,29 +164,52 @@ export async function serve(_requiredArgs, deps = {}) {
         // sees both and picks by what its call actually does.
         createExecuteReadonlyDelegatedToolTool({ runId }, delegatedGatewayOptions),
     ];
+}
+function buildServerOptions({ env, runId, delegatedGatewayOptions }, deps) {
     // Absent credential => no `authHeaders` at all => byte-identical request headers to before this
     // env var existed. See DAEMON_TOKEN_ENV_VAR's doc for why an unset value is not a startup failure.
     const credential = env[DAEMON_TOKEN_ENV_VAR];
-    const authHeaders = typeof credential === 'string' && credential.length > 0
-        ? { Authorization: `Bearer ${credential}` }
-        : undefined;
-    const requiredArgs = { name: SERVER_NAME, version: SERVER_VERSION, tools, resolveBaseUrl };
-    const serverOptions = {
-        resources: KERNEL_RESOURCES,
+    return {
+        resources: [...KERNEL_RESOURCES, createSiteGuideResource({ runId }, delegatedGatewayOptions)],
         instructions: INSTRUCTIONS,
-        ...(authHeaders !== undefined ? { authHeaders } : {}),
-        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
-        ...(deps.stdin !== undefined ? { stdin: deps.stdin } : {}),
-        ...(deps.stdout !== undefined ? { stdout: deps.stdout } : {}),
+        ...definedOnly({
+            authHeaders: credential ? { Authorization: `Bearer ${credential}` } : undefined,
+            fetchImpl: deps.fetchImpl,
+            stdin: deps.stdin,
+            stdout: deps.stdout,
+        }),
     };
-    try {
-        await createMcpToolServerFn(requiredArgs, serverOptions).run({});
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        writeErr({ text: `${SERVER_NAME}: ${message}\n` });
-        return exit({ code: 1 });
+}
+// Only the spawning host supplies registration metadata. Never learn exceptions from an
+// error body or model arguments: either would turn a secret into its own redaction exemption.
+function parseLaunchToolIds({ env, key }) {
+    const toolIds = JSON.parse(env[key] ?? '[]');
+    if (!Array.isArray(toolIds) || !toolIds.every(id => typeof id === 'string')) {
+        throw new Error(`${key} must be a JSON array of registered tool IDs`);
     }
+    return toolIds;
+}
+/**
+ * Resolve each unique startup ID through the existing authenticated describe/publication owner.
+ * The temporary descriptor list seeds M1's bounded exposure; it is not an execution catalog.
+ * Failure aborts startup before any partially resolved list can reach the client.
+ * @returns Authoritative descriptors; no daemon I/O when startup IDs are absent.
+ * @throws The existing descriptor/daemon errors, reported by serve's stderr/exit boundary.
+ * @complexity O(n + s) space/time plus n sequential bounded GETs for n unique IDs and s schema bytes.
+ */
+async function resolveStartupTools({ toolIds, resolveBaseUrl, serverOptions }) {
+    if (toolIds.length === 0)
+        return [];
+    const descriptors = [];
+    const ctx = {
+        baseUrl: await resolveBaseUrl(),
+        fetchImpl: serverOptions.fetchImpl ?? fetch,
+        ...definedOnly({ authHeaders: serverOptions.authHeaders, diagnosticToolIds: serverOptions.diagnosticToolIds }),
+        publishTool: async ({ descriptor }) => { descriptors.push(descriptor); },
+    };
+    for (const id of new Set(toolIds))
+        await describeToolTool.handler({ args: { id }, ctx });
+    return descriptors;
 }
 // Only run for real when this module is the actual process entrypoint (`node dist/bin/serve.js`,
 // or the `jini-mcp` bin shim pnpm/npm links to it) — not merely imported, e.g. by this file's own