@usemcpkit/core 0.5.0 → 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.
- package/build/mcpkit.core.d.ts +49 -0
- package/build/mcpkit.core.js +84 -12
- package/package.json +2 -2
package/build/mcpkit.core.d.ts
CHANGED
|
@@ -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. */
|
package/build/mcpkit.core.js
CHANGED
|
@@ -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
|
|
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
|
|
414
|
-
|
|
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.
|
|
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.
|
|
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",
|