@corbits/mcp 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +53 -13
  2. package/docs/integration-status.md +11 -9
  3. package/docs/migration.md +5 -5
  4. package/docs/public-api.md +13 -14
  5. package/package.json +7 -7
package/README.md CHANGED
@@ -47,30 +47,70 @@ or certify the host's sandbox. See [scope and evidence](docs/conformance.md).
47
47
 
48
48
  ## Install
49
49
 
50
+ `@corbits/mcp@0.4.1` is the package. Neutral imports `@corbits/mcp/client` and
51
+ `@corbits/mcp/server` need no Interchange or OAuth peers.
52
+
50
53
  ```bash
51
54
  bun add @corbits/mcp
52
- # For Interchange consumption:
53
- bun add @intx/agent @intx/harness
54
- # Historical root / guarded OAuth login also requires OAuth-core:
55
- bun add @corbits/oauth-core@0.3.0
55
+ # For Interchange consumption (optional peers ^0.5.0):
56
+ bun add @intx/agent@0.5.0 @intx/harness@0.5.0
57
+ # Historical root entry and guarded OAuth login (optional peer ^0.3.3):
58
+ bun add @corbits/oauth-core@0.3.3
56
59
  ```
57
60
 
58
61
  Runs on Node.js 24+ and Bun 1.2+.
59
62
 
60
- Standalone client/server entries do not require OAuth-core or Interchange host
61
- peers. OAuth-core is now an **optional peer**, not a mandatory dependency: this
62
- is a breaking installation change for the historical root and OAuth login users,
63
- who must explicitly install it as shown above. Installing OAuth-core still brings
63
+ OAuth-core is an **optional peer**, not a mandatory dependency: this is a
64
+ breaking installation change for the historical root and OAuth login users, who
65
+ must explicitly install it as shown above. Installing OAuth-core still brings
64
66
  its own DB/hub/Hono dependencies; that host installation is separate from the
65
- neutral package. See [public API dependency notes](docs/public-api.md) for the
66
- credential-http/harness/types peer conflict affecting the full hub setup.
67
+ neutral package. See [public API dependency notes](docs/public-api.md).
67
68
 
68
- For the `@corbits/mcp/hub` routes, also install:
69
+ For hub discovery, `@corbits/credential-http` is an optional peer (`^0.1.3`).
70
+ Install `@corbits/credential-http@0.1.3`. That release accepts `@intx/harness`
71
+ and `@intx/types` `^0.5.0`. The other hub packages:
69
72
 
70
73
  ```bash
71
- bun add @corbits/credential-http @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono
74
+ bun add @intx/authz @intx/crypto @intx/db @intx/hub-api drizzle-orm hono
75
+ ```
76
+
77
+ ## Use it from an agent
78
+
79
+ List tools with the standalone client. That import needs no Interchange or OAuth
80
+ peers:
81
+
82
+ ```ts
83
+ import { mcpConnect, mcpListTools } from "@corbits/mcp/client";
84
+
85
+ const url = "https://mcp.deepwiki.com/mcp";
86
+ const session = await mcpConnect(url);
87
+ for (const tool of await mcpListTools(url, { session })) {
88
+ console.log(`${tool.name}: ${tool.description ?? ""}`);
89
+ }
90
+ ```
91
+
92
+ The root entry requires `@corbits/oauth-core` as well as `@intx/agent` and
93
+ `@intx/harness`. Install `@corbits/oauth-core@0.3.3` (optional peer `^0.3.3`)
94
+ and `@intx/harness@0.5.0` (optional peer `^0.5.0`).
95
+ `@intx/agent` and `@intx/harness` alone are not enough: importing `mcpTools`
96
+ from `@corbits/mcp` loads `@corbits/oauth-core`. After those peers are
97
+ installed, the root entry discovers each server and builds one Interchange
98
+ tool per remote tool:
99
+
100
+ ```ts
101
+ import { mcpTools } from "@corbits/mcp";
102
+
103
+ const factory = await mcpTools({
104
+ servers: [{ name: "deepwiki", url: "https://mcp.deepwiki.com/mcp" }],
105
+ });
72
106
  ```
73
107
 
108
+ The four entries in the table above are the scoped role entries, not the whole
109
+ public surface. The package also exports `.`, `./hub`, `./sidecar-bundle`, and
110
+ `./server/task-store`. This package does not claim full MCP certification and
111
+ does not supply a browser renderer. Legacy sessions are in-memory. The Skills
112
+ consumer declines dynamic manifests.
113
+
74
114
  ## Quickstart
75
115
 
76
116
  Lists the tools on a public MCP server:
@@ -274,7 +314,7 @@ above still apply, including no deprecated HTTP+SSE transport or SSE resumption.
274
314
  - `readCredentialSecret` is now `readCredential`, which returns `{ secret, origin? }`. `discoverMcpServer` takes `credential: { secret, origin? }` instead of `secret`.
275
315
  - `mcpInitialize` returns an `McpSession` (`protocolVersion`, `sessionId?`, `serverInfo?`) and sends `notifications/initialized`. Pass it as `{ session }` to `mcpListTools` and `mcpCallTool`; a stateful server needs it.
