@usemcpkit/core 0.8.2 → 0.8.4

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.
@@ -440,10 +440,12 @@ export declare interface StdioUpstream {
440
440
  command: string;
441
441
  /** May contain `{repo}`, the folder of `repo`'s clone. */
442
442
  args?: readonly string[];
443
- /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables; a missing one is an error. */
443
+ /** Names of credentials handed to the child as environment variables; one missing from the env and the secret store is asked for in the credentials form, saved once the server has started. */
444
444
  forwardEnv?: readonly string[];
445
445
  /** Names handed to the child when set, in the client's env or the secret store; the upstream decides what a missing one means. */
446
446
  optionalEnv?: readonly string[];
447
+ /** The credentials form for `forwardEnv`: `inputs` by env var name and link `actions`. */
448
+ ui?: UiSpec;
447
449
  /** When set, the program is run from this repository, cloned and set up on first use. */
448
450
  repo?: UpstreamRepo;
449
451
  /** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
@@ -524,6 +526,8 @@ export declare interface UiInputSpec {
524
526
  label?: string;
525
527
  hint?: string;
526
528
  placeholder?: string;
529
+ /** Whether the page masks what is typed; true when left out. Ids that are not secret can set it to false. */
530
+ secret?: boolean;
527
531
  }
528
532
 
529
533
  /** A button that opens `url` in a new tab; `{domain}`, `{webHost}` and `{server}` are filled in. */
@@ -621,7 +625,7 @@ export declare const validateCredentialResponse: (request: CredentialRequest, re
621
625
  export declare const validateManifest: (manifest: unknown) => string[];
622
626
 
623
627
  /**
624
- * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials; an HTTP one
628
+ * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials, asked for in the credentials form when missing and saved once `run` succeeded; an HTTP one
625
629
  * tries the manifest's auth options in order like an API call does, moving on when `run` throws UnauthorizedError.
626
630
  */
627
631
  export declare const withUpstreamAccess: <T>(manifest: Manifest, run: (access: UpstreamAccess) => Promise<T>, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<T>;
@@ -300,7 +300,9 @@ var validateUiInputs = (inputs, location, envNames) => {
300
300
  const inputLocation = `${location}.${name}`;
301
301
  if (!envNames.includes(name)) return [`${inputLocation}: "${name}" is not a credential of this auth entry (${envNames.join(", ")})`];
302
302
  if (!isJsonObject(input)) return [`${inputLocation} must be an object`];
303
- return UI_INPUT_KEYS.filter((key) => input[key] !== void 0 && typeof input[key] !== "string").map((key) => `${inputLocation}.${key} must be a string`);
303
+ const textErrors = UI_INPUT_KEYS.filter((key) => input[key] !== void 0 && typeof input[key] !== "string").map((key) => `${inputLocation}.${key} must be a string`);
304
+ const secretErrors = input.secret === void 0 || typeof input.secret === "boolean" ? [] : [`${inputLocation}.secret must be a boolean`];
305
+ return [...textErrors, ...secretErrors];
304
306
  });
305
307
  };
306
308
  //#endregion
@@ -418,6 +420,20 @@ var validateServerFields = (manifest) => {
418
420
  return errors;
419
421
  };
420
422
  //#endregion
423
+ //#region src/manifest/validation/ui/validate-stdio-ui.ts
424
+ /** A stdio upstream's form asks for its `forwardEnv` credentials; it has no domain and no CLI to take a token from. */
425
+ var validateStdioUi = (upstream) => {
426
+ const { ui } = upstream;
427
+ if (ui === void 0) return [];
428
+ if (!isJsonObject(ui)) return ["upstream.ui must be an object"];
429
+ const forwardEnv = Array.isArray(upstream.forwardEnv) ? upstream.forwardEnv.map(String) : [];
430
+ return [
431
+ ...Object.keys(ui).filter((key) => !UI_AUTH_KEYS.includes(key)).map((key) => `upstream.ui.${key} is not allowed here`),
432
+ ...validateUiInputs(ui.inputs, "upstream.ui.inputs", forwardEnv),
433
+ ...validateUiActions(ui.actions, "upstream.ui.actions", false, false)
434
+ ];
435
+ };
436
+ //#endregion
421
437
  //#region src/errors/describe-error.ts
