@jini-ai/mcp 0.4.2 → 0.4.3

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/bin/serve.js

@@ -7,6 +7,7 @@ import { 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. */
@@ -40,7 +41,10 @@ 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. ' +
+    '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) {
@@ -120,7 +124,7 @@ export async function serve(_requiredArgs, deps = {}) {
         : undefined;
     const requiredArgs = { name: SERVER_NAME, version: SERVER_VERSION, tools, resolveBaseUrl };
     const serverOptions = {
-        resources: KERNEL_RESOURCES,
+        resources: [...KERNEL_RESOURCES, createSiteGuideResource({ runId }, delegatedGatewayOptions)],
         instructions: INSTRUCTIONS,
         ...(authHeaders !== undefined ? { authHeaders } : {}),
         ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),

package/dist/federation/bootstrap.d.ts

@@ -2,6 +2,7 @@ import { type Logger } from "@jini-ai/core/primitives";
 import type { ToolRegistry } from "@jini-ai/core";
 import type { ResolvedFederatedConnection } from "./config.js";
 import type { McpSessionPort } from "./ports.js";
+import { type FederatedMcpPresetRegistry } from "./presets.js";
 import { type FederationDeps } from "./registrations.js";
 import type { FederatedAdmissionReport } from "./trust.js";
 export interface AttachFederatedToolsResult {
@@ -74,6 +75,7 @@ export interface AttachFederatedToolsResult {
  * @complexity O(c · t) in connections and their advertised tools.
  */
 export interface AttachFederatedMcpToolsParams {
+    readonly presetRegistry?: FederatedMcpPresetRegistry;
     registry: ToolRegistry;
     deps: FederationDeps;
     connections?: readonly ResolvedFederatedConnection[] | undefined;
@@ -97,4 +99,20 @@ export interface AttachFederatedMcpToolsParams {
 export type AttachFederatedMcpToolsRequiredArgs = Pick<AttachFederatedMcpToolsParams, "registry" | "deps" | "connect">;
 export type AttachFederatedMcpToolsOptions = Omit<AttachFederatedMcpToolsParams, "registry" | "deps" | "connect">;
 export declare function attachFederatedMcpTools(requiredArgs: AttachFederatedMcpToolsRequiredArgs, optionalArgs?: AttachFederatedMcpToolsOptions): Promise<AttachFederatedToolsResult>;
+/**
+ * Asks every registered preset for a connection, in registration order.
+ *
+ * Errors are isolated PER PRESET rather than abandoning the whole resolution pass: an enabled-but-
+ * invalid Supabase config must not also disable a correctly-configured second vendor that happens to
+ * be registered after it. Each failure is loud — the operator meant to have that connection and does
+ * not — and still non-fatal, because host app's own assistant is unaffected either way.
+ *
+ * A preset that declines (`null`) is silent: "not configured" is the expected default state, and
+ * logging it every boot would train operators to ignore this channel.
+ */
+export declare function resolveFederatedMcpPresets({ env, logger, registry }: {
+    env: NodeJS.ProcessEnv;
+    logger: Pick<Logger, "warn">;
+    registry: FederatedMcpPresetRegistry;
+}, _optional?: {}): ResolvedFederatedConnection[];
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/federation/bootstrap.js

@@ -1,5 +1,5 @@
 import { createConsoleLogger } from "@jini-ai/core/primitives";
-import { listFederatedMcpPresets } from "./presets.js";
+import { defaultFederatedMcpPresetRegistry } from "./presets.js";
 import { federateSession } from "./registrations.js";
 /**
  * @file The composition root for outbound MCP federation: the one function
@@ -56,7 +56,7 @@ function withPresetOrigin(connection) {
 function resolveFederationAttachInputs(params) {
     const logger = params.logger ?? consoleLogger;
     const connect = params.connect;
-    const presetConnections = params.connections ?? resolveRegisteredPresets(params.env ?? process.env, logger);
+    const presetConnections = params.connections ?? resolveFederatedMcpPresets({ env: params.env ?? process.env, logger, registry: params.presetRegistry ?? defaultFederatedMcpPresetRegistry });
     const connections = [
         ...presetConnections.map((connection) => ({ connection: withPresetOrigin(connection), isPreset: true })),
         ...(params.extraConnections ?? []).map((connection) => ({ connection, isPreset: false })),
@@ -162,9 +162,9 @@ async function attachOneFederatedConnection(params) {
  * A preset that declines (`null`) is silent: "not configured" is the expected default state, and
  * logging it every boot would train operators to ignore this channel.
  */
-function resolveRegisteredPresets(env, logger) {
+export function resolveFederatedMcpPresets({ env, logger, registry }, _optional = {}) {
     const connections = [];
-    for (const preset of listFederatedMcpPresets()) {
+    for (const preset of registry.list({})) {
         try {
             const connection = preset.resolve({ env: env });
             if (connection)

package/dist/federation/presets.d.ts

@@ -44,23 +44,22 @@ export interface FederatedMcpPreset {
     readonly presetId: string;
     readonly resolve: FederatedMcpPresetResolver;
 }
-/**
- * Registers a preset, called once at composition-root boot by the preset's own module.
- *
- * Re-registering the same `presetId` REPLACES the earlier entry rather than appending. Unlike a
- * `<head>` contributor, a duplicate here would resolve to two connections with the same
- * `connectionId`, and `trust.ts` R1's collision assertion would then drop the second one whole —
- * producing a confusing "registered, then refused for shadowing itself" log for what is really just
- * a module imported from two places. Last registration wins, and registration order is otherwise
- * preserved so a replacement does not silently reorder connections.
- */
-export declare function registerFederatedMcpPreset({ preset }: {
+export interface FederatedMcpPresetRegistry {
+    register(required: {
+        preset: FederatedMcpPreset;
+    }, optional?: Record<string, never>): void;
+    list(required: Record<string, never>, optional?: Record<string, never>): readonly FederatedMcpPreset[];
+    reset(required: Record<string, never>, optional?: Record<string, never>): void;
+}
+/** Each host owns one ordered registry. Replacement retains order; snapshots cannot mutate it.
+ * The preserved reset rationale below describes the legacy module registry; reset now clears
+ * only this instance. The published default registry is a compatibility adapter. */
+export declare function createFederatedMcpPresetRegistry(_required: Record<string, never>, _optional?: Record<string, never>): FederatedMcpPresetRegistry;
+/** Compatibility owner for published callers; hosts inject their own instance at boot. */
+export declare const defaultFederatedMcpPresetRegistry: FederatedMcpPresetRegistry;
+export declare function registerFederatedMcpPreset(required: {
     preset: FederatedMcpPreset;
-}): void;
-/** Registration order. `bootstrap.ts` resolves in this order, and that order decides which
- * connection claims a contested tool id first (R1). */
+}, optional?: {}): void;
 export declare function listFederatedMcpPresets(): readonly FederatedMcpPreset[];
-/** Test-only reset of the module-level registry (mirrors `page-head.ts`'s
- * `resetPageHeadRegistry`, though that one is no longer test-only — see its own doc). */
-export declare function resetFederatedMcpPresetsForTests(_required: Record<string, never>): void;
+export declare function resetFederatedMcpPresetsForTests(required: Record<string, never>): void;
 //# sourceMappingURL=presets.d.ts.map

package/dist/federation/presets.js

@@ -1,30 +1,37 @@
-let presets = [];
-/**
- * Registers a preset, called once at composition-root boot by the preset's own module.
- *
- * Re-registering the same `presetId` REPLACES the earlier entry rather than appending. Unlike a
- * `<head>` contributor, a duplicate here would resolve to two connections with the same
- * `connectionId`, and `trust.ts` R1's collision assertion would then drop the second one whole —
- * producing a confusing "registered, then refused for shadowing itself" log for what is really just
- * a module imported from two places. Last registration wins, and registration order is otherwise
- * preserved so a replacement does not silently reorder connections.
- */
-export function registerFederatedMcpPreset({ preset }) {
-    const existing = presets.findIndex((candidate) => candidate.presetId === preset.presetId);
-    if (existing >= 0) {
-        presets[existing] = preset;
-        return;
-    }
-    presets.push(preset);
-}
-/** Registration order. `bootstrap.ts` resolves in this order, and that order decides which
- * connection claims a contested tool id first (R1). */
-export function listFederatedMcpPresets() {
-    return presets;
-}
-/** Test-only reset of the module-level registry (mirrors `page-head.ts`'s
- * `resetPageHeadRegistry`, though that one is no longer test-only — see its own doc). */
-export function resetFederatedMcpPresetsForTests(_required) {
-    presets = [];
+/** Each host owns one ordered registry. Replacement retains order; snapshots cannot mutate it.
+ * The preserved reset rationale below describes the legacy module registry; reset now clears
+ * only this instance. The published default registry is a compatibility adapter. */
+export function createFederatedMcpPresetRegistry(_required, _optional = {}) {
+    let presets = [];
+    return {
+        /**
+         * Registers a preset, called once at composition-root boot by the preset's own module.
+         *
+         * Re-registering the same `presetId` REPLACES the earlier entry rather than appending. Unlike a
+         * `<head>` contributor, a duplicate here would resolve to two connections with the same
+         * `connectionId`, and `trust.ts` R1's collision assertion would then drop the second one whole —
+         * producing a confusing "registered, then refused for shadowing itself" log for what is really just
+         * a module imported from two places. Last registration wins, and registration order is otherwise
+         * preserved so a replacement does not silently reorder connections.
+         */
+        register({ preset }) {
+            const existing = presets.findIndex(candidate => candidate.presetId === preset.presetId);
+            if (existing >= 0)
+                presets[existing] = preset;
+            else
+                presets.push(preset);
+        },
+        /** Registration order. `bootstrap.ts` resolves in this order, and that order decides which
+         * connection claims a contested tool id first (R1). */
+        list: () => Object.freeze(presets.slice()),
+        /** Test-only reset of the module-level registry (mirrors `page-head.ts`'s
+         * `resetPageHeadRegistry`, though that one is no longer test-only — see its own doc). */
+        reset: () => { presets = []; },
+    };
 }
+/** Compatibility owner for published callers; hosts inject their own instance at boot. */
+export const defaultFederatedMcpPresetRegistry = createFederatedMcpPresetRegistry({});
+export function registerFederatedMcpPreset(required, optional = {}) { defaultFederatedMcpPresetRegistry.register(required, optional); }
+export function listFederatedMcpPresets() { return defaultFederatedMcpPresetRegistry.list({}); }
+export function resetFederatedMcpPresetsForTests(required) { defaultFederatedMcpPresetRegistry.reset(required); }
 //# sourceMappingURL=presets.js.map

package/dist/index.d.ts

@@ -14,13 +14,13 @@ export type { BuildMcpInstallPayloadInputs, McpInstallPayload } from './core/ind
 export { createMcpIdleExitController, extractRelativeRefs, isTextualMime, } from './client/index.js';
 export { cancelRunTool, createMcpToolServer, daemonCallOptions, errorResult, getActiveContextTool, getDaemonJson, getRunTool, listAgentsTool, okResult, postDaemonJson, requireString, RUN_TOOLS, startRunTool, toolsToList, buildToolIndex, handleToolCall, DaemonResponseTooLargeError, } from './server/index.js';
 export type { DaemonRequestOptions, McpServerLike, McpToolContext, McpToolDef, McpToolServerHandle, McpToolServerOptions, McpTransportLike, } from './server/index.js';
-export { activeContextResource, buildResourceIndex, handleResourceRead, KERNEL_RESOURCES, resourcesToList, } from './server/index.js';
+export { activeContextResource, createSiteGuideResource, buildResourceIndex, handleResourceRead, KERNEL_RESOURCES, resourcesToList, } from './server/index.js';
 export type { McpResourceDef, McpResourceReadResult } from './server/index.js';
 export { searchToolsTool, describeToolTool, TOOL_CATALOG_TOOLS } from './server/index.js';
 export { searchComponentsTool, describeComponentTool, COMPONENT_CATALOG_TOOLS } from './server/index.js';
 export { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool, DEFAULT_DELEGATED_TOOL_TIMEOUT_MS, } from './server/index.js';
 export type { CreateExecuteDelegatedToolToolOptions } from './server/index.js';
-export { AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
+export { CHROME_DEVTOOLS_MCP_PRESET, AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
 export type { AgentSlug, McpLaunchSpec, PlanContext, CliInstallPlan, JsonInstallPlan, ManualInstallPlan, InstallPlan, } from './agent-install/index.js';
 export type { McpConfigFilesystemPort } from './core/config.js';
 export type { McpTokenClockOptions, McpTokenStoreOptions } from './core/tokens.js';

package/dist/index.js

@@ -16,7 +16,7 @@ export { createMcpIdleExitController, extractRelativeRefs, isTextualMime, } from
 // ── server: the generic MCP tool-hosting mechanism + kernel-run tool defs ───
 export { cancelRunTool, createMcpToolServer, daemonCallOptions, errorResult, getActiveContextTool, getDaemonJson, getRunTool, listAgentsTool, okResult, postDaemonJson, requireString, RUN_TOOLS, startRunTool, toolsToList, buildToolIndex, handleToolCall, DaemonResponseTooLargeError, } from './server/index.js';
 // ── server: the generic MCP resource surface + kernel resource defs ────────
-export { activeContextResource, buildResourceIndex, handleResourceRead, KERNEL_RESOURCES, resourcesToList, } from './server/index.js';
+export { activeContextResource, createSiteGuideResource, buildResourceIndex, handleResourceRead, KERNEL_RESOURCES, resourcesToList, } from './server/index.js';
 // ── server: the tool-catalog discovery defs (search_tools / describe_tool) ──
 export { searchToolsTool, describeToolTool, TOOL_CATALOG_TOOLS } from './server/index.js';
 // ── server: the component-catalog discovery defs (search_components / describe_component) ──
@@ -24,6 +24,6 @@ export { searchComponentsTool, describeComponentTool, COMPONENT_CATALOG_TOOLS }
 // ── server: gap 3's MCP-callback delegated-tool-execution def ──────────────
 export { createExecuteDelegatedToolTool, createExecuteReadonlyDelegatedToolTool, DEFAULT_DELEGATED_TOOL_TIMEOUT_MS, } from './server/index.js';
 // ── agent-install: register an MCP server into external agents ──────────────
-export { AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
+export { CHROME_DEVTOOLS_MCP_PRESET, AGENT_SLUGS, isAgentSlug, planAgentInstall, applyJsonInstall, removeJsonInstall, } from './agent-install/index.js';
 export { DaemonHttpError } from './server/daemon-client.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.d.ts

@@ -19,4 +19,5 @@ export * from './tools/delegated-tool.js';
 export * from './tools/tool-catalog-tools.js';
 export * from './tools/component-catalog-tools.js';
 export * from './resources/active-resource.js';
+export * from './resources/site-guide-resource.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.js

@@ -19,4 +19,5 @@ export * from './tools/delegated-tool.js';
 export * from './tools/tool-catalog-tools.js';
 export * from './tools/component-catalog-tools.js';
 export * from './resources/active-resource.js';
+export * from './resources/site-guide-resource.js';
 //# sourceMappingURL=index.js.map

package/dist/server/resources/site-guide-resource.d.ts

@@ -0,0 +1,15 @@
+import type { McpResourceDef } from '../resource-protocol.js';
+import { type CreateExecuteDelegatedToolToolOptions } from '../tools/delegated-tool.js';
+/** Expose a host's learning tool as an attachable resource through the EXISTING read-only gateway.
+ * The run identity is host-bound; bearer headers, cancellation and authorization follow the same
+ * path as tools/call. No direct registry read or privileged principal is introduced.
+ * @param input - The spawning run id, never supplied by the MCP client.
+ * @returns jini://site-guide, with a fresh permission-scoped overview on every read.
+ * @throws When the host lacks site_guide, authorization denies, or execution does not complete.
+ * @complexity O(1) plus one delegated read and result serialization.
+ * @example createSiteGuideResource({ runId });
+ */
+export declare function createSiteGuideResource(input: {
+    readonly runId: string;
+}, options?: CreateExecuteDelegatedToolToolOptions): McpResourceDef;
+//# sourceMappingURL=site-guide-resource.d.ts.map

package/dist/server/resources/site-guide-resource.js

@@ -0,0 +1,25 @@
+import { createExecuteReadonlyDelegatedToolTool } from '../tools/delegated-tool.js';
+/** Expose a host's learning tool as an attachable resource through the EXISTING read-only gateway.
+ * The run identity is host-bound; bearer headers, cancellation and authorization follow the same
+ * path as tools/call. No direct registry read or privileged principal is introduced.
+ * @param input - The spawning run id, never supplied by the MCP client.
+ * @returns jini://site-guide, with a fresh permission-scoped overview on every read.
+ * @throws When the host lacks site_guide, authorization denies, or execution does not complete.
+ * @complexity O(1) plus one delegated read and result serialization.
+ * @example createSiteGuideResource({ runId });
+ */
+export function createSiteGuideResource(input, options = {}) {
+    const gateway = createExecuteReadonlyDelegatedToolTool(input, options);
+    return {
+        uri: 'jini://site-guide', name: 'How this site works', mimeType: 'application/json',
+        description: 'Permission-filtered building blocks and live facts for the site hosting this run. Consult before planning or building; use site_guide explain through the delegated gateway for details.',
+        read: async ({ ctx }) => {
+            const result = await gateway.handler({ args: { toolId: 'site_guide', input: { operation: 'overview' } }, ctx });
+            if (typeof result !== 'object' || result === null || !('status' in result) || result.status !== 'completed' || !('output' in result)) {
+                throw new Error('site_guide resource read did not complete. Use the delegated tool result to inspect authorization or availability.');
+            }
+            return { text: JSON.stringify(result.output, null, 2) };
+        },
+    };
+}
+//# sourceMappingURL=site-guide-resource.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Model Context Protocol adapters: server config schema and IO, an MCP client, and agent-side MCP server installation.",
   "license": "Apache-2.0",
   "repository": {
@@ -83,11 +83,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.4.2"
+    "@jini-ai/core": "^0.4.3"
   },
   "peerDependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@jini-ai/platform": "^0.5.1",
+    "@jini-ai/platform": "^0.5.3",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependenciesMeta": {
@@ -104,8 +104,8 @@
   "devDependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/core": "^0.4.2",
-    "@jini-ai/platform": "^0.5.2"
+    "@jini-ai/core": "^0.4.3",
+    "@jini-ai/platform": "^0.5.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",