@corbits/mcp 0.3.1 → 0.4.0

package/docs/public-api.md

@@ -0,0 +1,106 @@
+# Public extension and authorization API
+
+Status: integration followup, 2026-10-25. Factory exports are implemented and
+installed behavior is tested; OAuth-core is an optional host peer.
+
+| Entry                             | Public API                                                                                                                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@corbits/mcp/client`             | Standalone client functions and wire types                                                                                                                                                       |
+| `@corbits/mcp/server`             | Server/provider factories, `createSkillPublisher`, skill contracts, `createTaskRuntime`, `validateTaskRecord`, task contracts, `createMcpResourceServerAuth`, auth policy/identity/options types |
+| `@corbits/mcp/server/task-store`  | `createFileTaskStore` (explicit filesystem entry only)                                                                                                                                           |
+| `@corbits/mcp/interchange/client` | Existing tool/server/host APIs plus `createSkillLoader`, `parseSkillFrontmatter`, `SKILL_LIMITS`, skill contracts                                                                                |
+| `@corbits/mcp/interchange/server` | Explicit selected host exposure contracts and providers                                                                                                                                          |
+| `@corbits/mcp`                    | Historical facade and guarded authorization APIs                                                                                                                                                 |
+
+Facade changes add reexports only. No filesystem store is exported through a
+neutral barrel. The file store requires a private host-owned directory and one
+writer; stale-lock recovery requires proof the previous writer is dead.
+
+## Dependency boundary and setup
+
+OAuth-core is an optional peer (`^0.3.0`) and pinned development dependency
+(0.3.0). Neutral client/server entries do not require it. Root and guarded OAuth
+login users must explicitly install OAuth-core plus the root's agent/harness
+peers; this is a breaking change from automatic OAuth installation. Host/auth
+packed fixtures explicitly install these dependencies. OAuth-core itself still
+transitively installs DB/hub/Hono; that cost belongs to the opt-in host setup.
+
+Resource-server URL validation now uses the neutral auth URL-policy seam. Its
+errors retain the diagnostic `OAuthDiscoveryError` name/message/detail but are
+not instances of OAuth-core's error class. OAuth-facing helpers translate to the
+actual OAuth-core `OAuthDiscoveryError` class. Neutral consumers must not import
+the optional OAuth implementation merely to perform an `instanceof` check.
+
+```sh
+npm install @corbits/mcp @corbits/oauth-core@0.3.0 @intx/agent@0.5.0 @intx/harness@0.5.0
+```
+
+The full hub peer set does not resolve: credential-http 0.1.0 declares harness
+**and types** `^0.4.0`, incompatible with the pinned 0.5.0 baseline. A companion
+credential-http release validated with and declaring support for both
+`@intx/harness@0.5.0` and `@intx/types@0.5.0` is needed. No known release number
+is asserted; no force/legacy-peer-deps or external patch was used.
+
+## Installed evidence
+
+The final optional-peer tarball fixtures pass on Bun 1.4.2 and Node 24.22.1:
+publisher bytes/metadata, task close/reopen/recovery without replay and principal
+isolation, injected resource-auth verifier/challenge/metadata, skill verification
+and refusal to activate without policy, historical facade identity, and guarded
+OAuth PKCE/resource/cancellation. These are scoped fixture assertions, not live
+OAuth interoperability, cryptographic-verifier certification or full conformance.
+
+Package tests use ordinary npm installs (no peer omission), reject absent public
+exports, assert unwanted dependencies are absent, and check both neutral module
+graphs. These checks validate the dependency boundary; see [integration status](integration-status.md) for command evidence.
+
+## Legacy public options and Apps gate
+
+The server entry exposes `McpLegacyOptions` / `McpLegacyRevision`; the installed
+legacy smoke exercises `createMcpServer({ legacy: ... })` for all three 2025
+revisions. See [legacy-server.md](legacy-server.md) for bounds and deployment
+requirements. Modern mode stays session-free by default.
+
+Interchange Apps advertisement requires explicit `apps` bridge/support and
+presentation, including sandbox renderer, CSP enforcement and authenticated
+bridge support. Metadata-only presentation does not advertise Apps. The host
+must implement the renderer and enforce these commitments.
+
+## Guarded path versus external companion defects
+
+**CL11479:** OAuth-core 0.3.0 stock BaseTokens/conversion/storage requires refresh
+material even for valid access-token-only grants. Stock token POST follows
+redirects and exposes raw response error bodies, and authorization extras can
+overwrite protected state/PKCE. The guarded MCP login/session path supports
+access-only tokens through honest host persistence, refuses redirects, sanitizes
+errors and rejects protected overrides; it does not fix stock helpers.
+
+Additional documented stock hub limits are DCR-only registration selection and
+present-but-unadvertised `iss` not being checked on the stock callback path.
+These integration limits are distinct from the exact CL11479 issue acceptance.
+Use guarded preparation/session/callback seams rather than assuming the stock
+provider/hub path has equivalent checks. OAuth-core already propagates resource
+on code exchange and refresh; the local config-builder omission was fixed, not
+an absent upstream feature.
+
+**CL11480:** Besides the harness/types peer conflict above, credential-http 0.1.0
+ignores Request+init overrides in its Request branch and permits insecure
+configured credential destination schemes. Local hub endpoint/redirect checks
+do not fix standalone external provider handles. Upstream correction and host
+transport policy remain required; no external package was patched here.
+
+The source audit is recorded in `src/auth/INTEGRATION.md`; this public summary
+keeps the relevant limits available in the packed docs. Production encrypted
+storage/authority, live callback listeners, consent, actual cryptographic token
+verification, egress/DNS policy and distributed durability remain host obligations.
+
+## Verified Skills supported shapes
+
+The verified Skills loader declines dynamic manifests. This refusal is permitted
+by the pinned Skills specification; dynamic consumption is not a newly missing
+mandatory capability or an expansion of this adapter's implementation scope.
+The adapter requires a complete resource read containing exactly one text or
+blob item whose URI matches the requested resource. Resource-read MRTR
+(`input_required`) is unsupported by this verified adapter; generic client MRTR
+support does not imply that the Skills adapter can fulfill it. These supported-
+shape limits are separate from the approved decoded-size and integrity bounds.

package/examples/README.md

@@ -0,0 +1,28 @@
+# Examples
+
+These examples use public entry points after building/installing the package.
+
+- `standalone-client.ts`: discover and call an explicitly named remote tool.
+- `standalone-server.ts`: intentionally public loopback echo server. Do not expose
+  sensitive operations with `auth: "public"`; install a validated auth policy and
+  explicit allowed origins when deploying an authenticated service.
+- `../e2e/interchange.test.ts`: executable bidirectional example using installed
+  Interchange `defineTool`, `createToolRunner`, HTTP credential provider and
+  credential capability. It exposes one selected tool (not the entire bundle),
+  calls it through standalone MCP, consumes it back into a real tool factory,
+  and asserts schema/authorization/approval failures do not execute it. It does
+  not simulate an inference reactor or certify workflow/task lifecycle support.
+
+```sh
+bun run build
+bun examples/standalone-server.ts
+# In another terminal:
+bun examples/standalone-client.ts http://127.0.0.1:3000/mcp echo
+```
+
+For an authenticated host, compose `createInterchangeProviders({ auth, exposures })`
+into `createMcpServer({ serverInfo, auth, providers })`. Each exposure supplies a
+host-bound tenant, operation resource/action, explicit approval callback and a
+selected tool/agent/HTTP/workflow binding. Never derive identity or fixed tenant
+paths from model arguments. See the [migration guide](../docs/migration.md) for
+required host services and cancellation/durability limits.

package/examples/standalone-client.ts

@@ -0,0 +1,14 @@
+import { mcpCallTool, mcpConnect, mcpListTools } from "@corbits/mcp/client";
+
+const url = process.argv[2];
+const name = process.argv[3];
+if (!url || !name) throw new Error("Usage: standalone-client.ts <url> <tool>");
+const session = await mcpConnect(url);
+console.log(await mcpListTools(url, { session }));
+const result = await mcpCallTool(url, name, { text: "hello" }, { session });
+if (result.resultType === "input_required" || result.resultType === "task") {
+  throw new Error(
+    "This minimal example has no elicitation or task host services",
+  );
+}
+console.log(result.content);

package/examples/standalone-server.ts

@@ -0,0 +1,37 @@
+import { createMcpServer, createToolProviders } from "@corbits/mcp/server";
+
+const server = createMcpServer({
+  serverInfo: { name: "public-loopback-echo", version: "1" },
+  auth: "public",
+  providers: createToolProviders(
+    [
+      {
+        definition: {
+          name: "echo",
+          inputSchema: {
+            type: "object",
+            properties: { text: { type: "string" } },
+            required: ["text"],
+            additionalProperties: false,
+          },
+        },
+        resource: "example:echo",
+        action: "invoke",
+        execute: (args) => ({
+          content: [{ type: "text", text: String(args.text) }],
+        }),
+      },
+    ],
+    "public",
+  ),
+});
+const http = Bun.serve({
+  hostname: "127.0.0.1",
+  port: 3000,
+  fetch: server.fetch,
+});
+console.log(new URL("/mcp", http.url).href);
+process.once("SIGINT", () => {
+  http.stop(true);
+  void server.close();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corbits/mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "MCP client tool package for Interchange: streamable HTTP, per-tool grants, OAuth.",
   "keywords": [
     "corbits",
@@ -22,7 +22,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs",
+    "examples"
   ],
   "type": "module",
   "sideEffects": false,
@@ -38,6 +40,26 @@
     "./hub": {
       "types": "./dist/hub/index.d.ts",
       "default": "./dist/hub/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./interchange/client": {
+      "types": "./dist/interchange/client.d.ts",
+      "default": "./dist/interchange/client.js"
+    },
+    "./interchange/server": {
+      "types": "./dist/interchange/server.d.ts",
+      "default": "./dist/interchange/server.js"
+    },
+    "./server/task-store": {
+      "types": "./dist/extensions/tasks/file-store.d.ts",
+      "default": "./dist/extensions/tasks/file-store.js"
     }
   },
   "publishConfig": {
@@ -52,15 +74,18 @@
     "format:check": "oxfmt --check",
     "test": "bun test src --pass-with-no-tests",
     "test:e2e": "bun test e2e",
-    "check": "bun run typecheck && bun run lint && bun run format:check && bun run test"
+    "check": "bun run typecheck && bun run lint && bun run format:check && bun run test",
+    "test:package": "bun test e2e/package.test.ts"
   },
   "dependencies": {
-    "@corbits/oauth-core": "^0.3.0",
     "@intx/types": "^0.5.0",
-    "arktype": "^2.2.3"
+    "ajv": "^8.17.1",
+    "arktype": "^2.2.3",
+    "yaml": "2.8.1"
   },
   "devDependencies": {
     "@corbits/credential-http": "0.1.0",
+    "@corbits/oauth-core": "0.3.0",
     "@intx/agent": "0.5.0",
     "@intx/authz": "0.5.0",
     "@intx/db": "0.5.0",
@@ -77,6 +102,7 @@
   },
   "peerDependencies": {
     "@corbits/credential-http": "^0.1.0",
+    "@corbits/oauth-core": "^0.3.0",
     "@intx/agent": "^0.5.0",
     "@intx/db": "^0.5.0",
     "@intx/harness": "^0.4.0 || ^0.5.0",
@@ -99,6 +125,15 @@
     },
     "hono": {
       "optional": true
+    },
+    "@intx/agent": {
+      "optional": true
+    },
+    "@intx/harness": {
+      "optional": true
+    },
+    "@corbits/oauth-core": {
+      "optional": true
     }
   },
   "engines": {