@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.
@@ -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.9.0",
4
- "description": "Manifest-driven MCP tool execution: manifest validation, HTTP execution, response mapping, auth and the server SDK.",
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/mcpkit.core.d.ts",
14
- "import": "./build/mcpkit.core.js"
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/mcpkit.core.d.ts",
22
- "import": "./build/mcpkit.core.js"
21
+ "types": "./build/usemcpkit.core.d.ts",
22
+ "import": "./build/usemcpkit.core.js"
23
23
  }
24
24
  }
25
25
  },