@usemcpkit/core 0.5.0 → 0.7.0

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.
@@ -177,6 +177,16 @@ export declare type FixedValue = string | number | boolean;
177
177
  /** Values sent on every call, keyed like the outgoing keys of the request part they belong to. */
178
178
  export declare type FixedValues = Readonly<Record<string, FixedValue>>;
179
179
 
180
+ /**
181
+ * Functions the CLI's native form window binds into the page: close it, fit it to `{ width, height }`, and open a link
182
+ * in the default browser (a webview has no tabs, so `target="_blank"` links go nowhere).
183
+ */
184
+ export declare const FORM_WINDOW_BINDINGS: {
185
+ readonly close: "mcpkitCloseWindow";
186
+ readonly fit: "mcpkitFitWindow";
187
+ readonly openLink: "mcpkitOpenLink";
188
+ };
189
+
180
190
  /**
181
191
  * Resolves `a.b.c` paths; a `name[]` segment maps the rest of the path over an array.
182
192
  * The return type is declared because TypeScript cannot infer it for this recursive function.
@@ -210,6 +220,8 @@ export declare interface HttpUpstream {
210
220
  type: "http";
211
221
  /** May contain `{domain}`. */
212
222
  url: string;
223
+ /** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
224
+ naming?: readonly UpstreamNameRule[];
213
225
  }
214
226
 
215
227
  /** Builds an object input schema; `required` is derived from the params. */
@@ -273,6 +285,13 @@ declare type NameList = readonly string[];
273
285
 
274
286
  export declare type NameMapping = Readonly<Record<string, string>>;
275
287
 
288
+ /**
289
+ * The catalog name `rules` give an upstream tool, from the first rule whose `match` finds the tool name, or undefined
290
+ * when none does. A name that is not `<group>:<resource>:<action>` in lowercase snake case is an error in the
291
+ * manifest, never silently replaced.
292
+ */
293
+ export declare const nameUpstreamTool: (rules: readonly UpstreamNameRule[] | undefined, upstreamName: string) => string | undefined;
294
+
276
295
  declare interface NoneAuth {
277
296
  type: "none";
278
297
  }
@@ -325,6 +344,13 @@ declare interface QueryAuth {
325
344
  ui?: UiSpec;
326
345
  }
327
346
 
