@jini-ai/mcp 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @jini-ai/mcp
 
+## 0.4.2
+
+### Patch Changes
+
+- Tovu clean-up release (2026-10-08): code Tovu moved into Jini, plus the Jini clean-up (see the commit log since 0.4.1).
+
+## 0.4.1 — 2026-10-06
+
+- The delegated tool gateways send input `{}` when the model omits it or sends `null`, so a no-input call no longer fails before a retry.
+- Internal `@jini-ai/*` runtime dependencies are caret ranges (`workspace:^`) instead of exact pins.
+
 ## 0.4.0 — 2026-10-02
 
 ### BREAKING

package/dist/federation/ports.d.ts

@@ -1,3 +1,28 @@
+/**
+ * @file The typed boundary for OUTBOUND MCP federation: the host daemon acting as a client of
+ * third-party servers. Inbound MCP injection hands an agent access to the host's own catalog;
+ * outbound federation accepts another party's tool surface, so its trust question is different.
+ *
+ * Why a declared port rather than `@modelcontextprotocol/sdk`: the SDK is not a dependency and
+ * would add a transitive tree to the boot path for a small JSON-RPC surface. A real adapter and
+ * a memory double share one interface instead.
+ *
+ * Layered seams are deliberate. McpSessionPort is the outer seam for trust and registration tests
+ * without protocol I/O. McpStdioChannel and McpHttpExchange are the inner seams, so the real
+ * client's framing, handshake, pagination, cancellation and timeouts run against scripted bytes.
+ * A fake at the outer seam alone would test the fake, which would not satisfy the constraint of
+ * exercising protocol behavior without a live third-party server. Both transports share protocol
+ * logic above those seams; adding a hosted transport does not redesign the federation boundary.
+ *
+ * All remote names, descriptions, schemas, annotations and results are untrusted input. These
+ * declarations type them; trust.ts vets them before they reach a registry or model.
+ */
+/**
+ * Remote behavior hints are self-declared by the party being classified. A host's native risk
+ * catalog refuses to let a tool downgrade its own risk by editing one word; letting a remote
+ * server change its annotations would make the same mistake with a party the host cannot control.
+ * Hints are carried and logged, but trust.ts only lets them make a tool LESS available, never more.
+ */
 export interface RemoteToolAnnotations {
     readonly title?: string | undefined;
     readonly readOnlyHint?: boolean | undefined;

package/dist/federation/ports.js

@@ -1,3 +1,22 @@
+/**
+ * @file The typed boundary for OUTBOUND MCP federation: the host daemon acting as a client of
+ * third-party servers. Inbound MCP injection hands an agent access to the host's own catalog;
+ * outbound federation accepts another party's tool surface, so its trust question is different.
+ *
+ * Why a declared port rather than `@modelcontextprotocol/sdk`: the SDK is not a dependency and
+ * would add a transitive tree to the boot path for a small JSON-RPC surface. A real adapter and
+ * a memory double share one interface instead.
+ *
+ * Layered seams are deliberate. McpSessionPort is the outer seam for trust and registration tests
+ * without protocol I/O. McpStdioChannel and McpHttpExchange are the inner seams, so the real
+ * client's framing, handshake, pagination, cancellation and timeouts run against scripted bytes.
+ * A fake at the outer seam alone would test the fake, which would not satisfy the constraint of
+ * exercising protocol behavior without a live third-party server. Both transports share protocol
+ * logic above those seams; adding a hosted transport does not redesign the federation boundary.
+ *
+ * All remote names, descriptions, schemas, annotations and results are untrusted input. These
+ * declarations type them; trust.ts vets them before they reach a registry or model.
+ */
 /** Narrows a {@link McpLaunchSpec} to its hosted arm. */
 export function isHttpLaunchSpec(input) {
     return "url" in input.spec;

package/dist/federation/testing/adapter.memory.d.ts

@@ -50,16 +50,17 @@ export declare class InMemoryMcpSession implements McpSessionPort {
     constructor({ tools }: {
         tools: readonly RemoteToolDescriptor[];
     }, options?: {
-        /** Defaults to echoing the call back, which is enough for most wiring assertions. */
+        /** Defaults to echoing the call back, which is enough for most wiring assertions.
+         * The injected remote receives the same optional cancellation object as a real session. */
         onCall?: ((required: {
             name: string;
             args: Record<string, unknown>;
-        }) => RemoteToolResult | Promise<RemoteToolResult>) | undefined;
+        }, options?: McpToolCallOptions) => RemoteToolResult | Promise<RemoteToolResult>) | undefined;
         /** Overrides `listTools` wholesale, for the "the remote is down at connect time" cases. */
         onListTools?: (() => Promise<RemoteToolDescriptor[]>) | undefined;
     });
     listTools(): Promise<RemoteToolDescriptor[]>;
-    callTool(request: McpToolCallRequiredArgs, _options?: McpToolCallOptions): Promise<RemoteToolResult>;
+    callTool(request: McpToolCallRequiredArgs, options?: McpToolCallOptions): Promise<RemoteToolResult>;
     close(_required: Record<string, never>): Promise<void>;
 }
 /** One JSON-RPC message the fake channel received from the client under test. */

package/dist/federation/testing/adapter.memory.js

@@ -51,9 +51,10 @@ export class InMemoryMcpSession {
             return this.listToolsBehaviour();
         return [...this.tools];
     }