422
438
  var describeError = (error) => error instanceof Error ? error.message : String(error);
423
439
  //#endregion
@@ -475,7 +491,7 @@ var validateStdio = (upstream) => {
475
491
  if (upstream.forwardEnv !== void 0 && !isStringList(upstream.forwardEnv)) errors.push("upstream.forwardEnv must be a list of strings");
476
492
  if (upstream.optionalEnv !== void 0 && !isStringList(upstream.optionalEnv)) errors.push("upstream.optionalEnv must be a list of strings");
477
493
  if (upstream.repo !== void 0) errors.push(...validateUpstreamRepo(upstream.repo));
478
- return errors;
494
+ return [...errors, ...validateStdioUi(upstream)];
479
495
  };
480
496
  var validateUpstream = (upstream) => {
481
497
  if (!isJsonObject(upstream)) return ["upstream must be an object"];
@@ -1387,7 +1403,7 @@ var toCredentialField = (key, label, secret, texts, spec) => {
1387
1403
  label: spec?.label ?? label,
1388
1404
  hint: spec?.hint ?? fillTemplate(texts.fieldHint, { key }),
1389
1405
  placeholder: spec?.placeholder ?? "",
1390
- secret
1406
+ secret: spec?.secret ?? secret
1391
1407
  };
1392
1408
  };
1393
1409
  //#endregion
@@ -2113,9 +2129,46 @@ var nameUpstreamTool = (rules, upstreamName) => {
2113
2129
  }
2114
2130
  };
2115
2131
  //#endregion
2132
+ //#region src/execution/upstream/request-forwarded-credentials.ts
2133
+ var FORWARDED_OPTION_INDEX = 0;
2134
+ /** Asks the user in the credentials form for `names`, the credentials of a stdio upstream that nothing provided. */
2135
+ var requestForwardedCredentials = async (manifest, upstream, names, requestCredentials) => {
2136
+ const texts = buildUiTexts(manifest);
2137
+ const { request, response } = await requestCredentialsOnce(manifest.name, async () => {
2138
+ const fields = names.map((name) => toCredentialField(name, name, true, texts, upstream.ui?.inputs?.[name]));
2139
+ const option = {
2140
+ index: FORWARDED_OPTION_INDEX,
2141
+ label: texts.credentialLegend,
2142
+ fields,
2143
+ actions: toOptionActions(upstream.ui, manifest.name, fields.length)
2144
+ };
2145
+ return {
2146
+ serverName: manifest.name,
2147
+ texts,
2148
+ options: [option],
2149
+ signIn: false
2150
+ };
2151
+ }, requestCredentials);
2152
+ const errors = validateCredentialResponse(request, response);
2153
+ if (errors.length > 0 || response.method !== "token") throw new AuthError(`${manifest.name}: invalid credentials form answer: ${errors.join("; ")}`);
2154
+ return trimValues(response.values);
2155
+ };
2156
+ //#endregion
2157
+ //#region src/execution/upstream/ask-for-missing-credentials.ts
2158
+ /** The values the user enters for `missing`; without a form to ask in, the missing names are the error. */
2159
+ var askForMissingCredentials = (manifest, upstream, missing, requestCredentials) => {
2160
+ if (!requestCredentials) throw new AuthError(`${manifest.name}: missing credential, set ${missing.join(", ")} in the client's env for mcpkit`);
2161
+ return requestForwardedCredentials(manifest, upstream, missing, requestCredentials);
2162
+ };
2163
+ //#endregion
2116
2164
  //#region src/execution/upstream/read-forwarded-env.ts
