@usemcpkit/core 0.4.1 → 0.6.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,14 @@ 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
443
  /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables. */
417
444
  forwardEnv?: readonly string[];
445
+ /** When set, the program is run from this repository, cloned and set up on first use. */
446
+ repo?: UpstreamRepo;
447
+ /** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
448
+ naming?: readonly UpstreamNameRule[];
418
449
  }
419
450
 
420
451
  declare interface StoredToken {
@@ -536,6 +567,7 @@ export declare interface UiTexts {
536
567
  actionsDivider: string;
537
568
  cancel: string;
538
569
  submit: string;
570
+ checking: string;
539
571
  requiredField: string;
540
572
  savedTitle: string;
541
573
  savedBody: string;
@@ -558,6 +590,23 @@ export declare interface UpstreamAccess {
558
590
  env: Readonly<Record<string, string>>;
559
591
  }
560
592
 
593
+ /** Renames the tools of an upstream server into mcpkit's `<group>:<resource>:<action>` form. */
594
+ export declare interface UpstreamNameRule {
595
+ /** A regular expression tested against the upstream tool name; the first rule that matches names the tool. */
596
+ match: string;
597
+ /** The new name, with `$1`… for captures and `$&` for the whole upstream name: `org:members:$&`. */
598
+ name: string;
599
+ }
600
+
601
+ /** A git repository the upstream server is run from, cloned on first use into `~/.mcpkit/repos/<category>/<name>`. */
602
+ export declare interface UpstreamRepo {
603
+ url: string;
604
+ /** Tag or commit to check out; pin a commit, since the checkout is run as code. */
605
+ ref: string;
606
+ /** Run in order in the clone once, after checkout, with no credentials in the environment. */
607
+ setup?: readonly RepoSetupStep[];
608
+ }
609
+
561
610
  export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
562
611
 
563
612
  /** 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,69 @@ 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 tag or commit, 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.repo !== void 0) errors.push(...validateUpstreamRepo(upstream.repo));
421
477
  return errors;
422
478
  };
479
+ var validateUpstream = (upstream) => {
480
+ if (!isJsonObject(upstream)) return ["upstream must be an object"];
481
+ if (upstream.type !== "http" && upstream.type !== "stdio") return ["upstream.type must be \"http\" or \"stdio\""];
482
+ return [...upstream.type === "http" ? validateHttp(upstream) : validateStdio(upstream), ...upstream.naming === void 0 ? [] : validateUpstreamNaming(upstream.naming)];
483
+ };
423
484
  //#endregion
424
485
  //#region src/manifest/validation/find-duplicates.ts
425
486
  var findDuplicates = (values) => [...new Set(values.filter((value, index) => values.indexOf(value) !== index))];
@@ -663,12 +724,6 @@ var mergeLegacySecrets = (config, legacy) => {
663
724
  };
664
725
  };
665
726
  //#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
727
  //#region src/auth/token-store/read-tokens-text.ts
673
728
  var readTokensText = async (file) => {
674
729
  try {
@@ -2040,6 +2095,23 @@ var executeTool = async (manifest, tool, rawArgs, { fetchImpl = fetch, timeoutMs
2040
2095
  return mapResponse(body, sentTool.response);
2041
2096
  };
2042
2097
  //#endregion
2098
+ //#region src/execution/upstream/name-upstream-tool.ts
2099
+ var CATALOG_NAME_PATTERN = /^[a-z][a-z0-9_]*(:[a-z][a-z0-9_]*){2,}$/;
2100
+ /**
2101
+ * The catalog name `rules` give an upstream tool, from the first rule whose `match` finds the tool name, or undefined
2102
+ * when none does. A name that is not `<group>:<resource>:<action>` in lowercase snake case is an error in the
2103
+ * manifest, never silently replaced.
2104
+ */
2105
+ var nameUpstreamTool = (rules, upstreamName) => {
2106
+ for (const rule of rules ?? []) {
2107
+ const pattern = new RegExp(rule.match);
2108
+ if (!pattern.test(upstreamName)) continue;
2109
+ const name = upstreamName.replace(pattern, rule.name);
2110
+ if (!CATALOG_NAME_PATTERN.test(name)) throw new Error(`naming rule "${rule.match}" turned "${upstreamName}" into "${name}", which is not <group>:<resource>:<action>`);
2111
+ return name;
2112
+ }
2113
+ };
2114
+ //#endregion
2043
2115
  //#region src/execution/upstream/read-forwarded-env.ts
2044
2116
  /** Each forwarded credential from its env var, else from the secret store. */
2045
2117
  var readForwardedEnv = async (manifest, { forwardEnv = [] }, domain, context) => {
@@ -2196,4 +2268,4 @@ var compareVersions = (left, right) => {
2196
2268
  return 0;
2197
2269
  };
2198
2270
  //#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 };
2271
+ 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.4.1",
3
+ "version": "0.6.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.4.1",
38
+ "@usemcpkit/testing": "0.6.0",
39
39
  "typescript": "^5.9.0",
40
40
  "vite": "^8.0.0",
41
41
  "vite-plugin-dts": "5.1.2",