-    async callTool(request, _options = {}) {
+    async callTool(request, options = {}) {
         this.calls.push({ name: request.name, arguments: request.arguments });
-        return this.handler({ name: request.name, args: request.arguments });
+        // The injected remote must see cancellation too, so wiring tests can exercise the real ABI.
+        return this.handler({ name: request.name, args: request.arguments }, options);
     }
     async close(_required) {
         this.closed = true;

package/dist/federation/testing/tool-approvals.memory.js

@@ -30,6 +30,14 @@ export function createInMemoryConversationToolApprovalStore(_required) {
         async has(key) {
             return rows.get(keyOf(key)) === key.fingerprint;
         },
+        async hasIdentity(key) {
+            for (const [encoded, fingerprint] of rows) {
+                const [, principalId, connectionId, toolName] = JSON.parse(encoded);
+                if (principalId === key.principalId && connectionId === key.connectionId && toolName === key.toolName && fingerprint === key.fingerprint)
+                    return true;
+            }
+            return false;
+        },
         async grant({ key }) {
             rows.set(keyOf(key), key.fingerprint);
         },

package/dist/federation/tool-approvals.d.ts

@@ -89,6 +89,9 @@ export interface ConversationToolApprovalKey {
 export interface ConversationToolApprovalStore {
     /** True only for this conversation AND this person AND this exact fingerprint. */
     has(key: ConversationToolApprovalKey): Promise<boolean>;
+    /** Native escalation consent can outlive the invoking chat, while remaining person/identity bound.
+     * Hosts namespace connectionId by workspace and behavior; deletion of all granting chats revokes it. */
+    hasIdentity?(key: Omit<ConversationToolApprovalKey, "conversationId">): Promise<boolean>;
     grant(input: {
         key: ConversationToolApprovalKey;
         grantedAt: string;

package/dist/index.d.ts

@@ -1,180 +1,9 @@
 /**
  * @module @jini-ai/mcp
- * Public barrel for the MCP (Model Context Protocol) domain. External code
- * imports MCP capabilities only from here — never from a subdirectory — so the
- * internal split (`core` kernel + `client` / `agent-install` concerns) can move
- * without touching consumers.
- *
- * Re-exports are explicit and named (no `export *`) so the public surface is
- * visible here and name collisions surface at build time.
-
- * Archived provenance rationale:
- * ## What was dropped (and why)
- *
- * - **`live-artifacts/` (entire subdir)** — the OD per-run "live artifacts" MCP
- *   tool surface. An OD-product feature, out of scope per the port brief.
- * - **The `od mcp` stdio server** in `client/client.ts` — `runMcpStdio`,
- *   `TOOL_DEFS`, `handleMcpToolCall`, and every tool handler (`get_artifact`,
- *   `create_project`, `start_run`, project/active-context resolution, studio deep
- *   links, run polling, …). This is not a generic MCP client: it is an
- *   OD-product MCP **server** hardwired to Open Design's REST API
- *   (`/api/projects`, `/api/skills`, `/api/design-systems`, `/api/runs`, …) and
- *   concepts (design systems, skills, plugins, artifacts, runs, studio, the
- *   `od://` resource scheme). It also imports the OD-only `@open-design/contracts`
- *   package (`buildProjectRawFileUrl`), the OD daemon-internal
- *   `../../artifacts/create.js`, and the `@modelcontextprotocol/sdk` — none of
- *   which exist in this repo. Faithfully porting it would mean importing OD
- *   product surface, so it was dropped and only its generic primitives salvaged.
- * - **`MCP_TEMPLATES` catalog + template types + `templateId`** in `config.ts` —
- *   a large, design-tool-tilted curated catalog of third-party MCP servers with
- *   OD marketing prose. Zero functional coupling; dropped for neutrality (same
- *   rationale `@jini/sqlite` used to drop the OD "templates" table).
- *
- * ### The `list_agents` decision
- *
- * Investigated before building anything, per the task brief. `@jini/agent-runtime`'s
- * barrel (`packages/agent-runtime/src/index.ts` → `export * from './registry.js'`)
- * already exports `AGENT_DEFS: RuntimeAgentDef[]` — the exact static, in-memory
- * list of every registered agent def (`registry.ts`'s `BASE_AGENT_DEFS`, 24
- * entries). `RuntimeAgentDef` has plain `id`/`name` fields (plus a large surface
- * of CLI-spawn internals: `bin`, `buildArgs`, `env`, `listModels`, etc. — no
- * `available`/live-detection field at all). No HTTP projection of this list
- * existed anywhere in `packages/http/src/*.ts` before this pass. Building
- * `GET /api/agents` returning `{agents: [{id, name}]}` needed no design judgment
- * call beyond "project the two safe fields" — no timeout/caching/probing
- * decisions, unlike OD's own `list_agents` (`listAgents`, mcp.ts:1034-1057),
- * which filters on a *live-detected* `available: boolean` field (OD's
- * `/api/agents` route actually probes each agent binary for installation/version
- * at request time — a real design decision this pass deliberately did not need
- * to make, since Jini has no such probing route or field to project). So it was
- * built: `packages/http/src/agents.ts`'s `agentListRoute` (`GET /api/agents`,
- * `AgentsHttpDeps.listAgents: () => readonly {id, name}[]` injected — DI,
- * matching `daemon-status.ts`/`active-context.ts`'s convention, so `@jini/http`
- * does not take on a new `@jini/agent-runtime` package dependency for a
- * two-field projection) plus `@jini/mcp`'s `list_agents` tool
- * (`server/tools/run-tools.ts`) proxying it. OD's `includeUnavailable` flag and
- * per-agent `installUrl`/`modelsCount` enrichment were **not** ported — those
- * exist only because OD's route does live probing, which this pass's route does
- * not attempt.
- *
- * ### What was explicitly excluded (and why)
- *
- * Per the task brief, only the mechanism plus tools mapping to real kernel
- * primitives were ported. The other 13 of OD's 18 `TOOL_DEFS` were **not**
- * ported — all are OD's project/file/artifact/skill/plugin model, none of which
- * exists in the Jini kernel (extraction-plan §2.1's "no Project, Conversation,
- * Brand, DesignSystem, Plugin/marketplace, or Automation noun" holds here
- * exactly as it did for `@jini/cli`'s own `mcp` row):
- * `list_projects`, `get_artifact`, `get_project`, `get_file`, `search_files`,
- * `list_files`, `create_artifact`, `write_file`, `delete_file`, `delete_project`,
- * `create_project`, `list_skills`, `list_plugins`. Also not ported: the
- * `ListResourcesRequestSchema`/`ReadResourceRequestSchema` resource surface
- * (`od://focus/active`, `od://skills/...`, `od://design-systems/...` — resources
- * require a skill/design-system store this kernel doesn't have), the studio
- * deep-link builder (`buildStudioUrl`, `getDefaultConversationId`,
- * `getWebBaseUrl`), the project-name-resolution cache (`resolveProjectId`,
- * `fetchProjectList`, `resolveProjectArg`), and the SSE-transcript reassembly
- * (`fetchRunAgentMessage`) — every one of these exists only in service of a
- * dropped tool.
- *
- * ### Design decision: the hosting-mechanism shape
- *
- * `createMcpToolServer({name, version, tools, resolveBaseUrl, instructions?,
- * idleMs?, fetchImpl?, stdin?, stdout?, createServer?, createTransport?})`
- * returns `{run(): Promise<void>}`. Construction (tool-name-uniqueness
- * validation via `buildToolIndex`) is synchronous and side-effect-free; all I/O
- * — resolving the daemon URL, connecting the transport, serving requests —
- * happens in `run()`. This is genuinely new kernel-adjacent surface (a new
- * package capability, not a file port), justified per extraction-plan §7's
- * two-consumer rule by the user's explicit request plus the stated expectation
- * that Zana/Open-Marketing will each want their own product-specific MCP
- * server built on the same hosting mechanism later — so the mechanism accepts
- * an arbitrary, caller-registered `McpToolDef[]`, not the 3-5 tools this pass
- * ships as its first real, working example.
- *
- * `McpServerLike`/`McpTransportLike` (in `tool-server.ts`) are narrow structural
- * interfaces covering only what this module calls on a `Server` instance
- * (`setRequestHandler`, `connect`) and a transport (`onmessage`, `onclose`,
- * `close`) — not literal re-exports of the SDK's own types, which can't be
- * satisfied by a plain object (the SDK's `Server` class has private fields, so
- * it's nominally, not structurally, typed). The default `createServer`/
- * `createTransport` factories construct the real SDK classes and cast through
- * `unknown` to these narrower interfaces (the same `as unknown as X` pattern
- * `core/oauth.ts` already uses to bridge undici's types); a caller may override
- * either factory to inject a test double. This is what makes `run()`'s full
- * orchestration — activity wrapping, message/close composition, the stdin-close
- * race, idle-triggered shutdown — deterministically unit-testable without a
- * real subprocess or real timers (see `tool-server.test.ts`), while one
- * dedicated test (`'wires the real @modelcontextprotocol/sdk Server +
- * StdioServerTransport when no factories are injected'`) still exercises the
- * true default path end-to-end with real `node:stream` `PassThrough` streams,
- * proving the DI seam isn't hiding a real-SDK integration bug.
- *
- * **Why `daemon-client.ts` is not `@jini/cli`'s `getJsonFromDaemon`/
- * `postJsonToDaemon`.** The architectural brief called for reusing
- * `@jini/cli`'s already-hardened daemon-fetch helpers "the way
- * `packages/cli/src/run-command.ts` already does." Checked directly: those two
- * functions map every failure — network-unreachable, non-2xx, oversized
- * response — onto `process.exit()` (via `exitWithStructuredError`), which is
- * correct for a one-shot CLI invocation but fatal for a long-lived stdio MCP
- * server, where a single failed tool call must return an `{isError:true}` MCP
- * result and the process must keep serving the next call. Routing around this
- * by injecting an `exit` callback that throws instead of exiting was considered
- * and rejected: it would require also capturing/re-parsing whatever
- * `postJsonToDaemon` had already written through its `write` callback to
- * reconstruct an error message, which is more convoluted than porting OD's own
- * already-throw-based `getJson`/`postJson` mechanism with the same bounded-I/O
- * hardening added. What **is** reused directly from `@jini/cli` (both pure,
- * non-`process.exit` functions): `sanitizeUntrustedText` (redacts daemon-
- * supplied error text before it reaches an MCP result) and, per the
- * architecture note about `daemon-url.ts`, `resolveDaemonUrl`/
- * `sanitizeDaemonUrlForDisplay` are available for a caller's `resolveBaseUrl`
- * implementation to use directly (this package does not re-wrap them — a
- * caller passes `() => resolveDaemonUrl({...})` straight into
- * `createMcpToolServer`'s `resolveBaseUrl` option; no `packages/mcp`-local
- * daemon-URL-resolution equivalent was built, since one already exists and nothing
- * about MCP's use case differs from a CLI command's). This cross-import
- * (`@jini/mcp` -> `@jini/cli`) is allowed by `scripts/check-engine-boundaries.ts`'s
- * R7 rule: R7 only restricts a **locked** package (the extraction-plan §3
- * fourteen) importing an **unlocked** one below `"stable"` status; `@jini/mcp`
- * is itself unlocked (`UNLOCKED.md`), so it importing the locked, stable
- * `@jini/cli` package is unrestricted. Confirmed via `pnpm guard` after wiring
- * the dependency (see below) — zero violations.
- *
- * No SSRF hardening (`assertSafePublicUrl`/`createValidatingLookup`, the
- * pattern `core/oauth.ts` uses for its own outbound fetches) was added to
- * `daemon-client.ts` — deliberately: `assertSafePublicUrl` actively *rejects*
- * loopback/private addresses, which is exactly where a real daemon lives. The
- * daemon URL here is a caller-resolved, typically-loopback target the user
- * already trusts enough to run (the same trust boundary `@jini/cli/http.ts`
- * already accepts for the identical "fetch my own daemon" concern), not an
- * attacker- or remote-metadata-controlled URL the way an external MCP server's
- * OAuth endpoints are.
- *
- * ### `daemonCallOptions(ctx)` — why a helper for two fields
- *
- * Nine call sites across `tools/` and `resources/` each wrote `{ fetchImpl: ctx.fetchImpl }` inline. Adding
- * a second field that must travel with the first creates a failure mode that is *not* a compile error: miss
- * one site and that single tool 401s while its neighbours keep working, which reaches a user as "some of
- * these tools just don't do anything". Every site now routes through one mapping, so a newly added tool is
- * authenticated by construction.
- *
- * The guarantee is a test rather than a convention. `server/__tests__/auth-propagation.test.ts` enumerates
- * the **real** registries (`RUN_TOOLS`, `TOOL_CATALOG_TOOLS`, `createExecuteDelegatedToolTool`,
- * `KERNEL_RESOURCES` — 8 tools + 1 resource), drives each handler through a spy `fetch`, and asserts the
- * header on every request each one makes; a matching pass asserts **no** `Authorization` key at all when no
- * credential was issued. It also asserts the surface list itself, so emptying or renaming a registry cannot
- * make the loops vacuously pass.
- *
- * That test was verified to actually catch the bug it exists for: reverting one call site to the inline form
- * fails it, naming the offending tool and URL.
- *
- * No transport change was needed — `daemon-client.ts`'s `DaemonRequestOptions` already carried `headers`.
- *
- * **Verified, personally, this session**: `pnpm --filter @jini-ai/mcp run typecheck` clean; full suite
- * **332/332 passing** (18 files), including 21 new propagation tests and 4 new `serve()` credential tests.
- * The pre-existing tool/resource suites, which assert the exact options object passed to the daemon client,
- * pass **unmodified** — the evidence that the no-credential path is byte-identical.
+ * Import capabilities through the public barrel or declared stable subpaths; internal source
+ * paths remain private so the core/client/install/hosting split can move without consumer churn.
+ * Explicit named exports expose the public surface and catch collisions. Core binding, hosting,
+ * daemon I/O and auth propagation are documented at their respective owners below.
  */
 export { inferMcpAuthModeForUrl, sanitizeMcpServer, sanitizeMcpConfig, readMcpConfig, writeMcpConfig, isManagedProjectCwd, buildClaudeMcpJson, buildAcpMcpServers, buildOpenCodeMcpConfigContent, } from './core/index.js';
 export type { McpTransport, McpAuthMode, McpServerConfig, McpConfig, AcpMcpServer, OpenCodeConfigBuildOptions, } from './core/index.js';

package/dist/index.js

@@ -1,184 +1,10 @@
 /**
  * @module @jini-ai/mcp
- * Public barrel for the MCP (Model Context Protocol) domain. External code
- * imports MCP capabilities only from here — never from a subdirectory — so the
- * internal split (`core` kernel + `client` / `agent-install` concerns) can move
- * without touching consumers.
- *
- * Re-exports are explicit and named (no `export *`) so the public surface is
- * visible here and name collisions surface at build time.
-
- * Archived provenance rationale:
- * ## What was dropped (and why)
- *
- * - **`live-artifacts/` (entire subdir)** — the OD per-run "live artifacts" MCP
- *   tool surface. An OD-product feature, out of scope per the port brief.
- * - **The `od mcp` stdio server** in `client/client.ts` — `runMcpStdio`,
- *   `TOOL_DEFS`, `handleMcpToolCall`, and every tool handler (`get_artifact`,
- *   `create_project`, `start_run`, project/active-context resolution, studio deep
- *   links, run polling, …). This is not a generic MCP client: it is an
- *   OD-product MCP **server** hardwired to Open Design's REST API
- *   (`/api/projects`, `/api/skills`, `/api/design-systems`, `/api/runs`, …) and
- *   concepts (design systems, skills, plugins, artifacts, runs, studio, the
- *   `od://` resource scheme). It also imports the OD-only `@open-design/contracts`
- *   package (`buildProjectRawFileUrl`), the OD daemon-internal
- *   `../../artifacts/create.js`, and the `@modelcontextprotocol/sdk` — none of
- *   which exist in this repo. Faithfully porting it would mean importing OD
- *   product surface, so it was dropped and only its generic primitives salvaged.
- * - **`MCP_TEMPLATES` catalog + template types + `templateId`** in `config.ts` —
- *   a large, design-tool-tilted curated catalog of third-party MCP servers with
- *   OD marketing prose. Zero functional coupling; dropped for neutrality (same
- *   rationale `@jini/sqlite` used to drop the OD "templates" table).
- *
- * ### The `list_agents` decision
- *
- * Investigated before building anything, per the task brief. `@jini/agent-runtime`'s
- * barrel (`packages/agent-runtime/src/index.ts` → `export * from './registry.js'`)
- * already exports `AGENT_DEFS: RuntimeAgentDef[]` — the exact static, in-memory
- * list of every registered agent def (`registry.ts`'s `BASE_AGENT_DEFS`, 24
- * entries). `RuntimeAgentDef` has plain `id`/`name` fields (plus a large surface
- * of CLI-spawn internals: `bin`, `buildArgs`, `env`, `listModels`, etc. — no
- * `available`/live-detection field at all). No HTTP projection of this list
- * existed anywhere in `packages/http/src/*.ts` before this pass. Building
- * `GET /api/agents` returning `{agents: [{id, name}]}` needed no design judgment
- * call beyond "project the two safe fields" — no timeout/caching/probing
- * decisions, unlike OD's own `list_agents` (`listAgents`, mcp.ts:1034-1057),
- * which filters on a *live-detected* `available: boolean` field (OD's
- * `/api/agents` route actually probes each agent binary for installation/version
- * at request time — a real design decision this pass deliberately did not need
- * to make, since Jini has no such probing route or field to project). So it was
- * built: `packages/http/src/agents.ts`'s `agentListRoute` (`GET /api/agents`,
- * `AgentsHttpDeps.listAgents: () => readonly {id, name}[]` injected — DI,
- * matching `daemon-status.ts`/`active-context.ts`'s convention, so `@jini/http`
- * does not take on a new `@jini/agent-runtime` package dependency for a
- * two-field projection) plus `@jini/mcp`'s `list_agents` tool
- * (`server/tools/run-tools.ts`) proxying it. OD's `includeUnavailable` flag and
- * per-agent `installUrl`/`modelsCount` enrichment were **not** ported — those
- * exist only because OD's route does live probing, which this pass's route does
- * not attempt.
- *
- * ### What was explicitly excluded (and why)
- *
- * Per the task brief, only the mechanism plus tools mapping to real kernel
- * primitives were ported. The other 13 of OD's 18 `TOOL_DEFS` were **not**
- * ported — all are OD's project/file/artifact/skill/plugin model, none of which
- * exists in the Jini kernel (extraction-plan §2.1's "no Project, Conversation,
- * Brand, DesignSystem, Plugin/marketplace, or Automation noun" holds here
- * exactly as it did for `@jini/cli`'s own `mcp` row):
- * `list_projects`, `get_artifact`, `get_project`, `get_file`, `search_files`,
- * `list_files`, `create_artifact`, `write_file`, `delete_file`, `delete_project`,
- * `create_project`, `list_skills`, `list_plugins`. Also not ported: the
- * `ListResourcesRequestSchema`/`ReadResourceRequestSchema` resource surface
- * (`od://focus/active`, `od://skills/...`, `od://design-systems/...` — resources
- * require a skill/design-system store this kernel doesn't have), the studio
- * deep-link builder (`buildStudioUrl`, `getDefaultConversationId`,
- * `getWebBaseUrl`), the project-name-resolution cache (`resolveProjectId`,
- * `fetchProjectList`, `resolveProjectArg`), and the SSE-transcript reassembly
- * (`fetchRunAgentMessage`) — every one of these exists only in service of a
- * dropped tool.
- *
- * ### Design decision: the hosting-mechanism shape
- *
- * `createMcpToolServer({name, version, tools, resolveBaseUrl, instructions?,
- * idleMs?, fetchImpl?, stdin?, stdout?, createServer?, createTransport?})`
- * returns `{run(): Promise<void>}`. Construction (tool-name-uniqueness
- * validation via `buildToolIndex`) is synchronous and side-effect-free; all I/O
- * — resolving the daemon URL, connecting the transport, serving requests —
- * happens in `run()`. This is genuinely new kernel-adjacent surface (a new
- * package capability, not a file port), justified per extraction-plan §7's
- * two-consumer rule by the user's explicit request plus the stated expectation
- * that Zana/Open-Marketing will each want their own product-specific MCP
- * server built on the same hosting mechanism later — so the mechanism accepts
- * an arbitrary, caller-registered `McpToolDef[]`, not the 3-5 tools this pass
- * ships as its first real, working example.
- *
- * `McpServerLike`/`McpTransportLike` (in `tool-server.ts`) are narrow structural
- * interfaces covering only what this module calls on a `Server` instance
- * (`setRequestHandler`, `connect`) and a transport (`onmessage`, `onclose`,
- * `close`) — not literal re-exports of the SDK's own types, which can't be
- * satisfied by a plain object (the SDK's `Server` class has private fields, so
- * it's nominally, not structurally, typed). The default `createServer`/
- * `createTransport` factories construct the real SDK classes and cast through
- * `unknown` to these narrower interfaces (the same `as unknown as X` pattern
- * `core/oauth.ts` already uses to bridge undici's types); a caller may override
- * either factory to inject a test double. This is what makes `run()`'s full
- * orchestration — activity wrapping, message/close composition, the stdin-close
- * race, idle-triggered shutdown — deterministically unit-testable without a
- * real subprocess or real timers (see `tool-server.test.ts`), while one
- * dedicated test (`'wires the real @modelcontextprotocol/sdk Server +
- * StdioServerTransport when no factories are injected'`) still exercises the
- * true default path end-to-end with real `node:stream` `PassThrough` streams,
- * proving the DI seam isn't hiding a real-SDK integration bug.
- *
- * **Why `daemon-client.ts` is not `@jini/cli`'s `getJsonFromDaemon`/
- * `postJsonToDaemon`.** The architectural brief called for reusing
- * `@jini/cli`'s already-hardened daemon-fetch helpers "the way
- * `packages/cli/src/run-command.ts` already does." Checked directly: those two
- * functions map every failure — network-unreachable, non-2xx, oversized
- * response — onto `process.exit()` (via `exitWithStructuredError`), which is
- * correct for a one-shot CLI invocation but fatal for a long-lived stdio MCP
- * server, where a single failed tool call must return an `{isError:true}` MCP
- * result and the process must keep serving the next call. Routing around this
- * by injecting an `exit` callback that throws instead of exiting was considered
- * and rejected: it would require also capturing/re-parsing whatever
- * `postJsonToDaemon` had already written through its `write` callback to
- * reconstruct an error message, which is more convoluted than porting OD's own
- * already-throw-based `getJson`/`postJson` mechanism with the same bounded-I/O
- * hardening added. What **is** reused directly from `@jini/cli` (both pure,
- * non-`process.exit` functions): `sanitizeUntrustedText` (redacts daemon-
- * supplied error text before it reaches an MCP result) and, per the
- * architecture note about `daemon-url.ts`, `resolveDaemonUrl`/
- * `sanitizeDaemonUrlForDisplay` are available for a caller's `resolveBaseUrl`
- * implementation to use directly (this package does not re-wrap them — a
- * caller passes `() => resolveDaemonUrl({...})` straight into
- * `createMcpToolServer`'s `resolveBaseUrl` option; no `packages/mcp`-local
- * daemon-URL-resolution equivalent was built, since one already exists and nothing
- * about MCP's use case differs from a CLI command's). This cross-import
- * (`@jini/mcp` -> `@jini/cli`) is allowed by `scripts/check-engine-boundaries.ts`'s
- * R7 rule: R7 only restricts a **locked** package (the extraction-plan §3
- * fourteen) importing an **unlocked** one below `"stable"` status; `@jini/mcp`
- * is itself unlocked (`UNLOCKED.md`), so it importing the locked, stable
- * `@jini/cli` package is unrestricted. Confirmed via `pnpm guard` after wiring
- * the dependency (see below) — zero violations.
- *
- * No SSRF hardening (`assertSafePublicUrl`/`createValidatingLookup`, the
- * pattern `core/oauth.ts` uses for its own outbound fetches) was added to
- * `daemon-client.ts` — deliberately: `assertSafePublicUrl` actively *rejects*
- * loopback/private addresses, which is exactly where a real daemon lives. The
- * daemon URL here is a caller-resolved, typically-loopback target the user
- * already trusts enough to run (the same trust boundary `@jini/cli/http.ts`
- * already accepts for the identical "fetch my own daemon" concern), not an
- * attacker- or remote-metadata-controlled URL the way an external MCP server's
- * OAuth endpoints are.
- *
- * ### `daemonCallOptions(ctx)` — why a helper for two fields
- *
- * Nine call sites across `tools/` and `resources/` each wrote `{ fetchImpl: ctx.fetchImpl }` inline. Adding
- * a second field that must travel with the first creates a failure mode that is *not* a compile error: miss
- * one site and that single tool 401s while its neighbours keep working, which reaches a user as "some of
- * these tools just don't do anything". Every site now routes through one mapping, so a newly added tool is
- * authenticated by construction.
- *
- * The guarantee is a test rather than a convention. `server/__tests__/auth-propagation.test.ts` enumerates
- * the **real** registries (`RUN_TOOLS`, `TOOL_CATALOG_TOOLS`, `createExecuteDelegatedToolTool`,
- * `KERNEL_RESOURCES` — 8 tools + 1 resource), drives each handler through a spy `fetch`, and asserts the
- * header on every request each one makes; a matching pass asserts **no** `Authorization` key at all when no
- * credential was issued. It also asserts the surface list itself, so emptying or renaming a registry cannot
- * make the loops vacuously pass.
- *
- * That test was verified to actually catch the bug it exists for: reverting one call site to the inline form
- * fails it, naming the offending tool and URL.
- *
- * No transport change was needed — `daemon-client.ts`'s `DaemonRequestOptions` already carried `headers`.
- *
- * **Verified, personally, this session**: `pnpm --filter @jini-ai/mcp run typecheck` clean; full suite
- * **332/332 passing** (18 files), including 21 new propagation tests and 4 new `serve()` credential tests.
- * The pre-existing tool/resource suites, which assert the exact options object passed to the daemon client,
- * pass **unmodified** — the evidence that the no-credential path is byte-identical.
+ * Import capabilities through the public barrel or declared stable subpaths; internal source
+ * paths remain private so the core/client/install/hosting split can move without consumer churn.
+ * Explicit named exports expose the public surface and catch collisions. Core binding, hosting,
+ * daemon I/O and auth propagation are documented at their respective owners below.
  */
-// The original root-only boundary above describes the initial core/client/server split.
-// Stable public subpaths now also host federation, approvals, stdio, testing, and ask-choice;
-// internal source paths remain private so consumers can follow their declared runtime entry.
 // ── core: config schema + IO ────────────────────────────────────────────────
 export { inferMcpAuthModeForUrl, sanitizeMcpServer, sanitizeMcpConfig, readMcpConfig, writeMcpConfig, isManagedProjectCwd, buildClaudeMcpJson, buildAcpMcpServers, buildOpenCodeMcpConfigContent, } from './core/index.js';
 // ── core: token store ───────────────────────────────────────────────────────

package/dist/server/daemon-client.d.ts

@@ -1,7 +1,6 @@
 /**
- * Thrown for a non-2xx daemon response. The message is unchanged from the plain `Error` this used to
- * be; `status` is what lets a tool tell "this daemon does not serve the route" (404) apart from any
- * other failure instead of pattern-matching the message.
+ * Thrown for a non-2xx daemon response. `status` lets a tool distinguish an unsupported route (404)
+ * from other failures without pattern-matching the public error message.
  */
 export declare class DaemonHttpError extends Error {
     readonly status: number;

package/dist/server/daemon-client.js

@@ -1,30 +1,12 @@
 /**
  * @module @jini-ai/mcp/server/daemon-client
+ * Bounded-I/O JSON GET/POST against a caller-resolved trusted daemon base URL.
+ * A long-lived MCP server must report a failed call and keep serving, so this transport throws
+ * redacted errors for handleToolCall to convert rather than using the CLI transport's process.exit.
+ * Bounded reads, timeouts and redaction follow CR-004/SEC-RB-009.
  *
- * Bounded-I/O JSON GET/POST against a trusted daemon base URL — the transport
- * primitive every proxy tool `createMcpToolServer` hosts is built on
- * (`../client/client.js`'s `createMcpIdleExitController` is the other half of
- * the mechanism; this module is the network half).
- *
- * Deliberately NOT the CLI transport's `getJsonFromDaemon`/`postJsonToDaemon`
- * (`packages/cli/src/http.ts`): those map a failure onto `process.exit`,
- * which is the right contract for a one-shot CLI invocation but wrong here —
- * a stdio MCP server is a long-lived process serving many tool calls, and one
- * failed call must return an MCP `{isError:true}` result and keep serving the
- * next call, not terminate the process. This module ports the same
- * bounded-read / timeout / redaction posture `http.ts` established
- * (CR-004/SEC-RB-009 — see `ADS-memory/reports/code-review/CR-remaining-backend-audit-2026-07-21.md`,
- * `ADS-memory/reports/security/SEC-remaining-backend-audit-2026-07-21.md`) as
- * a throw-based primitive instead: a failed request throws a plain,
- * already-redacted `Error` whose message a tool handler's caller
- * (`handleToolCall` in `./tool-protocol.js`) turns into that MCP error result.
- *
- * No SSRF hardening here: the
- * target is a caller-resolved, typically-loopback daemon the user already
- * trusts enough to run — not an attacker- or server-metadata-controlled
- * remote URL the way a configured external MCP server's OAuth endpoints are.
- * This mirrors the CLI HTTP transport's own posture for the identical "fetch my
- * own daemon" concern (no `assertSafePublicUrl` there either).
+ * This is a trusted, typically-loopback daemon URL, not attacker-controlled server metadata or
+ * an external MCP OAuth endpoint; public-URL SSRF validation is therefore outside this contract.
  */
 import { sanitizeUntrustedText } from '@jini-ai/core/text';
 /** Request deadline. Generous enough for a slow tool call, short enough that a stalled daemon doesn't hang a stdio server turn forever. */
@@ -32,9 +14,8 @@ const DEFAULT_TIMEOUT_MS = 15_000;
 /** Cap on a daemon response body. Comfortably larger than any real status/run envelope, small enough to bound worst-case memory from a hostile/broken daemon. */
 const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 /**
- * Thrown for a non-2xx daemon response. The message is unchanged from the plain `Error` this used to
- * be; `status` is what lets a tool tell "this daemon does not serve the route" (404) apart from any
- * other failure instead of pattern-matching the message.
+ * Thrown for a non-2xx daemon response. `status` lets a tool distinguish an unsupported route (404)
+ * from other failures without pattern-matching the public error message.
  */
 export class DaemonHttpError extends Error {
     status;

package/dist/server/resources/active-resource.d.ts

@@ -3,8 +3,7 @@ import type { McpResourceDef } from '../resource-protocol.js';
  * `jini://active` -> `GET /api/active`. Returns the raw daemon payload as formatted JSON text,
  * unchanged — unlike `getActiveContextTool`, this does not add a conversational hint when
  * `active:false`; a resource is meant to be raw structured data a client attaches to context, not
- * a model-facing tool result, matching the OD origin's own `od://focus/active` handler (which also
- * returned the raw `/api/active` body with no special-casing).
+ * a model-facing tool result.
  */
 export declare const activeContextResource: McpResourceDef;
 /** The full set of kernel resource defs this package ships, ready to pass as `createMcpToolServer`'s `resources` option. */

package/dist/server/resources/active-resource.js

@@ -1,27 +1,8 @@
 /**
  * @module @jini-ai/mcp/server/resources/active-resource
- *
- * The one MCP *resource* this package ships: a read-only pointer to
- * `GET /api/active` (`packages/http/src/active-context.ts`'s `getActiveRoute`)
- * — the same underlying data `../tools/run-tools.js`'s `getActiveContextTool`
- * already proxies as a *tool*. This is not redundant: OD's origin
- * (`apps/daemon/src/mcp.ts`) exposed the identical `/api/active` payload
- * both ways — as the `get_active_context` tool (already ported, see
- * `../tools/run-tools.js`) AND as the `od://focus/active` resource (its
- * `ListResourcesRequestSchema`/`ReadResourceRequestSchema` handlers) —
- * because tools and resources serve different MCP client affordances: a
- * tool is invoked by the model mid-conversation, while a resource can be
- * listed and attached to context by the user/client without any tool call.
- * This module is that second affordance for the same primitive. See
- * `archived provenance ledger`'s 2026-07-21 addition for why the rest of OD's resource
- * surface (`od://skills/...`, `od://design-systems/...`) was NOT ported the
- * same way (both require a Skill/DesignSystem noun this kernel doesn't have).
- *
- * Security posture matches every other tool/resource in this package: no
- * separate authorization mechanism here — whatever `@jini-ai/http-kit`'s
- * same-origin guard / bearer-auth middleware already enforces on
- * `GET /api/active` is the only gate a read of this resource passes
- * through.
+ * Read-only active-context resource over GET /api/active. Tools let the model request data during
+ * a conversation; resources let clients list and attach that data without invoking a tool.
+ * Target-route same-origin and bearer-auth gates remain authoritative, as for the proxy tools.
  */
 import { getDaemonJson } from '../daemon-client.js';
 import { daemonCallOptions } from '../tool-protocol.js';
@@ -29,8 +10,7 @@ import { daemonCallOptions } from '../tool-protocol.js';
  * `jini://active` -> `GET /api/active`. Returns the raw daemon payload as formatted JSON text,
  * unchanged — unlike `getActiveContextTool`, this does not add a conversational hint when
  * `active:false`; a resource is meant to be raw structured data a client attaches to context, not
- * a model-facing tool result, matching the OD origin's own `od://focus/active` handler (which also
- * returned the raw `/api/active` body with no special-casing).
+ * a model-facing tool result.
  */
 export const activeContextResource = {
     uri: 'jini://active',

package/dist/server/tool-server.d.ts

@@ -1,28 +1,10 @@
 /**
  * @module @jini-ai/mcp/server/tool-server
- *
- * `createMcpToolServer` — the generic stdio MCP server hosting mechanism.
- * Ported from the *mechanism* of OD's `apps/daemon/src/mcp.ts` `runMcpStdio`
- * (idle-exit lifecycle, `Server` + `StdioServerTransport` wiring, holding the
- * process open until stdin closes) with the OD-specific parts — the
- * hardcoded 18-tool `TOOL_DEFS`, the `od://` resource scheme, the
- * project/skill/plugin `instructions` prose — replaced by a caller-supplied,
- * bounded, explicit `tools: readonly McpToolDef[]` list. A caller is the
- * *first* user of this mechanism, not the only one it will ever support (see
- * `archived provenance ledger`'s 2026-07-21 addition for the full design-decision note).
- *
- * `tools` capability is always advertised (`capabilities: {tools: {}}`).
- * `resources` capability (`ListResourcesRequestSchema`/
- * `ReadResourceRequestSchema`, mirroring the tools wiring one section down)
- * is advertised only when the caller supplies at least one entry in the
- * optional `resources` option — a 2026-07-21 addition once this package
- * shipped its first genuinely portable resource (`../resources/
- * active-resource.js`'s `jini://active`, see that file's module doc and
- * `archived provenance ledger`'s 2026-07-21 addition for why the *rest* of OD's resource
- * surface — `od://skills/...`, `od://design-systems/...` — still has no
- * kernel equivalent and stays unported). A caller passing no `resources`
- * gets the exact same `capabilities: {tools: {}}`-only server this module
- * always produced.
+ * Generic stdio hosting for an explicit caller-supplied tool list. Construction validates unique
+ * names synchronously without I/O; run resolves the daemon URL, connects and serves until closure.
+ * Tools capability is always advertised; resources only when nonempty resources are supplied.
+ * Narrow object-shaped server/transport ports permit DI fakes without requiring SDK class instances
+ * with nominal private fields; default adapters translate those contracts to the real SDK.
  */
 import type { Readable, Writable } from 'node:stream';
 import type { McpTransportLike } from './ports.js';

package/dist/server/tool-server.js

@@ -5,7 +5,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import { createMcpIdleExitController } from '../client/client.js';
 import { buildResourceIndex, handleResourceRead, resourcesToList } from './resource-protocol.js';
 import { buildToolIndex, handleToolCall, toolsToList } from './tool-protocol.js';
-/** Auto-exit an idle server after this long with no tool activity — same ceiling the OD origin used for its own stdio MCP server. */
+/** Auto-exit an idle server after this long without tool activity. */
 const DEFAULT_IDLE_MS = 30 * 60 * 1000;
 // SDK objects remain behind these adapters; hosts implement the object-shaped ports above.
 function defaultCreateServer({ info, options }) {

package/dist/server/tools/delegated-tool.js

@@ -149,7 +149,10 @@ function createDelegatedGateway(variant, { runId }, options) {
                 runId,
                 toolUseId: generateToolUseId({}),
                 toolId: toolId,
-                input: args.input,
+                // The schema tells the model to omit `input` for a tool that takes none, but most tool
+                // handlers refuse an absent input ("input must be an object"). Sending `{}` makes the
+                // schema's promise true instead of costing a red failed call and a retry.
+                input: args.input ?? {},
                 ...(variant.requireReadOnly === undefined ? {} : { requireReadOnly: variant.requireReadOnly }),
             };
             const data = await postDaemonJson({ baseUrl: ctx.baseUrl, route: '/api/delegated-tool-calls', body: body }, {

package/dist/server/tools/run-tools.js

@@ -1,17 +1,8 @@
 /**
  * @module @jini-ai/mcp/server/tools/run-tools
- *
- * The first real, concrete `McpToolDef`s hosted by `createMcpToolServer`
- * (`../tool-server.js`) — a proxy over `@jini-ai/http-kit`'s already-gated `Run`
- * transport (`packages/http/src/runs.ts`) plus the generic active-resource
- * channel (`packages/http/src/active-context.ts`) and the agent-def listing
- * (`packages/http/src/agents.ts`). Each tool's `handler` does nothing but
- * validate its own arguments and proxy a single HTTP call via
- * `../daemon-client.js` — no separate authorization mechanism, no caching,
- * no state: whatever `@jini-ai/http-kit`'s same-origin guard / bearer-auth
- * middleware already enforces on the target route is the only gate a call
- * here passes through (see `archived provenance ledger`'s 2026-07-21 addition for the
- * full origin-mapping and what was deliberately not ported).
+ * Proxy tools for runs, active context and agent definitions. Each validates its arguments and
+ * delegates a single request to daemon-client; target-route same-origin and bearer-auth gates
+ * remain authoritative. See daemonCallOptions for shared auth and cancellation propagation.
  */
 import { getDaemonJson, postDaemonJson } from '../daemon-client.js';
 import { daemonCallOptions, requireString } from '../tool-protocol.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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,10 +83,29 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@jini-ai/core": "^0.4.2"
+  },
+  "peerDependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@jini-ai/platform": "^0.5.1",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "peerDependenciesMeta": {
+    "@cfworker/json-schema": {
+      "optional": true
+    },
+    "@jini-ai/platform": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@jini-ai/core": "0.4.0",
-    "@jini-ai/platform": "0.5.0"
+    "@jini-ai/core": "^0.4.2",
+    "@jini-ai/platform": "^0.5.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/serve.js",