@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.
- package/build/mcpkit.core.d.ts +55 -1
- package/build/mcpkit.core.js +92 -17
- 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,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. */
|
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,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
|
|
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.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
|
|
2052
|
-
const
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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",
|