@usemcpkit/core 0.9.0 → 0.11.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/README.md +17 -11
- package/build/{mcpkit.core.d.ts → usemcpkit.core.d.ts} +20 -156
- package/build/usemcpkit.core.js +322 -0
- package/package.json +6 -6
- package/build/mcpkit.core.js +0 -2341
|
@@ -0,0 +1,322 @@
|
|
|
1
|
+
//#region src/credentials-form/const.ts
|
|
2
|
+
/** HTTP contract between the CLI's loopback credentials form server and the page it serves. */
|
|
3
|
+
var CREDENTIALS_FORM_API = {
|
|
4
|
+
submit: "/api/submit",
|
|
5
|
+
cancel: "/api/cancel",
|
|
6
|
+
import: "/api/import"
|
|
7
|
+
};
|
|
8
|
+
var CREDENTIALS_REQUEST_ELEMENT_ID = "usemcpkit-request";
|
|
9
|
+
/**
|
|
10
|
+
* Functions the CLI's native form window binds into the page: close it, fit it to `{ width, height }`, and open a link
|
|
11
|
+
* in the default browser (a webview has no tabs, so `target="_blank"` links go nowhere).
|
|
12
|
+
*/
|
|
13
|
+
var FORM_WINDOW_BINDINGS = {
|
|
14
|
+
close: "usemcpkitCloseWindow",
|
|
15
|
+
fit: "usemcpkitFitWindow",
|
|
16
|
+
openLink: "usemcpkitOpenLink"
|
|
17
|
+
};
|
|
18
|
+
var CREDENTIALS_FORM_SESSION_HEADER = "X-Usemcpkit-Session";
|
|
19
|
+
var WEB_HOST_API_PREFIX = "api.";
|
|
20
|
+
//#endregion
|
|
21
|
+
//#region src/manifest/auth/describe-auth-type.ts
|
|
22
|
+
var describeAuthType = (auth) => auth.type === "oauth" ? "oauth pkce" : auth.type;
|
|
23
|
+
//#endregion
|
|
24
|
+
//#region src/manifest/auth/list-auth-env-names.ts
|
|
25
|
+
var listAuthEnvNames = (auth) => {
|
|
26
|
+
switch (auth.type) {
|
|
27
|
+
case "none": return [];
|
|
28
|
+
case "basic": return [auth.usernameEnv, auth.passwordEnv];
|
|
29
|
+
case "oauth": return auth.clientSecretEnv ? [auth.clientSecretEnv] : [];
|
|
30
|
+
case "bearer":
|
|
31
|
+
case "header":
|
|
32
|
+
case "query": return [auth.env];
|
|
33
|
+
default: return auth;
|
|
34
|
+
}
|
|
35
|
+
};
|
|
36
|
+
//#endregion
|
|
37
|
+
//#region src/manifest/auth/describe-auth-spec.ts
|
|
38
|
+
var describeAuthSpec = (auth) => {
|
|
39
|
+
if (auth.type === "none") return "no auth";
|
|
40
|
+
return [describeAuthType(auth), listAuthEnvNames(auth).join(", ")].filter(Boolean).join(" ");
|
|
41
|
+
};
|
|
42
|
+
//#endregion
|
|
43
|
+
//#region src/manifest/auth/describe-auth.ts
|
|
44
|
+
var describeAuth = (auth) => {
|
|
45
|
+
if (!auth || auth.length === 0) return "no auth";
|
|
46
|
+
return auth.map(describeAuthSpec).join(" → ");
|
|
47
|
+
};
|
|
48
|
+
//#endregion
|
|
49
|
+
//#region src/manifest/auth/is-interactive-auth.ts
|
|
50
|
+
/** OAuth2 auth signs in through the browser and keeps its token in `tokens.json`. */
|
|
51
|
+
var isInteractiveAuth = (auth) => auth.type === "oauth";
|
|
52
|
+
//#endregion
|
|
53
|
+
//#region src/manifest/const.ts
|
|
54
|
+
var SERVER_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
|
|
55
|
+
/** `resource:action`, for example `pull_request:list`; the action part is optional. */
|
|
56
|
+
var TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*(:[a-z][a-z0-9_]*)*$/;
|
|
57
|
+
var DOMAIN_PLACEHOLDER = "{domain}";
|
|
58
|
+
/** Hosts a `domain.loopbackHttp` server reaches over `http://`. */
|
|
59
|
+
var LOOPBACK_HOSTS = ["localhost", "127.0.0.1"];
|
|
60
|
+
var HTTPS_PREFIX = "https://";
|
|
61
|
+
var HTTP_PREFIX = "http://";
|
|
62
|
+
/** A host with an optional port and path, for example `ghe.example.com/api/v3`. */
|
|
63
|
+
var DOMAIN_VALUE_PATTERN = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d{1,5})?(\/[a-z0-9._~-]+)*$/i;
|
|
64
|
+
//#endregion
|
|
65
|
+
//#region src/manifest/domain/fill-domain.ts
|
|
66
|
+
var fillDomain = (template, domain) => template.replaceAll(DOMAIN_PLACEHOLDER, domain);
|
|
67
|
+
//#endregion
|
|
68
|
+
//#region src/manifest/domain/to-domain-host.ts
|
|
69
|
+
/** The lowercase host of a domain value: what comes before its path and port. */
|
|
70
|
+
var toDomainHost = (domain) => (domain.split("/")[0] ?? "").split(":")[0]?.toLowerCase() ?? "";
|
|
71
|
+
//#endregion
|
|
72
|
+
//#region src/manifest/domain/to-loopback-http-url.ts
|
|
73
|
+
/**
|
|
74
|
+
* `https://localhost:5678/api/v1` → `http://localhost:5678/api/v1` when the URL points at `domain` and that domain is
|
|
75
|
+
* a loopback host; any other URL is returned as is.
|
|
76
|
+
*/
|
|
77
|
+
var toLoopbackHttpUrl = (url, domain) => {
|
|
78
|
+
const host = toDomainHost(domain);
|
|
79
|
+
if (!LOOPBACK_HOSTS.includes(host) || !url.startsWith("https://")) return url;
|
|
80
|
+
const rest = url.slice(HTTPS_PREFIX.length);
|
|
81
|
+
return toDomainHost(rest) === host ? `${HTTP_PREFIX}${rest}` : url;
|
|
82
|
+
};
|
|
83
|
+
//#endregion
|
|
84
|
+
//#region src/manifest/domain/fill-domain-url.ts
|
|
85
|
+
/** A URL template with `{domain}` filled in, over `http://` for a loopback domain when the server allows it (`domain.loopbackHttp`). */
|
|
86
|
+
var fillDomainUrl = (template, domain, loopbackHttp) => {
|
|
87
|
+
const url = fillDomain(template, domain);
|
|
88
|
+
return loopbackHttp ? toLoopbackHttpUrl(url, domain) : url;
|
|
89
|
+
};
|
|
90
|
+
//#endregion
|
|
91
|
+
//#region src/manifest/domain/apply-auth-domain.ts
|
|
92
|
+
var applyAuthDomain = (auth, domain, loopbackHttp) => {
|
|
93
|
+
if (auth.type !== "oauth") return auth;
|
|
94
|
+
return {
|
|
95
|
+
...auth,
|
|
96
|
+
authorizationUrl: fillDomainUrl(auth.authorizationUrl, domain, loopbackHttp),
|
|
97
|
+
tokenUrl: fillDomainUrl(auth.tokenUrl, domain, loopbackHttp)
|
|
98
|
+
};
|
|
99
|
+
};
|
|
100
|
+
//#endregion
|
|
101
|
+
//#region src/manifest/domain/apply-tool-edition.ts
|
|
102
|
+
var applyToolEdition = (tool, editionName) => {
|
|
103
|
+
const edition = editionName === void 0 ? void 0 : tool.editions?.[editionName];
|
|
104
|
+
if (!edition) return tool;
|
|
105
|
+
return {
|
|
106
|
+
...tool,
|
|
107
|
+
request: edition.request,
|
|
108
|
+
response: edition.response ?? tool.response
|
|
109
|
+
};
|
|
110
|
+
};
|
|
111
|
+
//#endregion
|
|
112
|
+
//#region src/manifest/domain/find-edition.ts
|
|
113
|
+
var findEdition = (editions, domain) => {
|
|
114
|
+
const host = toDomainHost(domain);
|
|
115
|
+
return Object.entries(editions ?? {}).find(([, edition]) => edition.hosts.some((suffix) => host.endsWith(suffix.toLowerCase())))?.[0];
|
|
116
|
+
};
|
|
117
|
+
//#endregion
|
|
118
|
+
//#region src/manifest/domain/apply-domain.ts
|
|
119
|
+
/** A copy of the manifest with `{domain}` filled in and each tool set to the domain's edition; without a domain the manifest is returned as is. */
|
|
120
|
+
var applyDomain = (manifest, domain) => {
|
|
121
|
+
if (domain === void 0) return manifest;
|
|
122
|
+
const loopbackHttp = manifest.domain?.loopbackHttp === true;
|
|
123
|
+
const editionName = findEdition(manifest.editions, domain);
|
|
124
|
+
return {
|
|
125
|
+
...manifest,
|
|
126
|
+
baseUrl: fillDomainUrl(manifest.baseUrl, domain, loopbackHttp),
|
|
127
|
+
upstream: manifest.upstream?.type === "http" ? {
|
|
128
|
+
...manifest.upstream,
|
|
129
|
+
url: fillDomainUrl(manifest.upstream.url, domain, loopbackHttp)
|
|
130
|
+
} : manifest.upstream,
|
|
131
|
+
auth: manifest.auth?.map((auth) => applyAuthDomain(auth, domain, loopbackHttp)),
|
|
132
|
+
tools: manifest.tools.map((tool) => applyToolEdition(tool, editionName))
|
|
133
|
+
};
|
|
134
|
+
};
|
|
135
|
+
//#endregion
|
|
136
|
+
//#region src/manifest/domain/is-domain-value.ts
|
|
137
|
+
var isDomainValue = (value) => typeof value === "string" && DOMAIN_VALUE_PATTERN.test(value);
|
|
138
|
+
//#endregion
|
|
139
|
+
//#region src/manifest/is-name-list.ts
|
|
140
|
+
var isNameList = (spec) => Array.isArray(spec);
|
|
141
|
+
//#endregion
|
|
142
|
+
//#region src/manifest/to-name-mapping.ts
|
|
143
|
+
var toNameMapping = (spec) => {
|
|
144
|
+
if (!isNameList(spec)) return spec;
|
|
145
|
+
return Object.fromEntries(spec.map((name) => [name, name]));
|
|
146
|
+
};
|
|
147
|
+
//#endregion
|
|
148
|
+
//#region src/manifest/ui/const.ts
|
|
149
|
+
var DEFAULT_UI_TEXTS = {
|
|
150
|
+
brand: "usemcpkit",
|
|
151
|
+
pageTitle: "usemcpkit · Connect",
|
|
152
|
+
title: "Connect {server}",
|
|
153
|
+
intro: "A tool call needs access to {server}. What you enter is saved in ~/.usemcpkit/config.json and used for later calls.",
|
|
154
|
+
domainLabel: "Domain",
|
|
155
|
+
domainHint: "Host, optionally with a port and path, without https://",
|
|
156
|
+
domainPlaceholder: "api.example.com",
|
|
157
|
+
domainNewHost: "New host, saved with its own credentials.",
|
|
158
|
+
domainShowHosts: "Show saved hosts",
|
|
159
|
+
signInLabel: "Sign in with OAuth2",
|
|
160
|
+
tokenDivider: "or use an access token",
|
|
161
|
+
credentialLegend: "Credential",
|
|
162
|
+
fieldHint: "Or set the {key} environment variable.",
|
|
163
|
+
tokenLabel: "Access token",
|
|
164
|
+
usernameLabel: "Username",
|
|
165
|
+
passwordLabel: "Password",
|
|
166
|
+
headerLabel: "{name} header",
|
|
167
|
+
queryLabel: "{name} query parameter",
|
|
168
|
+
actionsDivider: "or get a token",
|
|
169
|
+
cancel: "Cancel",
|
|
170
|
+
submit: "Save and continue",
|
|
171
|
+
checking: "Checking with {server}…",
|
|
172
|
+
requiredField: "{label} is required",
|
|
173
|
+
savedTitle: "{server} is connected",
|
|
174
|
+
savedBody: "The credentials are saved in ~/.usemcpkit/config.json. This window closes by itself in a few seconds; you can also close it and go back to your MCP client.",
|
|
175
|
+
signingInTitle: "Continue in the new tab",
|
|
176
|
+
signingInBody: "Approve access to {server} in the sign-in tab that just opened. You can close this one.",
|
|
177
|
+
cancelledTitle: "Cancelled",
|
|
178
|
+
cancelledBody: "Nothing was saved. The tool call that asked for credentials fails; calling it again reopens this form.",
|
|
179
|
+
failedTitle: "Something went wrong",
|
|
180
|
+
requestFailed: "the CLI answered {status}"
|
|
181
|
+
};
|
|
182
|
+
var UI_DOMAIN_PLACEHOLDERS = ["domain", "webHost"];
|
|
183
|
+
var UI_PLACEHOLDER_PATTERN = /\{(\w+)\}/g;
|
|
184
|
+
//#endregion
|
|
185
|
+
//#region src/manifest/ui/fill-template.ts
|
|
186
|
+
/** Replaces `{name}` with its value; a placeholder without a value stays as it is. */
|
|
187
|
+
var fillTemplate = (template, values) => template.replace(UI_PLACEHOLDER_PATTERN, (placeholder, name) => values[name] ?? placeholder);
|
|
188
|
+
//#endregion
|
|
189
|
+
//#region src/manifest/ui/read-placeholders.ts
|
|
190
|
+
var readPlaceholders = (template) => Array.from(template.matchAll(UI_PLACEHOLDER_PATTERN), (match) => match[1] ?? "");
|
|
191
|
+
//#endregion
|
|
192
|
+
//#region src/manifest/upstream/name-upstream-tool.ts
|
|
193
|
+
var CATALOG_NAME_PATTERN = /^[a-z][a-z0-9_]*(:[a-z][a-z0-9_]*){2,}$/;
|
|
194
|
+
/**
|
|
195
|
+
* The catalog name `rules` give an upstream tool, from the first rule whose `match` finds the tool name, or undefined
|
|
196
|
+
* when none does. A name that is not `<group>:<resource>:<action>` in lowercase snake case is an error in the
|
|
197
|
+
* manifest, never silently replaced.
|
|
198
|
+
*/
|
|
199
|
+
var nameUpstreamTool = (rules, upstreamName) => {
|
|
200
|
+
for (const rule of rules ?? []) {
|
|
201
|
+
const pattern = new RegExp(rule.match);
|
|
202
|
+
if (!pattern.test(upstreamName)) continue;
|
|
203
|
+
const name = upstreamName.replace(pattern, rule.name);
|
|
204
|
+
if (!CATALOG_NAME_PATTERN.test(name)) throw new Error(`naming rule "${rule.match}" turned "${upstreamName}" into "${name}", which is not <group>:<resource>:<action>`);
|
|
205
|
+
return name;
|
|
206
|
+
}
|
|
207
|
+
};
|
|
208
|
+
//#endregion
|
|
209
|
+
//#region src/credentials-form/to-web-host.ts
|
|
210
|
+
/** `api.github.com` → `github.com`, `api.acme.ghe.com` → `acme.ghe.com`, `ghe.example.com/api/v3` → `ghe.example.com`. */
|
|
211
|
+
var toWebHost = (domain) => {
|
|
212
|
+
const [host = domain, ...path] = domain.split("/");
|
|
213
|
+
if (path.length === 0 && host.startsWith("api.")) return host.slice(WEB_HOST_API_PREFIX.length);
|
|
214
|
+
return host;
|
|
215
|
+
};
|
|
216
|
+
//#endregion
|
|
217
|
+
//#region src/credentials-form/resolve-link-url.ts
|
|
218
|
+
/** Undefined while the link needs a domain and there is none yet; with `loopbackHttp` a link to a loopback domain opens over `http://`. */
|
|
219
|
+
var resolveLinkUrl = (url, domain, loopbackHttp) => {
|
|
220
|
+
if (readPlaceholders(url).some((name) => UI_DOMAIN_PLACEHOLDERS.includes(name)) && !domain) return;
|
|
221
|
+
const filled = fillTemplate(url, {
|
|
222
|
+
domain: domain ?? "",
|
|
223
|
+
webHost: domain ? toWebHost(domain) : ""
|
|
224
|
+
});
|
|
225
|
+
return domain && loopbackHttp ? toLoopbackHttpUrl(filled, domain) : filled;
|
|
226
|
+
};
|
|
227
|
+
//#endregion
|
|
228
|
+
//#region src/errors/describe-error.ts
|
|
229
|
+
var describeError = (error) => error instanceof Error ? error.message : String(error);
|
|
230
|
+
//#endregion
|
|
231
|
+
//#region src/json/is-json-object.ts
|
|
232
|
+
var isJsonObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
233
|
+
//#endregion
|
|
234
|
+
//#region src/sdk/define-server.ts
|
|
235
|
+
var defineServer = (manifest) => manifest;
|
|
236
|
+
//#endregion
|
|
237
|
+
//#region src/sdk/define-tool.ts
|
|
238
|
+
var defineTool = (tool) => tool;
|
|
239
|
+
//#endregion
|
|
240
|
+
//#region src/sdk/define-ui.ts
|
|
241
|
+
var defineUI = (ui) => ui;
|
|
242
|
+
//#endregion
|
|
243
|
+
//#region src/sdk/const.ts
|
|
244
|
+
/** Symbol keys are dropped by JSON.stringify, so the marker never reaches a manifest. */
|
|
245
|
+
var OPTIONAL_MARKER = Symbol("optional");
|
|
246
|
+
//#endregion
|
|
247
|
+
//#region src/sdk/is-required-param.ts
|
|
248
|
+
var isRequiredParam = (param) => !param[OPTIONAL_MARKER] && param.default === void 0;
|
|
249
|
+
//#endregion
|
|
250
|
+
//#region src/sdk/strip-optional-marker.ts
|
|
251
|
+
var stripOptionalMarker = (param) => {
|
|
252
|
+
const { [OPTIONAL_MARKER]: _marker, ...rest } = param;
|
|
253
|
+
return rest;
|
|
254
|
+
};
|
|
255
|
+
//#endregion
|
|
256
|
+
//#region src/sdk/input.ts
|
|
257
|
+
/** Builds an object input schema; `required` is derived from the params. */
|
|
258
|
+
var input = (params = {}) => {
|
|
259
|
+
const entries = Object.entries(params);
|
|
260
|
+
const required = entries.filter(([, param]) => isRequiredParam(param)).map(([name]) => name);
|
|
261
|
+
return {
|
|
262
|
+
type: "object",
|
|
263
|
+
properties: Object.fromEntries(entries.map(([name, param]) => [name, stripOptionalMarker(param)])),
|
|
264
|
+
...required.length > 0 ? { required } : {}
|
|
265
|
+
};
|
|
266
|
+
};
|
|
267
|
+
//#endregion
|
|
268
|
+
//#region src/sdk/optional.ts
|
|
269
|
+
/** Marks a param as not required. Params with a default are optional implicitly. */
|
|
270
|
+
var optional = (param) => {
|
|
271
|
+
return {
|
|
272
|
+
...param,
|
|
273
|
+
[OPTIONAL_MARKER]: true
|
|
274
|
+
};
|
|
275
|
+
};
|
|
276
|
+
//#endregion
|
|
277
|
+
//#region src/sdk/with-description.ts
|
|
278
|
+
var withDescription = (description) => description ? { description } : {};
|
|
279
|
+
//#endregion
|
|
280
|
+
//#region src/sdk/params/array.ts
|
|
281
|
+
var array = (items, description) => {
|
|
282
|
+
return {
|
|
283
|
+
type: "array",
|
|
284
|
+
items,
|
|
285
|
+
...withDescription(description)
|
|
286
|
+
};
|
|
287
|
+
};
|
|
288
|
+
//#endregion
|
|
289
|
+
//#region src/sdk/params/boolean.ts
|
|
290
|
+
var boolean = (description, options = {}) => {
|
|
291
|
+
return {
|
|
292
|
+
type: "boolean",
|
|
293
|
+
...withDescription(description),
|
|
294
|
+
...options
|
|
295
|
+
};
|
|
296
|
+
};
|
|
297
|
+
//#endregion
|
|
298
|
+
//#region src/sdk/params/number.ts
|
|
299
|
+
var number = (description, options = {}) => {
|
|
300
|
+
return {
|
|
301
|
+
type: "number",
|
|
302
|
+
...withDescription(description),
|
|
303
|
+
...options
|
|
304
|
+
};
|
|
305
|
+
};
|
|
306
|
+
//#endregion
|
|
307
|
+
//#region src/sdk/params/string.ts
|
|
308
|
+
var string = (description, options = {}) => {
|
|
309
|
+
return {
|
|
310
|
+
type: "string",
|
|
311
|
+
...withDescription(description),
|
|
312
|
+
...options
|
|
313
|
+
};
|
|
314
|
+
};
|
|
315
|
+
//#endregion
|
|
316
|
+
//#region src/sdk/params/one-of.ts
|
|
317
|
+
var oneOf = (values, description, options = {}) => string(description, {
|
|
318
|
+
enum: values,
|
|
319
|
+
...options
|
|
320
|
+
});
|
|
321
|
+
//#endregion
|
|
322
|
+
export { CREDENTIALS_FORM_API, CREDENTIALS_FORM_SESSION_HEADER, CREDENTIALS_REQUEST_ELEMENT_ID, DEFAULT_UI_TEXTS, FORM_WINDOW_BINDINGS, SERVER_NAME_PATTERN, TOOL_NAME_PATTERN, applyDomain, array, boolean, defineServer, defineTool, defineUI, describeAuth, describeAuthSpec, describeError, fillTemplate, input, isDomainValue, isInteractiveAuth, isJsonObject, listAuthEnvNames, nameUpstreamTool, number, oneOf, optional, resolveLinkUrl, string, toNameMapping };
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@usemcpkit/core",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.11.0",
|
|
4
|
+
"description": "The usemcpkit manifest format: types, the server SDK and the credentials form contract.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "git+https://github.com/MDReal32/mcpkit.git",
|
|
@@ -10,16 +10,16 @@
|
|
|
10
10
|
"type": "module",
|
|
11
11
|
"exports": {
|
|
12
12
|
".": {
|
|
13
|
-
"types": "./build/
|
|
14
|
-
"import": "./build/
|
|
13
|
+
"types": "./build/usemcpkit.core.d.ts",
|
|
14
|
+
"import": "./build/usemcpkit.core.js"
|
|
15
15
|
}
|
|
16
16
|
},
|
|
17
17
|
"publishConfig": {
|
|
18
18
|
"access": "public",
|
|
19
19
|
"exports": {
|
|
20
20
|
".": {
|
|
21
|
-
"types": "./build/
|
|
22
|
-
"import": "./build/
|
|
21
|
+
"types": "./build/usemcpkit.core.d.ts",
|
|
22
|
+
"import": "./build/usemcpkit.core.js"
|
|
23
23
|
}
|
|
24
24
|
}
|
|
25
25
|
},
|