347
+ /** One program run inside the clone after checkout, such as an install or a build; no shell. */
348
+ export declare interface RepoSetupStep {
349
+ /** A program name on PATH, never a path. */
350
+ command: string;
351
+ args?: readonly string[];
352
+ }
353
+
328
354
  declare interface RequestSpec {
329
355
  method: HttpMethod;
330
356
  /** `{arg}` placeholders are replaced by URL-encoded argument values. */
@@ -412,9 +438,16 @@ export declare interface StdioUpstream {
412
438
  type: "stdio";
413
439
  /** A program name on PATH, never a path. */
414
440
  command: string;
441
+ /** May contain `{repo}`, the folder of `repo`'s clone. */
415
442
  args?: readonly string[];
416
- /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables. */
443
+ /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables; a missing one is an error. */
417
444
  forwardEnv?: readonly string[];
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
+ optionalEnv?: readonly string[];
447
+ /** When set, the program is run from this repository, cloned and set up on first use. */
448
+ repo?: UpstreamRepo;
449
+ /** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
450
+ naming?: readonly UpstreamNameRule[];
418
451
  }
419
452
 
420
453
  declare interface StoredToken {
@@ -536,6 +569,7 @@ export declare interface UiTexts {
536
569
  actionsDivider: string;
537
570
  cancel: string;
538
571
  submit: string;
572
+ checking: string;
539
573
  requiredField: string;
540
574
  savedTitle: string;
541
575
  savedBody: string;
@@ -558,6 +592,26 @@ export declare interface UpstreamAccess {
558
592
  env: Readonly<Record<string, string>>;
559
593
  }
560
594
 
595
+ /** Renames the tools of an upstream server into mcpkit's `<group>:<resource>:<action>` form. */
596
+ export declare interface UpstreamNameRule {
597
+ /** A regular expression tested against the upstream tool name; the first rule that matches names the tool. */
598
+ match: string;
599
+ /** The new name, with `$1`… for captures and `$&` for the whole upstream name: `org:members:$&`. */
600
+ name: string;
601
+ }
602
+
603
+ /** A git repository the upstream server is run from, cloned on first use into `~/.mcpkit/repos/<category>/<name>`. */
604
+ export declare interface UpstreamRepo {
605
+ url: string;
606
+ /**
607
+ * Commit, tag or branch to check out. A commit is pinned and never compared; a tag or branch is compared with the
608
+ * remote on use and the clone rebuilt when it moved. The checkout is run as code, so pin a commit unless you trust the ref.
609
+ */
610
+ ref: string;
611
+ /** Run in order in the clone once, after checkout, with no credentials in the environment. */
612
+ setup?: readonly RepoSetupStep[];
613
+ }
614
+
561
615
  export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
562
616
 
563
617
  /** The form answer comes over a local HTTP request, so it is checked against what was asked. */
@@ -22,6 +22,15 @@ var CREDENTIALS_FORM_API = {
22
22
  import: "/api/import"
23
23
  };
24
24
  var CREDENTIALS_REQUEST_ELEMENT_ID = "mcpkit-request";
25
+ /**
26
+ * Functions the CLI's native form window binds into the page: close it, fit it to `{ width, height }`, and open a link
27
+ * in the default browser (a webview has no tabs, so `target="_blank"` links go nowhere).
28
+ */
29
+ var FORM_WINDOW_BINDINGS = {
30
+ close: "mcpkitCloseWindow",
31
+ fit: "mcpkitFitWindow",
32
+ openLink: "mcpkitOpenLink"
33
+ };
25
34
  var CREDENTIALS_FORM_SESSION_HEADER = "X-Mcpkit-Session";
26
35
  var CONFIG_FILE_NAME = "config.json";
27
36
  var SECRETS_FILE_NAME = "secrets.json";
@@ -201,9 +210,10 @@ var DEFAULT_UI_TEXTS = {
201
210
  actionsDivider: "or get a token",
202
211
  cancel: "Cancel",
203
212
  submit: "Save and continue",
213
+ checking: "Checking with {server}…",
204
214
  requiredField: "{label} is required",
205
215
  savedTitle: "{server} is connected",
206
- savedBody: "The credentials are saved in ~/.mcpkit/config.json. This tab closes by itself in a few seconds; you can also close it and go back to your MCP client.",
216
+ savedBody: "The credentials are saved in ~/.mcpkit/config.json. This window closes by itself in a few seconds; you can also close it and go back to your MCP client.",
207
217
  signingInTitle: "Continue in the new tab",
208
218
  signingInBody: "Approve access to {server} in the sign-in tab that just opened. You can close this one.",
209
219
  cancelledTitle: "Cancelled",
@@ -408,18 +418,70 @@ var validateServerFields = (manifest) => {
408
418
  return errors;
409
419
  };
410
420
  //#endregion
421
+ //#region src/errors/describe-error.ts
422
+ var describeError = (error) => error instanceof Error ? error.message : String(error);
423
+ //#endregion
424
+ //#region src/errors/is-missing-file-error.ts
425
+ var isMissingFileError = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
426
+ //#endregion
427
+ //#region src/manifest/validation/server/validate-upstream-naming.ts
428
+ var MAX_MATCH_LENGTH = 200;
429
+ var NAME_TEMPLATE_PATTERN = /^[a-z0-9_$&]+(:[a-z0-9_$&]+){2,}$/;
430
+ var validateRule = (rule, position) => {
431
+ const label = `upstream.naming[${position}]`;
432
+ if (!isJsonObject(rule)) return [`${label} must be an object`];
433
+ const errors = [];
434
+ if (typeof rule.match !== "string" || rule.match === "" || rule.match.length > MAX_MATCH_LENGTH) errors.push(`${label}.match must be a regular expression of at most ${MAX_MATCH_LENGTH} characters`);
435
+ else try {
436
+ new RegExp(rule.match);
437
+ } catch (error) {
438
+ errors.push(`${label}.match is not a valid regular expression: ${describeError(error)}`);
439
+ }
440
+ if (typeof rule.name !== "string" || !NAME_TEMPLATE_PATTERN.test(rule.name)) errors.push(`${label}.name must be <group>:<resource>:<action> with $1… or $& for the upstream name`);
441
+ return errors;
442
+ };
443
+ var validateUpstreamNaming = (naming) => Array.isArray(naming) ? naming.flatMap(validateRule) : ["upstream.naming must be a list of rules"];
444
+ //#endregion
445
+ //#region src/manifest/validation/server/validate-upstream-repo.ts
446
+ var PROGRAM_NAME_PATTERN$1 = /^[A-Za-z0-9._-]+$/;
447
+ var REF_PATTERN = /^[A-Za-z0-9._][A-Za-z0-9._/-]*$/;
448
+ var validateSetupStep = (step, position) => {
449
+ const label = `upstream.repo.setup[${position}]`;
450
+ if (!isJsonObject(step)) return [`${label} must be an object`];
451
+ const errors = [];
452
+ if (typeof step.command !== "string" || !PROGRAM_NAME_PATTERN$1.test(step.command)) errors.push(`${label}.command must be a program name on PATH, not a path`);
453
+ if (step.args !== void 0 && !isStringList(step.args)) errors.push(`${label}.args must be a list of strings`);
454
+ return errors;
455
+ };
456
+ var validateUpstreamRepo = (repo) => {
457
+ if (!isJsonObject(repo)) return ["upstream.repo must be an object"];
458
+ const errors = [];
459
+ if (!isHttpsUrl(repo.url)) errors.push("upstream.repo.url must be an https:// URL");
460
+ if (typeof repo.ref !== "string" || !REF_PATTERN.test(repo.ref)) errors.push("upstream.repo.ref must be a commit, tag or branch, not starting with '-'");
461
+ if (repo.setup !== void 0) {
462
+ if (Array.isArray(repo.setup)) errors.push(...repo.setup.flatMap(validateSetupStep));
463
+ else errors.push("upstream.repo.setup must be a list of steps");
464
+ }
465
+ return errors;
466
+ };
467
+ //#endregion
411
468
  //#region src/manifest/validation/server/validate-upstream.ts
412
469
  var PROGRAM_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
413
- var validateUpstream = (upstream) => {
414
- if (!isJsonObject(upstream)) return ["upstream must be an object"];
415
- if (upstream.type === "http") return isHttpsUrl(upstream.url) ? [] : ["upstream.url must be an https:// URL"];
416
- if (upstream.type !== "stdio") return ["upstream.type must be \"http\" or \"stdio\""];
470
+ var validateHttp = (upstream) => isHttpsUrl(upstream.url) ? [] : ["upstream.url must be an https:// URL"];
471
+ var validateStdio = (upstream) => {
417
472
  const errors = [];
418
473
  if (typeof upstream.command !== "string" || !PROGRAM_NAME_PATTERN.test(upstream.command)) errors.push("upstream.command must be a program name on PATH, not a path");
419
474
  if (upstream.args !== void 0 && !isStringList(upstream.args)) errors.push("upstream.args must be a list of strings");
420
475
  if (upstream.forwardEnv !== void 0 && !isStringList(upstream.forwardEnv)) errors.push("upstream.forwardEnv must be a list of strings");
476
+ if (upstream.optionalEnv !== void 0 && !isStringList(upstream.optionalEnv)) errors.push("upstream.optionalEnv must be a list of strings");
477
+ if (upstream.repo !== void 0) errors.push(...validateUpstreamRepo(upstream.repo));
421
478
  return errors;
422
479
  };
480
+ var validateUpstream = (upstream) => {
481
+ if (!isJsonObject(upstream)) return ["upstream must be an object"];
482
+ if (upstream.type !== "http" && upstream.type !== "stdio") return ["upstream.type must be \"http\" or \"stdio\""];
483
+ return [...upstream.type === "http" ? validateHttp(upstream) : validateStdio(upstream), ...upstream.naming === void 0 ? [] : validateUpstreamNaming(upstream.naming)];
484
+ };
423
485
  //#endregion
424
486
  //#region src/manifest/validation/find-duplicates.ts
425
487
  var findDuplicates = (values) => [...new Set(values.filter((value, index) => values.indexOf(value) !== index))];
@@ -663,12 +725,6 @@ var mergeLegacySecrets = (config, legacy) => {
663
725
  };
664
726
  };
665
727
  //#endregion
666
- //#region src/errors/describe-error.ts
667
- var describeError = (error) => error instanceof Error ? error.message : String(error);
668
- //#endregion
669
- //#region src/errors/is-missing-file-error.ts
670
- var isMissingFileError = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
671
- //#endregion
672
728
  //#region src/auth/token-store/read-tokens-text.ts
673
729
  var readTokensText = async (file) => {
674
730
  try {
@@ -2040,18 +2096,37 @@ var executeTool = async (manifest, tool, rawArgs, { fetchImpl = fetch, timeoutMs
2040
2096
  return mapResponse(body, sentTool.response);
2041
2097
  };
2042
2098
  //#endregion
2099
+ //#region src/execution/upstream/name-upstream-tool.ts
2100
+ var CATALOG_NAME_PATTERN = /^[a-z][a-z0-9_]*(:[a-z][a-z0-9_]*){2,}$/;
2101
+ /**
2102
+ * The catalog name `rules` give an upstream tool, from the first rule whose `match` finds the tool name, or undefined
2103
+ * when none does. A name that is not `<group>:<resource>:<action>` in lowercase snake case is an error in the
2104
+ * manifest, never silently replaced.
2105
+ */
2106
+ var nameUpstreamTool = (rules, upstreamName) => {
2107
+ for (const rule of rules ?? []) {
2108
+ const pattern = new RegExp(rule.match);
2109
+ if (!pattern.test(upstreamName)) continue;
2110
+ const name = upstreamName.replace(pattern, rule.name);
2111
+ if (!CATALOG_NAME_PATTERN.test(name)) throw new Error(`naming rule "${rule.match}" turned "${upstreamName}" into "${name}", which is not <group>:<resource>:<action>`);
2112
+ return name;
2113
+ }
2114
+ };
2115
+ //#endregion
2043
2116
  //#region src/execution/upstream/read-forwarded-env.ts
2044
- /** Each forwarded credential from its env var, else from the secret store. */
2045
- var readForwardedEnv = async (manifest, { forwardEnv = [] }, domain, context) => {
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) => {
2046
2119
  const owner = {
2047
2120
  name: manifest.name,
2048
2121
  category: manifest.category,
2049
2122
  domain
2050
2123
  };
2051
- const entries = await Promise.all(forwardEnv.map(async (name) => [name, context.env[name] || await context.secretStore?.get(owner, name)]));
2052
- const missing = entries.filter(([, value]) => !value).map(([name]) => name);
2124
+ const read = async (name) => [name, context.env[name] || await context.secretStore?.get(owner, name)];
2125
+ const required = await Promise.all(forwardEnv.map(read));
2126
+ const missing = required.filter(([, value]) => !value).map(([name]) => name);
2053
2127
  if (missing.length > 0) throw new AuthError(`${manifest.name}: missing credential, set ${missing.join(", ")} in the client's env for mcpkit`);
2054
- return Object.fromEntries(entries.map(([name, value]) => [name, value ?? ""]));
2128
+ const optional = (await Promise.all(optionalEnv.map(read))).filter(([, value]) => value);
2129
+ return Object.fromEntries([...required, ...optional].map(([name, value]) => [name, value ?? ""]));
2055
2130
  };
2056
2131
  //#endregion
2057
2132
  //#region src/execution/upstream/with-upstream-access.ts
@@ -2196,4 +2271,4 @@ var compareVersions = (left, right) => {
2196
2271
  return 0;
2197
2272
  };
2198
2273
  //#endregion
2199
- export { AuthError, CREDENTIALS_FORM_API, CREDENTIALS_FORM_SESSION_HEADER, CREDENTIALS_REQUEST_ELEMENT_ID, DEFAULT_UI_TEXTS, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, ToolError, UnauthorizedError, applyDomain, array, boolean, buildRequest, compareVersions, createFileSecretStore, defineServer, defineTool, defineUI, describeAuth, describeAuthSpec, describeError, executeTool, fillTemplate, getPath, input, isDomainValue, isInteractiveAuth, isJsonObject, isMissingFileError, isValidCredentialResponse, isValidManifest, listAuthEnvNames, mapResponse, number, oneOf, optional, prepareToolArgs, resolveCliCommand, resolveHomeDir, resolveLinkUrl, resolveStaticAuth, signIn, string, toNameMapping, validateCredentialResponse, validateManifest, withUpstreamAccess };
2274
+ export { AuthError, CREDENTIALS_FORM_API, CREDENTIALS_FORM_SESSION_HEADER, CREDENTIALS_REQUEST_ELEMENT_ID, DEFAULT_UI_TEXTS, FORM_WINDOW_BINDINGS, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, ToolError, UnauthorizedError, applyDomain, array, boolean, buildRequest, compareVersions, createFileSecretStore, defineServer, defineTool, defineUI, describeAuth, describeAuthSpec, describeError, executeTool, fillTemplate, getPath, input, isDomainValue, isInteractiveAuth, isJsonObject, isMissingFileError, isValidCredentialResponse, isValidManifest, listAuthEnvNames, mapResponse, nameUpstreamTool, number, oneOf, optional, prepareToolArgs, resolveCliCommand, resolveHomeDir, resolveLinkUrl, resolveStaticAuth, signIn, string, toNameMapping, validateCredentialResponse, validateManifest, withUpstreamAccess };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usemcpkit/core",
3
- "version": "0.5.0",
3
+ "version": "0.7.0",
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.5.0",
38
+ "@usemcpkit/testing": "0.7.0",
39
39
  "typescript": "^5.9.0",
40
40
  "vite": "^8.0.0",
41
41
  "vite-plugin-dts": "5.1.2",