From 54451b982ee293b2d8a18dfef93badf950d2f030 Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Sun, 25 Oct 2026 17:17:02 -0700 Subject: [PATCH 1/2] docs: point agents at the 0.4.0 entries Name the client, stateless server, and Interchange bridge, and pin the released OAuth and credential companions an agent should install. --- README.md | 49 ++++++++++++++++++++++++++++++++++++++-------- docs/public-api.md | 2 +- package.json | 2 +- 3 files changed, 43 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index db4ee1a..b6f8506 100644 --- a/README.md +++ b/README.md @@ -47,30 +47,63 @@ or certify the host's sandbox. See [scope and evidence](docs/conformance.md). ## Install +`@corbits/mcp@0.4.0` is the package. Neutral imports `@corbits/mcp/client` and +`@corbits/mcp/server` need no Interchange or OAuth peers. + ```bash bun add @corbits/mcp # For Interchange consumption: bun add @intx/agent @intx/harness -# Historical root / guarded OAuth login also requires OAuth-core: -bun add @corbits/oauth-core@0.3.0 +# Historical root entry and guarded OAuth login: +bun add @corbits/oauth-core@0.3.3 ``` Runs on Node.js 24+ and Bun 1.2+. -Standalone client/server entries do not require OAuth-core or Interchange host -peers. OAuth-core is now an **optional peer**, not a mandatory dependency: this -is a breaking installation change for the historical root and OAuth login users, -who must explicitly install it as shown above. Installing OAuth-core still brings +OAuth-core is an **optional peer**, not a mandatory dependency: this is a +breaking installation change for the historical root and OAuth login users, who +must explicitly install it as shown above. Installing OAuth-core still brings its own DB/hub/Hono dependencies; that host installation is separate from the neutral package. See [public API dependency notes](docs/public-api.md) for the credential-http/harness/types peer conflict affecting the full hub setup. -For the `@corbits/mcp/hub` routes, also install: +For hub discovery, also install `@corbits/credential-http@0.1.3` plus the hub +packages: ```bash -bun add @corbits/credential-http @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono +bun add @corbits/credential-http@0.1.3 @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono +``` + +## Use it from an agent + +List tools with the standalone client. That import needs no Interchange or OAuth +peers: + +```ts +import { mcpConnect, mcpListTools } from "@corbits/mcp/client"; + +const url = "https://mcp.deepwiki.com/mcp"; +const session = await mcpConnect(url); +for (const tool of await mcpListTools(url, { session })) { + console.log(`${tool.name}: ${tool.description ?? ""}`); +} +``` + +After `@intx/agent` and `@intx/harness` are installed, the peer-backed root +entry discovers each server and builds one Interchange tool per remote tool: + +```ts +import { mcpTools } from "@corbits/mcp"; + +const factory = await mcpTools({ + servers: [{ name: "deepwiki", url: "https://mcp.deepwiki.com/mcp" }], +}); ``` +The four entries in the table above are the public surface. This package does +not claim full MCP certification and does not supply a browser renderer. Legacy +sessions are in-memory. The Skills consumer declines dynamic manifests. + ## Quickstart Lists the tools on a public MCP server: diff --git a/docs/public-api.md b/docs/public-api.md index 26fd6a4..4c37c49 100644 --- a/docs/public-api.md +++ b/docs/public-api.md @@ -32,7 +32,7 @@ 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 +npm install @corbits/mcp @corbits/oauth-core@0.3.3 @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 diff --git a/package.json b/package.json index 7abf6d5..569f1d8 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@corbits/mcp", "version": "0.4.0", - "description": "MCP client tool package for Interchange: streamable HTTP, per-tool grants, OAuth.", + "description": "MCP client, stateless server, and Interchange bridge over streamable HTTP.", "keywords": [ "corbits", "interchange", From 9a9b1db624d2bec14d29c8dca44922335208f6cb Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Mon, 26 Oct 2026 20:41:36 -0700 Subject: [PATCH 2/2] docs: align quickstart pins with declared peers The root mcpTools import requires @corbits/oauth-core 0.3.0 (peer ^0.3.0). credential-http stays at the declared ^0.1.0 peer; 0.1.0 does not resolve on the 0.5 baseline. Name the root, hub, sidecar-bundle, and task-store exports beside the four role entries. --- README.md | 29 +++++++++++++++++++---------- docs/public-api.md | 2 +- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index b6f8506..327206a 100644 --- a/README.md +++ b/README.md @@ -54,8 +54,8 @@ or certify the host's sandbox. See [scope and evidence](docs/conformance.md). bun add @corbits/mcp # For Interchange consumption: bun add @intx/agent @intx/harness -# Historical root entry and guarded OAuth login: -bun add @corbits/oauth-core@0.3.3 +# Historical root entry and guarded OAuth login (optional peer ^0.3.0): +bun add @corbits/oauth-core@0.3.0 ``` Runs on Node.js 24+ and Bun 1.2+. @@ -67,11 +67,14 @@ its own DB/hub/Hono dependencies; that host installation is separate from the neutral package. See [public API dependency notes](docs/public-api.md) for the credential-http/harness/types peer conflict affecting the full hub setup. -For hub discovery, also install `@corbits/credential-http@0.1.3` plus the hub -packages: +For hub discovery, `@corbits/credential-http` is an optional peer (`^0.1.0`). +This package pins development dependency `0.1.0`. That release declares +`@intx/harness` and `@intx/types` `^0.4.0`, so it does not resolve with the +0.5 baseline, and no companion release number is known. See +[public API dependency notes](docs/public-api.md). The other hub packages: ```bash -bun add @corbits/credential-http@0.1.3 @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono +bun add @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono ``` ## Use it from an agent @@ -89,8 +92,12 @@ for (const tool of await mcpListTools(url, { session })) { } ``` -After `@intx/agent` and `@intx/harness` are installed, the peer-backed root -entry discovers each server and builds one Interchange tool per remote tool: +The root entry requires `@corbits/oauth-core` as well as `@intx/agent` and +`@intx/harness`. Install `@corbits/oauth-core@0.3.0` (optional peer `^0.3.0`). +`@intx/agent` and `@intx/harness` alone are not enough: importing `mcpTools` +from `@corbits/mcp` loads `@corbits/oauth-core`. After those peers are +installed, the root entry discovers each server and builds one Interchange +tool per remote tool: ```ts import { mcpTools } from "@corbits/mcp"; @@ -100,9 +107,11 @@ const factory = await mcpTools({ }); ``` -The four entries in the table above are the public surface. This package does -not claim full MCP certification and does not supply a browser renderer. Legacy -sessions are in-memory. The Skills consumer declines dynamic manifests. +The four entries in the table above are the scoped role entries, not the whole +public surface. The package also exports `.`, `./hub`, `./sidecar-bundle`, and +`./server/task-store`. This package does not claim full MCP certification and +does not supply a browser renderer. Legacy sessions are in-memory. The Skills +consumer declines dynamic manifests. ## Quickstart diff --git a/docs/public-api.md b/docs/public-api.md index 4c37c49..26fd6a4 100644 --- a/docs/public-api.md +++ b/docs/public-api.md @@ -32,7 +32,7 @@ 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.3 @intx/agent@0.5.0 @intx/harness@0.5.0 +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