@lenso/mcp 0.2.1 → 0.4.0

package/README.md

@@ -1,11 +1,158 @@
-# Local MCP adapter
+# MCP adapters
 
-`@lenso/mcp` is an optional local stdio adapter for **existing, explicitly
-declared Lenso operations**. It uses the official MCP SDK's `Server` and
-`StdioServerTransport`. It does not start a remote server, accept credentials,
-implement business handlers, load Engine config, or expose a shell.
+`@lenso/mcp` projects **explicitly selected existing Operations**, never inferred
+service methods. It offers a borrowed runtime adapter, dedicated local stdio,
+and an opt-in authenticated Fetch Streamable HTTP entry. HTTP starts no listener
+and does not change host logging. No business handlers, OAuth authorization
+server, shell, Agent loop, tasks, or durable cancellation are supplied.
 
-## Trusted launch configuration
+## Borrow one running app
+
+```ts
+import { createMcpAdapter, serveBorrowedStdio } from "@lenso/mcp";
+import { selectManageOperations } from "@lenso/manage";
+
+const shared = {
+  running: app, // already started by its owner
+  plugins: [notes], // exact installed instances
+  operations: selectManageOperations(notesManage, ["read", "write"]),
+  canList: (operation, request) => policy.canSee(request.identity, operation),
+  authorize: (operation, request) => policy.canInvoke(request.identity, operation),
+  binding: (_operation, _input, request) => ({
+    context: { identity: request.identity, requestId: request.requestId, signal: request.signal },
+  }),
+};
+const adapter = await createMcpAdapter(shared);
+// adapter.listTools({identity, requestId, signal})
+// adapter.callTool(discoveredName, input, {identity, requestId, signal})
+await adapter.close(); // app remains usable; its owner alone stops it
+```
+
+`running` is the existing Engine `OperationRuntime`; `binding` returns existing
+`OperationBoundOptions`, including confirmation/approval callbacks where required.
+It must match the real service's second parameter (`context: true`). The request
+context is trusted entry data, not a new registration or actor-in-JSON protocol.
+Every call rechecks both visibility and invocation permission. The ordinary
+service still enforces its tenant/object/owner rules. Manage/`createAgentTools`
+are the canonical schema/metadata source; all selected schemas must convert to
+SDK-compatible object schemas before readiness, including currently hidden tools.
+
+The borrowed adapter prepares one immutable Manage selection for its lifetime.
+Discovery, invocation policies and bindings receive the same frozen declaration
+snapshots, retaining exact plugin/schema/function identities. Do not key policies
+by the original declaration object's identity; use the exact plugin and declared
+method. Original declaration edits do not change admission or dispatch. Replace
+the adapter when changing its selection. Existing `operation_N` tool names remain
+entry-local, translated internally to Manage's selection-scoped opaque keys.
+Close revokes admission, waits for actual work to drain, then releases the
+selection's runtime references; policy closures retain any resources they capture.
+
+For a **dedicated local process**, replace the adapter creation above with:
+
+```ts
+const stdio = await serveBorrowedStdio({ ...shared, identity: trustedLaunchIdentity });
+// On shutdown await stdio.close(), then let the entry owner stop app.
+```
+
+It reuses that app for all calls, reserves stdio process ownership, routes console
+logs to redacted stderr, and drains on EOF/SIGINT/SIGTERM. Start the app with a
+stderr logger: the adapter cannot redirect logs emitted before it starts.
+Never embed this stdio owner in a general-purpose HTTP host.
+
+## Explicit HTTP mount and identity
+
+```ts
+import { createHttpMcp } from "@lenso/mcp";
+const mcp = await createHttpMcp({
+  ...shared,
+  resource: "https://api.example.com/mcp",
+  authorizationServers: ["https://idp.example.com"],
+  requiredScopes: ["mcp:use"],
+  allowedOrigins: ["https://trusted-client.example.com"], // [] denies present Origins
+  verifyToken: hostIdentityProvider.verifyMcpAccessToken,
+});
+// Mount both /mcp and /.well-known/oauth-protected-resource/mcp:
+// host Fetch router delegates these paths to mcp.fetch(request).
+// Host owns its existing listener, TLS, CORS and reverse-proxy configuration.
+```
+
+`verifyToken(token, signal)` is mandatory. Inject the host's real OAuth/OIDC
+signature verifier or token introspection client; decoding a JWT is not
+verification. For JWT providers, a host-installed `jose` verifier can use
+`createRemoteJWKSet` and `jwtVerify` with a fixed issuer, this resource audience,
+and an explicit algorithm allowlist. Require `exp`; honor `nbf`, provider
+revocation/current grants, and abortable verification. Map the **verified**
+subject to the host's tenant and Lenso business identity. Do not trust a
+client-selected tenant claim without the provider/host membership policy.
+When services require an `@lenso/auth` Actor, retain the original verified Actor
+reference in an identity extension such as `identity.actor` and bind that exact
+reference. A copied MCP identity is not an Auth Actor or permission grant.
+
+Return `McpIdentity`: `{subject, tenant, issuer, audience: string[], scopes:
+string[], expiresAt}` (Unix seconds), optionally extending it with verified
+business evidence. The adapter rechecks issuer, resource audience, expiry and
+required scopes on **every** protected request, including notifications and
+DELETE. `canList`, `authorize` and service policy handle current business grants;
+discovery is not call permission. Configure the issuer string exactly, including
+any provider-required trailing slash. Production verification/revocation remains
+the host's responsibility, not the example's deterministic fixture verifier.
+
+Missing/invalid credentials return 401 and a Bearer `resource_metadata` challenge;
+missing required scopes return 403 with `insufficient_scope`. Public RFC 9728
+metadata advertises the configured resource and authorization servers. Tokens
+are neither forwarded to services nor to a different resource. Session IDs never
+authenticate. Sessions and rate buckets bind issuer/subject/tenant/resource;
+foreign owners receive 404 and grants are not cached in sessions.
+
+Only canonical configured Host/Origin values are accepted. HTTPS is required
+except on loopback; forwarded headers are not trusted. A proxy host must present
+the canonical public Request URL through its own trusted routing. The adapter
+starts no second listener; an independent listener must explicitly bind loopback
+unless the host deliberately configures remote exposure.
+
+## Borrowed-entry bounds and protocol support
+
+Defaults: four admitted calls/discoveries (no queue), 30s request timeout,
+256 KiB business input/catalog, 1 MiB business result, 1 MiB HTTP frame, and
+2 MiB + 4 KiB complete HTTP response (including cumulative internal stream data).
+HTTP additionally admits 32 requests, 128 sessions, 5-minute idle expiry, and
+120 requests/minute per identity/tenant with at most 1024 rate buckets.
+Trusted options can change these budgets; output/HTTP error budgets must fit a
+256-byte fixed diagnostic. HTTP's outer verification/body/transport deadline is
+the request timeout plus 1s. Expired sessions/buckets are swept on ingress.
+
+Cancellation and timeout reach binding signals; only a host-bound cooperative
+service can interrupt actual work. Noncooperative work retains its concurrency
+slot until settlement. `close()` stops admission, aborts owned request signals,
+drains actual work and releases protocol resources; it is idempotent and never
+calls `app.stop()`. A hanging noncooperative service/verifier can prolong drain.
+Neither cancellation nor a lost response promises rollback or safe retry.
+HTTP disconnect alone is deliberately not an MCP cancellation notification.
+
+Protocol failures use fixed SDK MCP errors. Validation, authorization, business
+failure, cancellation, timeout, busy/closed and size errors have fixed bounded
+tool diagnostics; arbitrary thrown text, stacks, input and credentials are omitted.
+Engine's finite JSON/redaction policy remains in force, not a sandbox.
+
+Official SDK **1.32.1** remains exactly pinned. Official-client tests verify
+`2025-11-25` and `2025-03-26` Streamable HTTP, plus existing stdio. SDK owns
+negotiation, messages, session IDs and notification validation. Public HTTP
+responses are finite JSON; GET returns 405 (no standalone SSE), DELETE terminates
+sessions. No HTTP+SSE legacy endpoint, replay/event store, progress, resources,
+prompts, elicitation or task capability is claimed.
+
+Two version-specific mitigations use SDK public APIs: its finite POST SSE
+transport is consumed within a budget and normalized to JSON because 1.32.1
+JSON mode retains completed stream resolvers; entry-scoped cancellation handlers
+handle valid IDs `0`/`""` and emit finite replies so cancellation does not retain
+HTTP waiters. Regression tests inspect retained SDK state, cancellation and
+escape-heavy JSON. No SDK private state is patched.
+
+See the [offline host example](../../examples/mcp-host/README.md) for copyable
+workspace commands and discovery/multiple read/write calls with one app.
+These new exports are source-workspace changes, not proof of registry publication.
+
+## Existing trusted local launch (unchanged)
 
 Install the optional package in the application and create a dedicated entry:
 