276
316
  - The discovery route refuses plain-http loopback URLs unless `allowLoopback` is set. Handles and server names containing `.`, and catalogs repeating a tool name, are refused. `mcpTools` refuses an empty or repeated server name, and a non-https URL, before any request.
277
- - The integration baseline is `@intx/agent` 0.5.0 and `@intx/harness` 0.5.0; see package peer ranges.
317
+ - The integration baseline is `@intx/agent` 0.5.0, `@intx/harness` 0.5.0 (peer `^0.5.0`), `@corbits/oauth-core` 0.3.3 (peer `^0.3.3`), and `@corbits/credential-http` 0.1.3 (peer `^0.1.3`).
278
318
  - Discovery rejects authorization-server metadata whose `issuer` differs from the one the protected resource names.
279
319
 
280
320
  ## License
package/docs/integration-status.md CHANGED
@@ -8,10 +8,11 @@ unit tests and 2,116 assertions. This is not a 100% conformance claim.
8
8
 
9
9
  - Public role factories/contracts are exported and exercised through installed
10
10
  tarballs. File-store is explicit `@corbits/mcp/server/task-store` only.
11
- - OAuth-core is an optional peer `^0.3.0` and pinned development dependency 0.3.0.
11
+ - OAuth-core is an optional peer `^0.3.3` and pinned development dependency 0.3.3.
12
12
  Root/login consumers install it explicitly. Neutral client/server installations
13
13
  and module graphs exclude optional host stacks. Host/auth fixtures explicitly
14
- install OAuth-core 0.3.0 and agent/harness 0.5.0.
14
+ install OAuth-core 0.3.3 and `@intx/harness` 0.5.0 (peer `^0.5.0`).
15
+ `@corbits/credential-http` is an optional peer `^0.1.3`.
15
16
  - Opt-in server legacy compatibility is implemented for 2025-11-25/06-18/03-26.
16
17
  [Legacy deployment](legacy-server.md) documents defaults (1,024 sessions,
17
18
  absolute 30-minute TTL), in-memory affinity/restart loss, 10,000 request IDs,
@@ -62,14 +63,15 @@ unadvertised issuer handling are additional integration limits, distinct from
62
63
  exact issue acceptance. Resource exchange/refresh propagation exists upstream;
63
64
  this package's local config omission was fixed.
64
65
 
65
- **CL11480 (credential-http):** full pinned hub installation fails npm ERESOLVE:
66
- 0.1.0 requires harness/types ^0.4.0 against the 0.5.0 baseline. A companion
67
- release validated with and declaring support for both 0.5.0 peers is needed;
68
- no fixed release number is established. Request+init overrides and insecure
69
- configured schemes also require upstream correction. These optional-host
70
- failures do not block the passing neutral installation.
66
+ **CL11480 (credential-http):** the 2026-10-25 snapshot failed npm ERESOLVE on
67
+ credential-http 0.1.0, which required harness/types ^0.4.0 against the 0.5.0
68
+ baseline. This release's optional peer is `^0.1.3`. `@corbits/credential-http@0.1.3`
69
+ accepts `@intx/harness` and `@intx/types` `^0.5.0`. Request+init overrides and
70
+ insecure configured schemes were recorded against 0.1.0 and still require
71
+ upstream correction. Those optional-host limits do not block the neutral
72
+ installation.
71
73
 
72
- Previously reproduced external install (exit 1):
74
+ Previously reproduced external install of 0.1.0 (exit 1):
73
75
 
74
76
  ```sh
75
77
  npm install --prefix "$peer_dir" --ignore-scripts --no-audit --no-fund @corbits/credential-http@0.1.0 @intx/agent@0.5.0 @intx/harness@0.5.0 @intx/db@0.5.0 @intx/hub-api@0.5.0 @intx/types@0.5.0 drizzle-orm@0.45.3 hono@4.13.9
package/docs/migration.md CHANGED
@@ -119,11 +119,11 @@ Root import consumers still need their historical Interchange dependencies.
119
119
 
120
120
  Publisher/task-runtime/server-auth and host skill-loader factories are now exported
121
121
  through their role entries and exercised from installed tarballs. OAuth-core is now an optional peer: historical root and guarded login consumers
122
- must explicitly install `@corbits/oauth-core@^0.3.0` alongside their agent/harness
123
- peers. Neutral client/server consumers need none of those optional host packages.
124
- Packed auth fixtures explicitly install OAuth-core 0.3.0. See
125
- [public API](public-api.md) for the neutral URL-error class distinction and the
126
- companion credential-http harness/types 0.5.0 support requirement.
122
+ must explicitly install `@corbits/oauth-core@^0.3.3` alongside `@intx/harness@^0.5.0`
123
+ and their agent peers. Neutral client/server consumers need none of those optional host packages.
124
+ Packed auth fixtures explicitly install OAuth-core 0.3.3. See
125
+ [public API](public-api.md) for the neutral URL-error class distinction.
126
+ Hub discovery uses optional peer `@corbits/credential-http@^0.1.3`.
127
127
 
128
128
  ## Legacy server rollout
129
129
 
package/docs/public-api.md CHANGED
@@ -18,10 +18,10 @@ writer; stale-lock recovery requires proof the previous writer is dead.
18
18
 
19
19
  ## Dependency boundary and setup
20
20
 
21
- OAuth-core is an optional peer (`^0.3.0`) and pinned development dependency
22
- (0.3.0). Neutral client/server entries do not require it. Root and guarded OAuth
21
+ OAuth-core is an optional peer (`^0.3.3`) and pinned development dependency
22
+ (0.3.3). Neutral client/server entries do not require it. Root and guarded OAuth
23
23
  login users must explicitly install OAuth-core plus the root's agent/harness
24
- peers; this is a breaking change from automatic OAuth installation. Host/auth
24
+ peers (`@intx/harness` `^0.5.0`); this is a breaking change from automatic OAuth installation. Host/auth
25
25
  packed fixtures explicitly install these dependencies. OAuth-core itself still
26
26
  transitively installs DB/hub/Hono; that cost belongs to the opt-in host setup.
27
27
 
@@ -32,14 +32,12 @@ actual OAuth-core `OAuthDiscoveryError` class. Neutral consumers must not import
32
32
  the optional OAuth implementation merely to perform an `instanceof` check.
33
33
 
34
34
  ```sh