2117
- /** Each forwarded credential from its env var, else from the secret store; an optional one is left out when unset. */
2118
- var readForwardedEnv = async (manifest, { forwardEnv = [], optionalEnv = [] }, domain, context) => {
2165
+ /**
2166
+ * Each forwarded credential from its env var, else from the secret store; an optional one is left out when unset.
2167
+ * A required one found nowhere is asked for in the credentials form when the caller has one, and `commit` saves
2168
+ * what was entered once the upstream has started with it.
2169
+ */
2170
+ var readForwardedEnv = async (manifest, upstream, domain, context) => {
2171
+ const { forwardEnv = [], optionalEnv = [] } = upstream;
2119
2172
  const owner = {
2120
2173
  name: manifest.name,
2121
2174
  category: manifest.category,
@@ -2124,14 +2177,23 @@ var readForwardedEnv = async (manifest, { forwardEnv = [], optionalEnv = [] }, d
2124
2177
  const read = async (name) => [name, context.env[name] || await context.secretStore?.get(owner, name)];
2125
2178
  const required = await Promise.all(forwardEnv.map(read));
2126
2179
  const missing = required.filter(([, value]) => !value).map(([name]) => name);
2127
- if (missing.length > 0) throw new AuthError(`${manifest.name}: missing credential, set ${missing.join(", ")} in the client's env for mcpkit`);
2180
+ const entered = missing.length === 0 ? {} : await askForMissingCredentials(manifest, upstream, missing, context.requestCredentials);
2128
2181
  const optional = (await Promise.all(optionalEnv.map(read))).filter(([, value]) => value);
2129
- return Object.fromEntries([...required, ...optional].map(([name, value]) => [name, value ?? ""]));
2182
+ const found = [...required, ...optional].filter(([, value]) => value);
2183
+ const env = {
2184
+ ...Object.fromEntries(found.map(([name, value]) => [name, value ?? ""])),
2185
+ ...entered
2186
+ };
2187
+ const commit = () => saveCredentials(owner, entered, context.secretStore);
2188
+ return {
2189
+ env,
2190
+ commit
2191
+ };
2130
2192
  };
2131
2193
  //#endregion
2132
2194
  //#region src/execution/upstream/with-upstream-access.ts
2133
2195
  /**
2134
- * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials; an HTTP one
2196
+ * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials, asked for in the credentials form when missing and saved once `run` succeeded; an HTTP one
2135
2197
  * tries the manifest's auth options in order like an API call does, moving on when `run` throws UnauthorizedError.
2136
2198
  */
2137
2199
  var withUpstreamAccess = async (manifest, run, { fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, env = process.env, ...hooks } = {}) => {
@@ -2144,11 +2206,16 @@ var withUpstreamAccess = async (manifest, run, { fetchImpl = fetch, timeoutMs =
2144
2206
  const domain = await resolveDomain(manifest, context);
2145
2207
  const upstream = applyDomain(manifest, domain).upstream;
2146
2208
  if (!upstream) throw new AuthError(`${manifest.name} has no upstream`);
2147
- if (upstream.type === "stdio") return run({
2148
- upstream,
2149
- headers: {},
2150
- env: await readForwardedEnv(manifest, upstream, domain, context)
2151
- });
2209
+ if (upstream.type === "stdio") {
2210
+ const forwarded = await readForwardedEnv(manifest, upstream, domain, context);
2211
+ const result = await run({
2212
+ upstream,
2213
+ headers: {},
2214
+ env: forwarded.env
2215
+ });
2216
+ await forwarded.commit();
2217
+ return result;
2218
+ }
2152
2219
  const failures = [];
2153
2220
  for (const candidate of orderAuthCandidates(manifest.name, buildAuthCandidates(manifest, domain, context))) try {
2154
2221
  const resolution = await candidate.resolve();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usemcpkit/core",
3
- "version": "0.8.2",
3
+ "version": "0.8.4",
4
4
  "description": "Manifest-driven MCP tool execution: manifest validation, HTTP execution, response mapping, auth and the server SDK.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -35,7 +35,7 @@
35
35
  "devDependencies": {
36
36
  "@biomejs/biome": "2.5.15",
37
37
  "@microsoft/api-extractor": "^7.59.4",
38
- "@usemcpkit/testing": "0.8.2",
38
+ "@usemcpkit/testing": "0.8.4",
39
39
  "typescript": "^5.9.0",
40
40
  "vite": "^8.0.0",
41
41
  "vite-plugin-dts": "5.1.2",