@jini-ai/mcp 0.3.3 → 0.4.0

package/dist/bin/serve.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'node:url';
-import { resolveDaemonUrl as resolveDaemonUrlDefault } from '@jini-ai/cli';
+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';
@@ -9,7 +9,7 @@ import { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool
 import { KERNEL_RESOURCES } from '../server/resources/active-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 `@jini-ai/cli/main.ts`'s identically-named constant. */
+/** Checked (only) when resolving the daemon HTTP base URL — see `resolveDaemonUrl`'s own docs; matches the CLI entry point's identically-named constant. */
 export const DAEMON_URL_ENV_VAR = 'JINI_DAEMON_URL';
 /**
  * Bearer credential for this process's daemon callbacks, set by the spawning daemon when it issued
@@ -41,7 +41,32 @@ 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.';
-function defaultWriteErr(text) {
+// 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.');
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        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.` });
+    }
+    return url;
+}
+function defaultWriteErr({ text }) {
     process.stderr.write(text);
 }
 /**
@@ -52,25 +77,24 @@ function defaultWriteErr(text) {
  * idle-exit window elapses (`createMcpToolServer`'s own default) — never bare-throws: every error
  * path below writes a message to `writeErr` and calls `exit(1)` instead.
  */
-export async function serve(deps = {}) {
+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 exit = deps.exit ?? (({ code }) => process.exit(code));
     const resolveDaemonUrlFn = deps.resolveDaemonUrl ?? resolveDaemonUrlDefault;
     const createMcpToolServerFn = deps.createMcpToolServer ?? createMcpToolServerDefault;
     const runId = env[RUN_ID_ENV_VAR];
     if (typeof runId !== 'string' || runId.length === 0) {
-        writeErr(`${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(1);
+        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 });
     }
     const resolveBaseUrl = () => {
-        const options = { flagUrl: null, env, envVarName: DAEMON_URL_ENV_VAR, warn: writeErr };
-        return resolveDaemonUrlFn(options);
+        const options = { flagUrl: null, env, envVarName: DAEMON_URL_ENV_VAR, warn: ({ message }) => writeErr({ text: message }) };
+        return resolveDaemonUrlFn({}, options);
     };
     // 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 = {
-        runId,
         ...(deps.generateToolUseId !== undefined ? { 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.
@@ -82,11 +106,11 @@ export async function serve(deps = {}) {
         ...RUN_TOOLS,
         ...TOOL_CATALOG_TOOLS,
         ...COMPONENT_CATALOG_TOOLS,
-        createExecuteDelegatedToolTool(delegatedGatewayOptions),
+        createExecuteDelegatedToolTool({ runId }, delegatedGatewayOptions),
         // Hosted ALONGSIDE the unconstrained gateway, never instead of it. A client that gates on
         // `readOnlyHint: true` can now reach the read half of the catalog at all; every other client
         // sees both and picks by what its call actually does.
-        createExecuteReadonlyDelegatedToolTool(delegatedGatewayOptions),
+        createExecuteReadonlyDelegatedToolTool({ runId }, delegatedGatewayOptions),
     ];
     // 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.
@@ -94,12 +118,9 @@ export async function serve(deps = {}) {
     const authHeaders = typeof credential === 'string' && credential.length > 0
         ? { Authorization: `Bearer ${credential}` }
         : undefined;
+    const requiredArgs = { name: SERVER_NAME, version: SERVER_VERSION, tools, resolveBaseUrl };
     const serverOptions = {
-        name: SERVER_NAME,
-        version: SERVER_VERSION,
-        tools,
         resources: KERNEL_RESOURCES,
-        resolveBaseUrl,
         instructions: INSTRUCTIONS,
         ...(authHeaders !== undefined ? { authHeaders } : {}),
         ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
@@ -107,19 +128,19 @@ export async function serve(deps = {}) {
         ...(deps.stdout !== undefined ? { stdout: deps.stdout } : {}),
     };
     try {
-        await createMcpToolServerFn(serverOptions).run();
+        await createMcpToolServerFn(requiredArgs, serverOptions).run({});
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        writeErr(`${SERVER_NAME}: ${message}\n`);
-        return exit(1);
+        writeErr({ text: `${SERVER_NAME}: ${message}\n` });
+        return exit({ code: 1 });
     }
 }
 // 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
-// tests importing the named `serve` export above. Mirrors `@jini-ai/cli/main.ts`'s identical guard.
+// tests importing the named `serve` export above. Mirrors the CLI entry point's identical guard.
 const isMainModule = process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1];
 if (isMainModule) {
-    await serve();
+    await serve({});
 }
 //# sourceMappingURL=serve.js.map

package/dist/client/client.d.ts

@@ -6,23 +6,37 @@
  * textual-MIME classifier. Dependency-free (node stdlib only); imports no
  * sibling MCP subdirectory.
  */
+/** Scheduling boundary for hosts that manage their own timer lifecycle. */
+export interface McpIdleTimerPort {
+    schedule(args: {
+        callback: () => void;
+        delayMs: number;
+    }): ReturnType<typeof setTimeout>;
+    cancel(args: {
+        handle: ReturnType<typeof setTimeout>;
+    }): void;
+}
 interface McpIdleExitControllerOptions {
     idleMs: number;
-    onIdle: () => void;
+    onIdle: (required: Record<string, never>) => void;
 }
 /**
  * Create an idle-exit controller that calls `onIdle` after `idleMs` of
- * inactivity. Activity is tracked via `noteActivity()` and `trackRequest()`;
+ * inactivity. Activity is tracked via `noteActivity({})` and `trackRequest({ fn })`;
  * in-flight requests defer the idle timer. Used to auto-close a long-running
  * stdio MCP server process after a period of no tool calls.
  * @param options Idle duration in ms (finite positive integer, clamped to a
  *   24h ceiling — throws `RangeError` otherwise) and the callback to invoke on idle.
  * @returns An object with `noteActivity`, `trackRequest`, and `dispose` methods.
  */
-export declare function createMcpIdleExitController({ idleMs, onIdle, }: McpIdleExitControllerOptions): {
-    noteActivity(): void;
-    trackRequest<T>(fn: () => T | Promise<T>): Promise<T>;
-    dispose(): void;
+export declare function createMcpIdleExitController({ idleMs, onIdle, }: McpIdleExitControllerOptions, { timers }?: {
+    timers?: McpIdleTimerPort;
+}): {
+    noteActivity(_required: Record<string, never>): void;
+    trackRequest<T>({ fn }: {
+        fn: (required: Record<string, never>) => T | Promise<T>;
+    }): Promise<T>;
+    dispose(_required: Record<string, never>): void;
 };
 /**
  * True when `mime` names a textual content type whose body can be surfaced
@@ -31,7 +45,9 @@ export declare function createMcpIdleExitController({ idleMs, onIdle, }: McpIdle
  * @param mime The MIME type string to classify (undefined counts as non-textual).
  * @returns Whether the content should be treated as text.
  */
-export declare function isTextualMime(mime: string | undefined): boolean;
+export declare function isTextualMime({ mime }: {
+    mime: string | undefined;
+}): boolean;
 /**
  * Extract all relative (non-absolute, non-CDN, non-data-URI) file references from
  * the text content of a file, normalized to root-relative paths.
@@ -43,6 +59,10 @@ export declare function isTextualMime(mime: string | undefined): boolean;
  * @param fromMime The MIME type of the file (used to select reference-extraction patterns).
  * @returns Deduplicated root-relative paths of all referenced files found.
  */
-export declare function extractRelativeRefs(text: string, fromPath: string, fromMime: string): string[];
+export declare function extractRelativeRefs({ text, fromPath, fromMime }: {
+    text: string;
+    fromPath: string;
+    fromMime: string;
+}): string[];
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client/client.js

@@ -11,6 +11,10 @@
 // references" bundling. They hold no state beyond the idle controller's own
 // timer and never touch the network or filesystem, so they unit-test against
 // plain values.
+const defaultTimers = {
+    schedule: ({ callback, delayMs }) => setTimeout(callback, delayMs),
+    cancel: ({ handle }) => clearTimeout(handle),
+};
 // SEC-RB-011: an unvalidated `idleMs` (negative, `NaN`, `Infinity`, or a
 // non-integer) would either schedule an immediately/never-firing timer or
 // hand `setTimeout` a value it silently coerces in surprising ways. Bound it
@@ -28,21 +32,21 @@ function normalizeIdleMs(idleMs) {
 }
 /**
  * Create an idle-exit controller that calls `onIdle` after `idleMs` of
- * inactivity. Activity is tracked via `noteActivity()` and `trackRequest()`;
+ * inactivity. Activity is tracked via `noteActivity({})` and `trackRequest({ fn })`;
  * in-flight requests defer the idle timer. Used to auto-close a long-running
  * stdio MCP server process after a period of no tool calls.
  * @param options Idle duration in ms (finite positive integer, clamped to a
  *   24h ceiling — throws `RangeError` otherwise) and the callback to invoke on idle.
  * @returns An object with `noteActivity`, `trackRequest`, and `dispose` methods.
  */
-export function createMcpIdleExitController({ idleMs, onIdle, }) {
+export function createMcpIdleExitController({ idleMs, onIdle, }, { timers = defaultTimers } = {}) {
     const effectiveIdleMs = normalizeIdleMs(idleMs);
     let timer = null;
     let inFlight = 0;
     let disposed = false;
     const clear = () => {
         if (timer) {
-            clearTimeout(timer);
+            timers.cancel({ handle: timer });
             timer = null;
         }
     };
@@ -50,26 +54,26 @@ export function createMcpIdleExitController({ idleMs, onIdle, }) {
         if (disposed)
             return;
         clear();
-        timer = setTimeout(() => {
-            // `dispose()` always clears the pending timer and `schedule()` bails when
-            // already disposed, so this callback can only fire while live.
-            timer = null;
-            if (inFlight > 0) {
-                schedule();
-                return;
-            }
-            disposed = true;
-            onIdle();
-        }, effectiveIdleMs);
+        timer = timers.schedule({ callback: () => {
+                // `dispose({})` always clears the pending timer and `schedule()` bails when
+                // already disposed, so this callback can only fire while live.
+                timer = null;
+                if (inFlight > 0) {
+                    schedule();
+                    return;
+                }
+                disposed = true;
+                onIdle({});
+            }, delayMs: effectiveIdleMs });
     };
     schedule();
     return {
-        noteActivity() {
+        noteActivity(_required) {
             schedule();
         },
-        async trackRequest(fn) {
+        async trackRequest({ fn }) {
             if (disposed) {
-                return fn();
+                return fn({});
             }
             inFlight += 1;
             // Deliberately does NOT call `schedule()` here (SEC-RB-011): a request
@@ -80,7 +84,7 @@ export function createMcpIdleExitController({ idleMs, onIdle, }) {
             // on every concurrent request start instead caused needless
             // clearTimeout/setTimeout churn under load with no behavioral benefit.
             try {
-                return await fn();
+                return await fn({});
             }
             finally {
                 inFlight -= 1;
@@ -89,7 +93,7 @@ export function createMcpIdleExitController({ idleMs, onIdle, }) {
                 }
             }
         },
-        dispose() {
+        dispose(_required) {
             disposed = true;
             clear();
         },
@@ -114,7 +118,7 @@ const TEXTUAL_MIME_PATTERNS = [
  * @param mime The MIME type string to classify (undefined counts as non-textual).
  * @returns Whether the content should be treated as text.
  */
-export function isTextualMime(mime) {
+export function isTextualMime({ mime }) {
     if (!mime)
         return false;
     return TEXTUAL_MIME_PATTERNS.some((re) => re.test(mime));
@@ -169,7 +173,7 @@ function isHtmlLike(mime, fromPath) {
  * @param fromMime The MIME type of the file (used to select reference-extraction patterns).
  * @returns Deduplicated root-relative paths of all referenced files found.
  */
-export function extractRelativeRefs(text, fromPath, fromMime) {
+export function extractRelativeRefs({ text, fromPath, fromMime }) {
     if (!text)
         return [];
     const refs = new Set();

package/dist/core/config.d.ts

@@ -1,10 +1,3 @@
-/**
- * @module @jini-ai/mcp/core/config
- * Config schema + on-disk store for the external MCP servers the daemon connects
- * to as a client, plus the per-agent config builders (Claude `.mcp.json`, ACP
- * `mcpServers`, OpenCode) that hand those servers to a launching agent. Part of
- * the MCP `core` kernel; depends on no sibling subdirectory.
- */
 /** Wire-level transport discriminator for how the daemon connects to an external MCP server. */
 export type McpTransport = 'stdio' | 'sse' | 'http';
 /** Authentication mode for remote MCP servers: `'none'` for local/loopback targets, `'oauth'` for remote ones. */
@@ -29,6 +22,16 @@ export interface McpServerConfig {
 export interface McpConfig {
     servers: McpServerConfig[];
 }
+/** Text I/O boundary; secret writes must be atomic and owner-only from creation. */
+export interface McpConfigFilesystemPort {
+    readText(args: {
+        filePath: string;
+    }): Promise<string>;
+    writeSecretText(args: {
+        filePath: string;
+        contents: string;
+    }): Promise<void>;
+}
 /**
  * Infer the appropriate `McpAuthMode` for a given server URL.
  * Returns `'none'` for loopback targets (localhost, 127.x.x.x, ::1)
@@ -36,13 +39,17 @@ export interface McpConfig {
  * @param rawUrl The server URL string to inspect, if any.
  * @returns The inferred `McpAuthMode`.
  */
-export declare function inferMcpAuthModeForUrl(rawUrl: string | undefined): McpAuthMode;
+export declare function inferMcpAuthModeForUrl({ rawUrl }: {
+    rawUrl: string | undefined;
+}): McpAuthMode;
 /**
  * Validate a single user-supplied entry. Drops invalid fields so a typo in
  * one server doesn't tank the whole config. Returns null when the entry is
  * unsalvageable (no id, or no transport-required fields).
  */
-export declare function sanitizeMcpServer(raw: unknown): McpServerConfig | null;
+export declare function sanitizeMcpServer({ raw }: {
+    raw: unknown;
+}): McpServerConfig | null;
 /**
  * Coerce and de-duplicate a freeform JSON blob into a valid `McpConfig`.
  * Entries that fail `sanitizeMcpServer` are silently dropped; duplicate ids
@@ -50,14 +57,20 @@ export declare function sanitizeMcpServer(raw: unknown): McpServerConfig | null;
  * @param raw The raw parsed JSON to sanitize.
  * @returns A clean `McpConfig` guaranteed to have only valid, unique server entries.
  */
-export declare function sanitizeMcpConfig(raw: unknown): McpConfig;
+export declare function sanitizeMcpConfig({ raw }: {
+    raw: unknown;
+}): McpConfig;
 /**
  * Read and sanitize the MCP config from `<dataDir>/mcp-config.json`.
  * Returns `{ servers: [] }` when the file does not exist or contains invalid JSON.
  * @param dataDir The resolved runtime data directory.
  * @returns The sanitized `McpConfig`, never rejects on missing-file or corrupt-JSON.
  */
-export declare function readMcpConfig(dataDir: string): Promise<McpConfig>;
+export declare function readMcpConfig({ dataDir }: {
+    dataDir: string;
+}, { filesystem }?: {
+    filesystem?: McpConfigFilesystemPort;
+}): Promise<McpConfig>;
 /**
  * Sanitize and atomically write the MCP config to `<dataDir>/mcp-config.json`.
  * Uses a per-`dataDir` promise-chain mutex so concurrent writes serialize
@@ -65,13 +78,18 @@ export declare function readMcpConfig(dataDir: string): Promise<McpConfig>;
  * being written. This file may carry environment variables and
  * `Authorization` header values (API keys, bearer tokens — see
  * `McpServerConfig.env`/`.headers`), so it is written with owner-only
- * (0600) permissions from the very first byte via `writeSecretFileAtomic`
+ * (0600) permissions from the very first byte via `writeFileAtomicAsync`
  * rather than a post-rename chmod (CR-006 / SEC-RB-002).
  * @param dataDir The resolved runtime data directory.
  * @param body The raw config body to sanitize and persist.
  * @returns The sanitized `McpConfig` that was written to disk.
  */
-export declare function writeMcpConfig(dataDir: string, body: unknown): Promise<McpConfig>;
+export declare function writeMcpConfig({ dataDir, body }: {
+    dataDir: string;
+    body: unknown;
+}, { filesystem }?: {
+    filesystem?: McpConfigFilesystemPort;
+}): Promise<McpConfig>;
 /**
  * True when `cwd` is a daemon-managed project directory under `projectsDir`
  * (= safe to write `.mcp.json` into without risk of clobbering a user-owned
@@ -82,11 +100,18 @@ export declare function writeMcpConfig(dataDir: string, body: unknown): Promise<
  * Both `cwd` and `projectsDir` are realpath-resolved before the containment
  * check (falling back to lexical `path.resolve` normalization for a path
  * that doesn't exist on disk yet), and containment is decided with
- * `@jini-ai/platform`'s separator-aware `pathContains` rather than a raw
+ * `@jini-ai/core/primitives`' separator-aware `pathContains` rather than a raw
  * string-prefix check — a `..`-containing path or a symlinked descendant
  * can defeat a plain `startsWith` (CR-006 / SEC-RB-011).
  */
-export declare function isManagedProjectCwd(cwd: string | null | undefined, projectsDir: string): boolean;
+export declare function isManagedProjectCwd({ cwd, projectsDir }: {
+    cwd: string | null | undefined;
+    projectsDir: string;
+}, { resolvePath }?: {
+    resolvePath?: (args: {
+        filePath: string;
+    }) => string;
+}): boolean;
 /**
  * Project-cwd `.mcp.json` shape that Claude Code auto-loads on spawn (the
  * same format Claude Desktop and Cursor use). Returns null when the user
@@ -101,7 +126,11 @@ export declare function isManagedProjectCwd(cwd: string | null | undefined, proj
  * pre-authenticated credentials. User-supplied headers always win on
  * conflict so they can pin a specific token if they really want to.
  */
-export declare function buildClaudeMcpJson(servers: McpServerConfig[], tokens?: Record<string, string>): unknown | null;
+export declare function buildClaudeMcpJson({ servers }: {
+    servers: McpServerConfig[];
+}, { tokens }?: {
+    tokens?: Record<string, string>;
+}): unknown | null;
 /**
  * Convert user-configured external MCP servers into the ACP `mcpServers`
  * shape that stdio-capable ACP agents accept.
@@ -124,7 +153,9 @@ export interface AcpMcpServer {
  * @param servers The full server list from `McpConfig`.
  * @returns ACP-shaped server entries for all enabled stdio servers.
  */
-export declare function buildAcpMcpServers(servers: McpServerConfig[]): AcpMcpServer[];
+export declare function buildAcpMcpServers({ servers }: {
+    servers: McpServerConfig[];
+}): AcpMcpServer[];
 /**
  * OpenCode merges its config from multiple sources at boot — global
  * `~/.config/opencode/opencode.json`, the `OPENCODE_CONFIG` file path, the
@@ -148,10 +179,18 @@ export declare function buildAcpMcpServers(servers: McpServerConfig[]): AcpMcpSe
  */
 /** Options for `buildOpenCodeMcpConfigContent`. */
 export interface OpenCodeConfigBuildOptions {
+    /** Access tokens keyed by server id. */
+    tokens?: Record<string, string>;
+    /** Resolves symlinks for permission allowlists. */
+    resolvePath?: (args: {
+        filePath: string;
+    }) => string;
     /** Absolute filesystem paths OpenCode's `external_directory` permission should allow. */
     allowedDirectories?: string[];
     /** Additional top-level keys merged into the emitted config object (e.g. `provider`). */
     extraConfig?: Record<string, unknown>;
 }
-export declare function buildOpenCodeMcpConfigContent(servers: McpServerConfig[], tokens?: Record<string, string>, options?: OpenCodeConfigBuildOptions): string | null;
+export declare function buildOpenCodeMcpConfigContent({ servers }: {
+    servers: McpServerConfig[];
+}, options?: OpenCodeConfigBuildOptions): string | null;
 //# sourceMappingURL=config.d.ts.map