35
- npm install @corbits/mcp @corbits/oauth-core@0.3.0 @intx/agent@0.5.0 @intx/harness@0.5.0
35
+ npm install @corbits/mcp @corbits/oauth-core@0.3.3 @intx/agent@0.5.0 @intx/harness@0.5.0
36
36
  ```
37
37
 
38
- The full hub peer set does not resolve: credential-http 0.1.0 declares harness
39
- **and types** `^0.4.0`, incompatible with the pinned 0.5.0 baseline. A companion
40
- credential-http release validated with and declaring support for both
41
- `@intx/harness@0.5.0` and `@intx/types@0.5.0` is needed. No known release number
42
- is asserted; no force/legacy-peer-deps or external patch was used.
38
+ `@corbits/credential-http` is an optional peer (`^0.1.3`). Install
39
+ `@corbits/credential-http@0.1.3`. That release accepts `@intx/harness` and
40
+ `@intx/types` `^0.5.0`.
43
41
 
44
42
  ## Installed evidence
45
43
 
@@ -83,11 +81,12 @@ provider/hub path has equivalent checks. OAuth-core already propagates resource
83
81
  on code exchange and refresh; the local config-builder omission was fixed, not
84
82
  an absent upstream feature.
85
83
 
86
- **CL11480:** Besides the harness/types peer conflict above, credential-http 0.1.0
87
- ignores Request+init overrides in its Request branch and permits insecure
88
- configured credential destination schemes. Local hub endpoint/redirect checks
89
- do not fix standalone external provider handles. Upstream correction and host
90
- transport policy remain required; no external package was patched here.
84
+ **CL11480:** credential-http 0.1.0 ignored Request+init overrides in its Request
85
+ branch and permitted insecure configured credential destination schemes. Peer
86
+ `^0.1.3` accepts `@intx/harness` and `@intx/types` `^0.5.0`. Local hub
87
+ endpoint/redirect checks do not fix standalone external provider handles.
88
+ Upstream correction and host transport policy remain required; no external
89
+ package was patched here.
91
90
 
92
91
  The source audit is recorded in `src/auth/INTEGRATION.md`; this public summary
93
92
  keeps the relevant limits available in the packed docs. Production encrypted
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@corbits/mcp",
3
- "version": "0.4.0",
4
- "description": "MCP client tool package for Interchange: streamable HTTP, per-tool grants, OAuth.",
3
+ "version": "0.4.1",
4
+ "description": "MCP client, stateless server, and Interchange bridge over streamable HTTP.",
5
5
  "keywords": [
6
6
  "corbits",
7
7
  "interchange",
@@ -84,8 +84,8 @@
84
84
  "yaml": "2.8.1"
85
85
  },
86
86
  "devDependencies": {
87
- "@corbits/credential-http": "0.1.0",
88
- "@corbits/oauth-core": "0.3.0",
87
+ "@corbits/credential-http": "0.1.3",
88
+ "@corbits/oauth-core": "0.3.3",
89
89
  "@intx/agent": "0.5.0",
90
90
  "@intx/authz": "0.5.0",
91
91
  "@intx/db": "0.5.0",
@@ -101,11 +101,11 @@
101
101
  "zod": "4.6.5"
102
102
  },
103
103
  "peerDependencies": {
104
- "@corbits/credential-http": "^0.1.0",
105
- "@corbits/oauth-core": "^0.3.0",
104
+ "@corbits/credential-http": "^0.1.3",
105
+ "@corbits/oauth-core": "^0.3.3",
106
106
  "@intx/agent": "^0.5.0",
107
107
  "@intx/db": "^0.5.0",
108
- "@intx/harness": "^0.4.0 || ^0.5.0",
108
+ "@intx/harness": "^0.5.0",
109
109
  "@intx/hub-api": "^0.5.0",
110
110
  "drizzle-orm": "^0.45.2",
111
111
  "hono": "^4.11.9"