@@ -56,7 +203,7 @@ processes with separately authorized credentials when local callers require
 identity isolation. A developer who can change application code/config or use
 the raw DB has administrative authority outside the tool surface; this adapter
 does not grant that authority to its client. Remote credentials, audiences and
-scopes require a separately designed trusted ingress, not this stdio entry.
+scopes belong to the explicitly enabled HTTP entry, never this stdio entry.
 
 Successful tool content contains one text block with Engine's deterministic,
 redacted JSON result. No output schema is fabricated. Undefined, cyclic,
@@ -129,13 +276,15 @@ Primary sources checked for this implementation:
 
 This package deliberately uses the mature official monolithic v1 SDK. It does
 **not** claim implementation of the newer 2026-07-28 stateless protocol or
-v2-only features. No resources, prompts, tasks, elicitation, remote auth, or
-credentials are advertised.
+v2-only features. No resources, prompts, tasks or elicitation are advertised.
+HTTP uses the [2025-11-25 authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)
+and RFC 9728 protected-resource metadata, not an application login endpoint.
 
 ## Development
 
 The integration owner installs dependencies and owns the workspace lockfile.
-Rebuild `@lenso/core`, `@lenso/engine`, and `@lenso/cli` before consuming their exports.
+Rebuild `@lenso/core`, `@lenso/engine`, `@lenso/web`, `@lenso/auth`,
+`@lenso/manage`, and `@lenso/cli` before consuming their exports.
 Then run from this package:
 
 ```sh

package/dist/adapter.d.ts

@@ -0,0 +1,29 @@
+import type { Plugin } from "@lenso/core";
+import { type Operation, type OperationBoundOptions, type OperationRuntime } from "@lenso/engine/operations";
+import { type CallToolResult, type Tool } from "@modelcontextprotocol/sdk/types.js";
+export interface McpRequestContext<I> {
+    readonly identity: I;
+    readonly requestId: string;
+    readonly signal: AbortSignal;
+}
+export interface McpAdapterOptions<I, O extends Operation = Operation> {
+    readonly running: OperationRuntime;
+    readonly plugins: readonly Plugin<unknown>[];
+    readonly operations: readonly O[];
+    readonly canList: (operation: O, request: McpRequestContext<I>) => boolean | Promise<boolean>;
+    readonly authorize: (operation: O, request: McpRequestContext<I>) => boolean | Promise<boolean>;
+    readonly binding: (operation: O, input: unknown, request: McpRequestContext<I>) => OperationBoundOptions<NoInfer<O>> | Promise<OperationBoundOptions<NoInfer<O>>>;
+    readonly maxInputBytes?: number;
+    readonly maxOutputBytes?: number;
+    readonly maxCatalogBytes?: number;
+    readonly maxConcurrentCalls?: number;
+    readonly requestTimeoutMs?: number;
+}
+/** Borrows only runtime capabilities, never app start/stop ownership. */
+export declare function createMcpAdapter<I, O extends Operation = Operation>(options: McpAdapterOptions<I, O>): Promise<Readonly<{
+    listTools(request: McpRequestContext<I>): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(name: string, input: unknown, request: McpRequestContext<I>): Promise<CallToolResult>;
+    close(): Promise<void>;
+}>>;

package/dist/borrowed-stdio.d.ts

@@ -0,0 +1,13 @@
+import type { Operation } from "@lenso/engine/operations";
+import { type McpAdapterOptions } from "./adapter";
+export interface BorrowedStdioOptions<I, O extends Operation = Operation> extends McpAdapterOptions<I, O> {
+    /** Trusted, fixed launch identity, never supplied by tool arguments. */
+    readonly identity: I;
+    readonly maxFrameBytes?: number;
+}
+/** Shared with other dedicated stdio entries; HTTP must not acquire this latch. */
+export declare function acquireStdioOwnership(): () => void;
+/** Borrows the running application; the host alone owns app.stop(). */
+export declare function serveBorrowedStdio<I, O extends Operation = Operation>(options: BorrowedStdioOptions<I, O>): Promise<{
+    close(): Promise<void>;
+}>;

package/dist/http.d.ts

@@ -0,0 +1,39 @@
+import type { Operation } from "@lenso/engine/operations";
+import { type McpAdapterOptions } from "./adapter";
+/** Verified by the host's signature/introspection and current revocation policy, not decoded JSON. */
+export interface McpIdentity {
+    readonly subject: string;
+    readonly tenant: string;
+    readonly issuer: string;
+    readonly audience: readonly string[];
+    readonly scopes: readonly string[];
+    /** Unix seconds. */
+    readonly expiresAt: number;
+}
+export interface HttpMcpOptions<I extends McpIdentity, O extends Operation = Operation> extends McpAdapterOptions<I, O> {
+    /** Canonical public MCP resource URL. Never inferred from forwarded headers. */
+    readonly resource: string;
+    readonly authorizationServers: readonly string[];
+    readonly requiredScopes: readonly string[];
+    readonly allowedOrigins: readonly string[];
+    /** Must cryptographically verify or introspect the token, including current validity/revocation. */
+    readonly verifyToken: (token: string, signal: AbortSignal) => I | Promise<I>;
+    readonly maxFrameBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxHttpRequests?: number;
+    readonly maxSessions?: number;
+    readonly sessionIdleMs?: number;
+    readonly rateLimit?: {
+        readonly requests: number;
+        readonly windowMs: number;
+        readonly maxIdentities: number;
+    };
+}
+/**
+ * Owns protocol sessions only. Mount fetch in the host's existing listener;
+ * close never stops the borrowed app or changes global logging.
+ */
+export declare function createHttpMcp<I extends McpIdentity, O extends Operation>(options: HttpMcpOptions<I, O>): Promise<{
+    fetch(request: Request): Promise<Response>;
+    close(): Promise<void>;
+}>;

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import { type OperationBinding } from "@lenso/engine/application";
+export { createMcpAdapter, type McpAdapterOptions, type McpRequestContext } from "./adapter";
+export { createHttpMcp, type HttpMcpOptions, type McpIdentity } from "./http";
+export { serveBorrowedStdio, type BorrowedStdioOptions } from "./borrowed-stdio";
 export interface StdioOptions {
     /** Trusted launch configuration, never supplied by an MCP tool. */
     root: string;