@usemcpkit/core 0.1.1 → 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.
package/README.md ADDED
@@ -0,0 +1,191 @@
1
+ # @usemcpkit/core
2
+
3
+ Library behind mcpkit: the manifest format and its validation, the server SDK (`defineServer`, `defineTool`,
4
+ `defineUI`), the HTTP executor with response mapping, and auth (fallbacks, OAuth 2.0 PKCE, the credentials form
5
+ contract). Published to npm. It contains no per-provider code: a server differs from another only in its manifest.
6
+
7
+ Public surface: `src/main.ts` (built to `build/mcpkit.core.js` with bundled types in `build/mcpkit.core.d.ts`).
8
+
9
+ ## Manifest format
10
+
11
+ ```jsonc
12
+ {
13
+ "name": "github", // [a-z][a-z0-9_]*
14
+ "category": "git", // [a-z][a-z0-9-]*, groups servers of one kind
15
+ "version": "1.0.0",
16
+ "baseUrl": "https://{domain}", // https only; {domain} is optional, see Domain
17
+ "domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" },
18
+ "headers": { "Accept": "application/vnd.github+json" },
19
+ "auth": [ // tried top to bottom, see Auth
20
+ { "type": "bearer", "env": "GITHUB_TOKEN" }
21
+ ],
22
+ "tools": [
23
+ {
24
+ "name": "list_issues",
25
+ "description": "List issues in a repository.",
26
+ "input": { "type": "object", "properties": { ... }, "required": ["owner", "repo"] },
27
+ "request": {
28
+ "method": "GET",
29
+ "path": "/repos/{owner}/{repo}/issues", // {arg} → URL-encoded argument
30
+ "query": ["state", "per_page"], // or { "q": "query" } to rename
31
+ "body": ["title"], // JSON body for non-GET, see Request bodies
32
+ "commaQuery": ["tags"], // optional: array query keys joined with commas (others repeat the key)
33
+ "fileArgs": ["file"], // optional: args holding a local file path; sent as multipart parts (contentType multipart/form-data) or as the raw bodyArg
34
+ "saveToArg": "save_to", // optional: arg holding a local path; a successful response is written there and a summary returned
35
+ "fixedQuery": { "sort": "updated" }, // optional: constant query values
36
+ "contentType": "text/plain", // optional: default application/json; text/* sends bodyArg as plain text
37
+ "fixedHeaders": { "X-Atlassian-Token": "no-check" }, // optional: constant request headers
38
+ "fixedBody": { "type": "issue" }, // optional: constant body values, args win
39
+ "bodyArg": "body" // optional: send this arg as the whole JSON body (array, string or free-form object); excludes body/fixedBody
40
+ },
41
+ "response": {
42
+ "root": "items", // optional: dig into the payload
43
+ "fields": { "author": "user.login", "labels": "labels[].name" }
44
+ }
45
+ }
46
+ ]
47
+ }
48
+ ```
49
+
50
+ **Request bodies.** Outgoing body keys may be dotted paths that build nested JSON, with numbers as array
51
+ indexes: `{ "fields.project.key": "project_key", "ancestors.0.id": "parent_id" }` sends
52
+ `{"fields":{"project":{"key":"..."}},"ancestors":[{"id":"..."}]}`. `fixedBody` keys work the same way. Fixed values
53
+ are strings, numbers or booleans.
54
+
55
+ **Editions.** One server can cover deployments whose endpoints differ, such as Atlassian Cloud and Data Center. The
56
+ manifest names them with the host suffixes that select them; a tool overrides its `request` (and `response`, when
57
+ given) per edition. A domain matching no edition uses the tool's own request:
58
+
59
+ ```jsonc
60
+ "editions": { "cloud": { "label": "Cloud", "hosts": [".atlassian.net"] } }, // names: [a-z][a-z0-9-]*
61
+ "tools": [
62
+ {
63
+ "name": "search_issues",
64
+ "request": { "method": "GET", "path": "/rest/api/2/search", "query": ["jql"] },
65
+ "editions": {
66
+ "cloud": { "request": { "method": "GET", "path": "/rest/api/2/search/jql", "query": ["jql"] } }
67
+ }
68
+ }
69
+ ]
70
+ ```
71
+
72
+ The edition follows the domain in use, including one typed in the credentials form.
73
+
74
+ ## Auth
75
+
76
+ `auth` lists OAuth2 entries (`oauth`) first, then fallbacks. A server can use fallbacks only:
77
+
78
+ ```jsonc
79
+ "auth": [
80
+ { "type": "oauth", "authorizationUrl": "...", "tokenUrl": "...", "clientId": "..." }, // optional
81
+ { "type": "bearer", "env": "GITHUB_TOKEN" } // fallback
82
+ ]
83
+ ```
84
+
85
+ Every tool call tries, in this order, and uses the first that works:
86
+
87
+ 1. the server's OAuth2 token in `tokens.json`, refreshed if it expired (only when `auth` has `oauth` entries);
88
+ 2. each fallback whose value is set, top to bottom. A value comes from its env var, or else from `config.json`;
89
+ 3. the **credentials form**: a local page opened in the browser that asks for the missing values (and the domain,
90
+ see below), or offers "Sign in with OAuth2" when the server has `oauth` entries.
91
+
92
+ An option is skipped when its credentials are missing or the API answers `401`. A fallback that worked is tried right after `tokens.json` on later calls in the same process. If nothing works, the call fails with one line per option
93
+ saying why. `none` can only be the last entry. Leaving out `auth` means no auth.
94
+
95
+ **Fallbacks.** The manifest never holds a secret, only where to find it:
96
+ `none`, `bearer {env}`, `header {env, name, prefix?}`, `query {env, name}`, `basic {usernameEnv, passwordEnv}`
97
+ (each also takes an optional `label`, the option's title in the form; all but `none` take an optional
98
+ `ui`, see below).
99
+ Env vars always win, so CI keeps working without a browser.
100
+
101
+ **Credentials form.** `mcpkit serve` starts a one-off server on `127.0.0.1` (a free port), prints its URL to
102
+ stderr and opens the browser. Only the page that was opened can answer: the URL carries a session token in its
103
+ `#fragment` and the server checks it and the `Host` header. Concurrent calls share one form; it closes after
104
+ an answer, on Cancel, or after 5 minutes. Secrets are saved **only after the API accepts them**, so a typo is never
105
+ stored.
106
+
107
+ **Config file.** The hosts and the saved credentials live together in `~/.mcpkit/config.json`, by category, server and host
108
+ (`{ "servers": { "git": { "gitlab": { "hosts": { "git.acme.com": { "secrets": { "GITLAB_TOKEN": "glpat-…" } } }, "projects": { "/work/app": "git.acme.com" } } } } }`),
109
+ which you can edit by hand. Credentials never cross hosts. With several hosts for one server, the host of a call is, in order:
110
+ its env var; the host its project (git root) was bound to the first time you answered the form; the saved host the
111
+ project's `origin` remote points at (servers whose manifest sets `domain.matchGitRemote`, such as GitHub and GitLab);
112
+ otherwise the form asks, and the answer is remembered for that project. Credentials are plain text, with file mode `0600` in a `0700` directory, the way `gh` and `glab` keep
113
+ their tokens. The file carries a `version` (now 2); a file without one is version 1 and, like an older `secrets.json`, is upgraded on first use by the migration list in `auth/config/config-migrations.ts` (a new version is one appended entry), and a file from a newer mcpkit is refused rather than overwritten. There is no password and nothing to unlock. Any program running as your user can read the file, so
114
+ protect your account and disk; to forget a credential, delete its entry or the file. Environment variables always win
115
+ over the file.
116
+
117
+ **Form UI.** The page holds no text of its own. The CLI injects the whole view model, built from the manifest, into
118
+ the page as JSON, and the page only renders it. Wording and buttons come from the manifest through `defineUI`:
119
+
120
+ ```ts
121
+ import { defineServer, defineUI } from '@usemcpkit/core';
122
+
123
+ defineServer({
124
+ // ...
125
+ ui: defineUI({ texts: { title: 'Connect {server}', submit: 'Save' } }), // any key of the default texts
126
+ auth: [
127
+ {
128
+ type: 'bearer',
129
+ env: 'GITHUB_TOKEN',
130
+ ui: defineUI({
131
+ inputs: { GITHUB_TOKEN: { label: 'Token', hint: '…', placeholder: 'ghp_…' } },
132
+ actions: [
133
+ { type: 'link', label: 'Create on GitHub ↗', url: 'https://{webHost}/settings/tokens/new?name=mcpkit+{server}' },
134
+ { type: 'cli', label: 'Use GitHub CLI', command: 'gh', args: ['auth', 'token', '--hostname', '{webHost}'] },
135
+ ],
136
+ }),
137
+ },
138
+ ],
139
+ });
140
+ ```
141
+
142
+ - `texts` (on the manifest) overrides the defaults in core (`DEFAULT_UI_TEXTS`); `{server}` is filled in. `domain`
143
+ also takes `hint` and `placeholder`.
144
+ - `inputs` (on an auth entry, keyed by env var name) sets a field's `label`, `hint` and `placeholder`.
145
+ - A `link` action opens an `https://` URL. `{domain}` is the typed domain, `{webHost}` its web host
146
+ (`api.github.com` → `github.com`, `api.<name>.ghe.com` → `<name>.ghe.com`, `<host>/api/v3` → `<host>`), `{server}`
147
+ the server name. The link follows the domain field and stays hidden while it needs a domain and there is none.
148
+ - A `cli` action carries its own `command` and `args`; core has no list of tools. `command` must be a program name
149
+ found on PATH (no path, no arguments), and `args` may use `{domain}` and `{webHost}`. On click the CLI process, not
150
+ the page, runs it without a shell, with a 15 s timeout; the token it prints goes straight to the API check and never
151
+ reaches the browser. It is offered only for an entry with a single credential, and only when the program is on PATH
152
+ when the form opens. Nothing runs without the click.
153
+
154
+ GitLab offers **Use GitLab CLI**, which runs `glab config get token --host <host>`. **Create on GitLab ↗** opens the personal access token page of the server's
155
+ host (`<host>/-/user_settings/personal_access_tokens`, under the relative URL root if the domain has one), prefilled
156
+ with a name and the `api` scope.
157
+
158
+ The CLI button is offered only for options with a single field. A domain typed in the form is used once it is valid. An imported token is saved like a
159
+ typed one: only after the API accepts it. Manifests can be updated remotely (see below), so only use a registry you
160
+ trust: its `cli` buttons name the programs mcpkit runs when you click them.
161
+
162
+ **Domain.** A server whose host differs per user (GitHub Enterprise, self-hosted GitLab, Jira...) writes
163
+ `{domain}` in `baseUrl` and, if it has them, in the OAuth URLs, and declares `domain`:
164
+
165
+ ```jsonc
166
+ "domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" } // all optional
167
+ ```
168
+
169
+ The domain comes from the env var, else `config.json`, else `default`. The form shows it prefilled and lets the
170
+ user change it (`host[:port][/path]`, no scheme), unless the env var is set.
171
+
172
+ **OAuth 2.0 with PKCE.** The user signs in once in the browser against the provider directly:
173
+
174
+ ```jsonc
175
+ {
176
+ "type": "oauth",
177
+ "authorizationUrl": "https://example.com/oauth/authorize", // https only, {domain} allowed
178
+ "tokenUrl": "https://example.com/oauth/token", // https only, {domain} allowed
179
+ "clientId": "public-client-id",
180
+ "clientSecretEnv": "EXAMPLE_CLIENT_SECRET", // optional, for providers that need one
181
+ "scopes": ["read", "write"], // optional
182
+ "redirectPort": 8976 // optional, 0 picks a free port
183
+ }
184
+ ```
185
+
186
+ The sign-in starts on the first tool call that has no working token: `mcpkit serve` prints the URL to stderr
187
+ and opens the browser. The redirect goes to `http://127.0.0.1:<port>/callback`, and the authorization code is
188
+ exchanged with a S256 code verifier. The token is saved to `~/.mcpkit/tokens.json` (`MCPKIT_HOME` overrides)
189
+ with file mode `0600`, together with the entry that issued it. Tool calls send it as a Bearer token and refresh
190
+ it before it expires. Concurrent calls share one sign-in. If the MCP client gives up waiting, the sign-in still
191
+ finishes and the next call uses the token.
@@ -9,6 +9,8 @@ export declare const array: (items: JsonSchema, description?: string) => Param;
9
9
  export declare interface AuthContext {
10
10
  env: Env;
11
11
  fetchImpl: typeof fetch;
12
+ /** The directory the calling client works in; it picks the host of a server used on several hosts. */
13
+ projectDir?: string;
12
14
  /** Shows the user the URL that starts a browser sign-in; without it a call never signs in. */
13
15
  onAuthorizationUrl?: (url: string) => void;
14
16
  /** Credentials saved from the credentials form; env vars win over them. */
@@ -23,7 +25,7 @@ export declare class AuthError extends Error {
23
25
  export declare type AuthSpec = NoneAuth | BearerAuth | HeaderAuth | QueryAuth | BasicAuth | OAuthAuth;
24
26
 
25
27
  declare interface BasicAuth {
26
- type: 'basic';
28
+ type: "basic";
27
29
  usernameEnv: string;
28
30
  passwordEnv: string;
29
31
  /** Shown for this option in the credentials form instead of its auth type and env vars. */
@@ -33,7 +35,7 @@ declare interface BasicAuth {
33
35
  }
34
36
 
35
37
  declare interface BearerAuth {
36
- type: 'bearer';
38
+ type: "bearer";
37
39
  env: string;
38
40
  /** Shown for this option in the credentials form instead of its auth type and env vars. */
39
41
  label?: string;
@@ -43,7 +45,7 @@ declare interface BearerAuth {
43
45
 
44
46
  export declare const boolean: (description?: string, options?: ParamOptions) => Param;
45
47
 
46
- /** Expects args already passed through prepareToolArgs. */
48
+ /** Expects args already passed through prepareToolArgs and loadFileArgs. */
47
49
  export declare const buildRequest: (manifest: Manifest, tool: ToolSpec, args: ToolArgs, auth: ResolvedAuth) => HttpRequest;
48
50
 
49
51
  /** A command that prints a token on stdout; run without a shell. */
@@ -54,7 +56,7 @@ export declare interface CliTokenCommand {
54
56
 
55
57
  export declare const compareVersions: (left: string, right: string) => number;
56
58
 
57
- /** Plain text in a 0600 file under the mcpkit home, read on every call so all running servers see each other's saves. */
59
+ /** Plain text in the 0600 config file under the mcpkit home, by server and host, read on every call so all running servers see each other's saves. */
58
60
  export declare const createFileSecretStore: (env?: Env) => SecretStore;
59
61
 
60
62
  export declare interface CredentialField {
@@ -122,6 +124,8 @@ export declare interface DomainField {
122
124
  placeholder: string;
123
125
  /** The domain in use, prefilled in the form; empty when there is none yet. */
124
126
  value: string;
127
+ /** Hosts already used with this server, offered for picking; the user can still type a new one. */
128
+ knownHosts: readonly string[];
125
129
  }
126
130
 
127
131
  /** Lets one server talk to any host of the same API, for example a self-hosted GitHub Enterprise. */
@@ -134,6 +138,8 @@ export declare interface DomainSpec {
134
138
  default?: string;
135
139
  /** Env var that sets the domain; when it is set the form does not ask for one. */
136
140
  env?: string;
141
+ /** Picks the saved host the git remote of the working directory points at, so a repository needs no question. */
142
+ matchGitRemote?: boolean;
137
143
  }
138
144
 
139
145
  /** A deployment of the same API that needs other requests, for example Atlassian Cloud next to Data Center. */
@@ -149,9 +155,10 @@ export declare interface ExecuteOptions {
149
155
  fetchImpl?: typeof fetch;
150
156
  timeoutMs?: number;
151
157
  env?: Env;
152
- onAuthorizationUrl?: AuthContext['onAuthorizationUrl'];
153
- secretStore?: AuthContext['secretStore'];
154
- requestCredentials?: AuthContext['requestCredentials'];
158
+ onAuthorizationUrl?: AuthContext["onAuthorizationUrl"];
159
+ projectDir?: AuthContext["projectDir"];
160
+ secretStore?: AuthContext["secretStore"];
161
+ requestCredentials?: AuthContext["requestCredentials"];
155
162
  }
156
163
 
157
164
  export declare const executeTool: (manifest: Manifest, tool: ToolSpec, rawArgs: ToolArgs | undefined, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<unknown>;
@@ -177,7 +184,7 @@ export declare type FixedValues = Readonly<Record<string, FixedValue>>;
177
184
  export declare const getPath: (source: unknown, path: string) => unknown;
178
185
 
179
186
  declare interface HeaderAuth {
180
- type: 'header';
187
+ type: "header";
181
188
  env: string;
182
189
  name: string;
183
190
  /** Shown for this option in the credentials form instead of its auth type and env vars. */
@@ -195,14 +202,21 @@ export declare interface HttpRequest {
195
202
  url: string;
196
203
  method: HttpMethod;
197
204
  headers: Readonly<Record<string, string>>;
198
- body?: string;
205
+ body?: string | FormData | Blob;
206
+ }
207
+
208
+ /** An MCP server reached over Streamable HTTP; the manifest's `auth` signs the requests. */
209
+ export declare interface HttpUpstream {
210
+ type: "http";
211
+ /** May contain `{domain}`. */
212
+ url: string;
199
213
  }
200
214
 
201
215
  /** Builds an object input schema; `required` is derived from the params. */
202
216
  export declare const input: (params?: ParamMap) => InputSchema;
203
217
 
204
218
  export declare interface InputSchema extends JsonSchema {
205
- type: 'object';
219
+ type: "object";
206
220
  }
207
221
 
208
222
  export declare type InteractiveAuth = OAuthAuth;
@@ -221,7 +235,7 @@ export declare const isValidCredentialResponse: (request: CredentialRequest, res
221
235
  export declare const isValidManifest: (value: unknown) => value is Manifest;
222
236
 
223
237
  export declare interface JsonSchema {
224
- type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
238
+ type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
225
239
  description?: string;
226
240
  default?: unknown;
227
241
  enum?: readonly unknown[];
@@ -238,7 +252,7 @@ export declare interface Manifest {
238
252
  category: string;
239
253
  version: string;
240
254
  description?: string;
241
- /** May contain `{domain}`, as may the oauth URLs; `domain` then says where the value comes from. */
255
+ /** May contain `{domain}`, as may the oauth URLs; `domain` then says where the value comes from. An `upstream` manifest never requests it, so it only names the service's https home. */
242
256
  baseUrl: string;
243
257
  domain?: DomainSpec;
244
258
  /** Deployments picked by the domain's host; a domain matching none uses the tools' own requests. */
@@ -248,6 +262,8 @@ export declare interface Manifest {
248
262
  auth?: readonly AuthSpec[];
249
263
  /** Page-wide texts of the credentials page, replacing mcpkit's defaults. */
250
264
  ui?: UiSpec;
265
+ /** Another MCP server this one fronts: its tools are discovered at runtime, so `tools` stays empty. */
266
+ upstream?: UpstreamSpec;
251
267
  tools: readonly ToolSpec[];
252
268
  }
253
269
 
@@ -258,14 +274,14 @@ declare type NameList = readonly string[];
258
274
  export declare type NameMapping = Readonly<Record<string, string>>;
259
275
 
260
276
  declare interface NoneAuth {
261
- type: 'none';
277
+ type: "none";
262
278
  }
263
279
 
264
280
  export declare const number: (description?: string, options?: ParamOptions) => Param;
265
281
 
266
282
  /** OAuth 2.0 authorization code flow with PKCE; the browser sign-in starts on the first tool call without a stored token. */
267
283
  export declare interface OAuthAuth {
268
- type: 'oauth';
284
+ type: "oauth";
269
285
  authorizationUrl: string;
270
286
  tokenUrl: string;
271
287
  clientId: string;
@@ -273,6 +289,12 @@ export declare interface OAuthAuth {
273
289
  scopes?: readonly string[];
274
290
  /** Loopback port for the redirect URI; 0 picks a free port. */
275
291
  redirectPort?: number;
292
+ /** Extra query parameters on the authorization URL, e.g. a provider's flag for a long-lived refresh token. */
293
+ authorizationParams?: Readonly<Record<string, string>>;
294
+ /** Where the client id and secret travel on token requests: the form body (default) or an HTTP Basic header (an absent secret is sent empty). */
295
+ clientAuthentication?: "body" | "basic";
296
+ /** Extra headers on token requests, for providers that reject anonymous clients. */
297
+ tokenHeaders?: Readonly<Record<string, string>>;
276
298
  }
277
299
 
278
300
  export declare const oneOf: (values: readonly string[], description?: string, options?: ParamOptions) => Param;
@@ -289,12 +311,12 @@ export declare interface Param extends JsonSchema {
289
311
 
290
312
  export declare type ParamMap = Readonly<Record<string, Param>>;
291
313
 
292
- export declare type ParamOptions = Pick<JsonSchema, 'default' | 'enum'>;
314
+ export declare type ParamOptions = Pick<JsonSchema, "default" | "enum">;
293
315
 
294
316
  export declare const prepareToolArgs: (tool: ToolSpec, rawArgs?: ToolArgs) => any;
295
317
 
296
318
  declare interface QueryAuth {
297
- type: 'query';
319
+ type: "query";
298
320
  env: string;
299
321
  name: string;
300
322
  /** Shown for this option in the credentials form instead of its auth type and env vars. */
@@ -310,7 +332,22 @@ declare interface RequestSpec {
310
332
  query?: ArgSpec;
311
333
  /** Outgoing keys may be dotted paths such as `fields.project.key` or `ancestors.0.id` to build nested JSON. */
312
334
  body?: ArgSpec;
335
+ /** Names the argument sent unchanged as the whole JSON body (an array, string or free-form object); excludes `body` and `fixedBody`. */
336
+ bodyArg?: string;
337
+ /** Defaults to `application/json`. A `text/*` type sends `bodyArg` as plain text, `multipart/form-data` sends `body` fields and `fileArgs` as form parts; any other type is sent as JSON. */
338
+ contentType?: string;
339
+ /** Outgoing query keys whose array values are joined with commas; other arrays repeat the key once per item. */
340
+ commaQuery?: readonly string[];
341
+ /**
342
+ * Names of arguments holding a local file path or an array of them. With `contentType` multipart/form-data the files become form
343
+ * parts; with `bodyArg` naming one of them the file is the raw request body.
344
+ */
345
+ fileArgs?: readonly string[];
346
+ /** Names the argument holding the local path a successful response is saved to, instead of being returned. */
347
+ saveToArg?: string;
313
348
  fixedQuery?: FixedValues;
349
+ /** Header values sent on every call; auth headers win over them. */
350
+ fixedHeaders?: Readonly<Record<string, string>>;
314
351
  /** Dotted paths like `body`; an argument with the same key wins. */
315
352
  fixedBody?: FixedValues;
316
353
  }
@@ -335,8 +372,10 @@ export declare interface ResponseSpec {
335
372
  fields?: FieldSpec;
336
373
  }
337
374
 
338
- /** The server a stored secret belongs to. */
339
- export declare type SecretOwner = Pick<Manifest, 'name' | 'category'>;
375
+ /** The server, and the host of it, a stored secret belongs to. */
376
+ export declare interface SecretOwner extends ServerKey {
377
+ domain?: string;
378
+ }
340
379
 
341
380
  /** Where credentials and domains entered in the credentials form are kept, per server and key. */
342
381
  export declare interface SecretStore {
@@ -346,11 +385,14 @@ export declare interface SecretStore {
346
385
 
347
386
  export declare const SERVER_NAME_PATTERN: RegExp;
348
387
 
388
+ /** Where a server's settings live in the config: `servers.<category>.<name>`. */
389
+ declare type ServerKey = Pick<Manifest, "name" | "category">;
390
+
349
391
  /** Runs the authorization code + PKCE flow through a loopback redirect and stores the token. */
350
392
  export declare const signIn: (serverName: string, auth: InteractiveAuth, { context, onAuthorizationUrl }: SignInOptions) => Promise<SignInResult>;
351
393
 
352
394
  export declare interface SignInCredentialResponse {
353
- method: 'sign-in';
395
+ method: "sign-in";
354
396
  domain?: string;
355
397
  }
356
398
 
@@ -365,6 +407,16 @@ export declare interface SignInResult {
365
407
  tokensFile: string;
366
408
  }
367
409
 
410
+ /** An MCP server started as a child process and spoken to over its stdio. */
411
+ export declare interface StdioUpstream {
412
+ type: "stdio";
413
+ /** A program name on PATH, never a path. */
414
+ command: string;
415
+ args?: readonly string[];
416
+ /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables. */
417
+ forwardEnv?: readonly string[];
418
+ }
419
+
368
420
  declare interface StoredToken {
369
421
  accessToken: string;
370
422
  tokenType: string;
@@ -379,7 +431,7 @@ declare interface StoredToken {
379
431
  export declare const string: (description?: string, options?: ParamOptions) => Param;
380
432
 
381
433
  export declare interface TokenCredentialResponse {
382
- method: 'token';
434
+ method: "token";
383
435
  /** `index` of the chosen credential option. */
384
436
  option: number;
385
437
  /** Values per field key. */
@@ -428,7 +480,7 @@ export declare type UiAction = UiLinkAction | UiCliAction;
428
480
  * and `args` may use `{domain}` and `{webHost}`.
429
481
  */
430
482
  export declare interface UiCliAction {
431
- type: 'cli';
483
+ type: "cli";
432
484
  label: string;
433
485
  command: string;
434
486
  args: readonly string[];
@@ -443,7 +495,7 @@ export declare interface UiInputSpec {
443
495
 
444
496
  /** A button that opens `url` in a new tab; `{domain}`, `{webHost}` and `{server}` are filled in. */
445
497
  export declare interface UiLinkAction {
446
- type: 'link';
498
+ type: "link";
447
499
  label: string;
448
500
  url: string;
449
501
  }
@@ -470,6 +522,8 @@ export declare interface UiTexts {
470
522
  domainLabel: string;
471
523
  domainHint: string;
472
524
  domainPlaceholder: string;
525
+ domainNewHost: string;
526
+ domainShowHosts: string;
473
527
  signInLabel: string;
474
528
  tokenDivider: string;
475
529
  credentialLegend: string;
@@ -493,10 +547,29 @@ export declare interface UiTexts {
493
547
  requestFailed: string;
494
548
  }
495
549
 
550
+ /** An upstream answered 401: the auth option that produced the credentials is rejected and the next one is tried. */
551
+ export declare class UnauthorizedError extends Error {
552
+ }
553
+
554
+ /** Everything needed to open one upstream connection: where to go, how requests are signed, what the child gets. */
555
+ export declare interface UpstreamAccess {
556
+ upstream: UpstreamSpec;
557
+ headers: Readonly<Record<string, string>>;
558
+ env: Readonly<Record<string, string>>;
559
+ }
560
+
561
+ export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
562
+
496
563
  /** The form answer comes over a local HTTP request, so it is checked against what was asked. */
497
564
  export declare const validateCredentialResponse: (request: CredentialRequest, response: unknown) => string[];
498
565
 
499
566
  /** Manifests can be downloaded at runtime, so they are treated as untrusted input. */
500
567
  export declare const validateManifest: (manifest: unknown) => string[];
501
568
 
569
+ /**
570
+ * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials; an HTTP one
571
+ * tries the manifest's auth options in order like an API call does, moving on when `run` throws UnauthorizedError.
572
+ */
573
+ export declare const withUpstreamAccess: <T>(manifest: Manifest, run: (access: UpstreamAccess) => Promise<T>, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<T>;
574
+
502
575
  export { }