@usemcpkit/core 0.13.5 → 0.15.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 +1 -1
- package/build/usemcpkit.core.d.ts +161 -5
- package/build/usemcpkit.core.js +7 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ Public surface: `src/main.ts` (built to `build/usemcpkit.core.js` with bundled t
|
|
|
13
13
|
```jsonc
|
|
14
14
|
{
|
|
15
15
|
"name": "github", // [a-z][a-z0-9_]*
|
|
16
|
-
"category": "git", // [a-z][a-z0-9-]*, groups servers of one kind
|
|
16
|
+
"category": "git", // [a-z][a-z0-9-]*, groups servers of one kind; orgs/<org> for the servers one organization offers several of
|
|
17
17
|
"version": "1.0.0",
|
|
18
18
|
"baseUrl": "https://{domain}", // https only; {domain} is optional, see Domain
|
|
19
19
|
"domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" },
|
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a hand-written tool or an auth entry of an OpenAPI manifest applies: a tool replaces the built tool of the same
|
|
3
|
+
* name there, and the credentials form offers an auth entry only there.
|
|
4
|
+
*/
|
|
5
|
+
export declare interface Applies {
|
|
6
|
+
/** Names of the OpenAPI sources; every source when absent. */
|
|
7
|
+
sources?: readonly string[];
|
|
8
|
+
/**
|
|
9
|
+
* The versions, as a condition on `{version}`: `9.0 <= {version} < 10`, or `{version} >= 9.0 && {version} < 10`
|
|
10
|
+
* (operators `<`, `<=`, `>`, `>=`, `==`, `!=`); every version when absent.
|
|
11
|
+
*/
|
|
12
|
+
if?: string;
|
|
13
|
+
}
|
|
14
|
+
|
|
1
15
|
/** 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. */
|
|
2
16
|
export declare const applyDomain: (manifest: Manifest, domain: string | undefined) => Manifest;
|
|
3
17
|
|
|
@@ -16,6 +30,8 @@ declare interface BasicAuth {
|
|
|
16
30
|
label?: string;
|
|
17
31
|
/** Texts, field labels and buttons of the credentials page for this entry. */
|
|
18
32
|
ui?: UiSpec;
|
|
33
|
+
/** In an OpenAPI manifest, the sources and versions the credentials form offers this entry for. */
|
|
34
|
+
applies?: Applies;
|
|
19
35
|
}
|
|
20
36
|
|
|
21
37
|
declare interface BearerAuth {
|
|
@@ -25,10 +41,40 @@ declare interface BearerAuth {
|
|
|
25
41
|
label?: string;
|
|
26
42
|
/** Texts, field labels and buttons of the credentials page for this entry. */
|
|
27
43
|
ui?: UiSpec;
|
|
44
|
+
/** In an OpenAPI manifest, the sources and versions the credentials form offers this entry for. */
|
|
45
|
+
applies?: Applies;
|
|
28
46
|
}
|
|
29
47
|
|
|
30
48
|
export declare const boolean: (description?: string, options?: ParamOptions) => Param;
|
|
31
49
|
|
|
50
|
+
/** How endpoints become tools; every field falls back to its default when absent. */
|
|
51
|
+
export declare interface ConversionOptions {
|
|
52
|
+
/** Object properties below this depth are dropped (3 by default). */
|
|
53
|
+
maxDepth?: number;
|
|
54
|
+
/** Puts the primitive `default` of a schema into the input (on by default). */
|
|
55
|
+
includeDefaults?: boolean;
|
|
56
|
+
/** Removes `**` from descriptions. */
|
|
57
|
+
stripBold?: boolean;
|
|
58
|
+
/** A oneOf/anyOf of mixed scalar types becomes `string` when one of them is a string. */
|
|
59
|
+
widenMixedScalars?: boolean;
|
|
60
|
+
/** An exploded query array of scalars stays an array argument; otherwise it is a comma-separated string. */
|
|
61
|
+
keepsExplodedArrays?: boolean;
|
|
62
|
+
/** Put before every tool description, for example `[Data Center]`. */
|
|
63
|
+
descriptionPrefix?: string;
|
|
64
|
+
/** Regexes over the path of GET endpoints whose answer is a file to save rather than read. */
|
|
65
|
+
downloadPaths?: readonly string[];
|
|
66
|
+
/** The form part a multipart body that is a bare file list is sent as. */
|
|
67
|
+
filePartName?: string;
|
|
68
|
+
/** Regexes over `"METHOD /path"` of endpoints left out. */
|
|
69
|
+
skip?: readonly string[];
|
|
70
|
+
/** Leaves out deprecated endpoints. */
|
|
71
|
+
skipDeprecated?: boolean;
|
|
72
|
+
/** Security schemes the manifest's auth satisfies; an endpoint whose `security` names only other schemes is left out. */
|
|
73
|
+
security?: readonly string[];
|
|
74
|
+
/** Query values sent on every call. */
|
|
75
|
+
fixedQuery?: Readonly<Record<string, FixedValue>>;
|
|
76
|
+
}
|
|
77
|
+
|
|
32
78
|
export declare interface CredentialField {
|
|
33
79
|
/** The env var that provides this value without the form. */
|
|
34
80
|
key: string;
|
|
@@ -46,6 +92,8 @@ export declare interface CredentialOption {
|
|
|
46
92
|
fields: readonly CredentialField[];
|
|
47
93
|
/** The buttons under the fields: links to create a token, or a CLI to take one from. */
|
|
48
94
|
actions: readonly UiAction[];
|
|
95
|
+
/** The sources and versions this option is offered for; every one when absent. */
|
|
96
|
+
applies?: Applies;
|
|
49
97
|
}
|
|
50
98
|
|
|
51
99
|
/** Everything the credentials page shows, so the page itself holds no text. */
|
|
@@ -70,6 +118,7 @@ export declare const CREDENTIALS_FORM_API: {
|
|
|
70
118
|
readonly submit: "/api/submit";
|
|
71
119
|
readonly cancel: "/api/cancel";
|
|
72
120
|
readonly import: "/api/import";
|
|
121
|
+
readonly check: "/api/check";
|
|
73
122
|
};
|
|
74
123
|
|
|
75
124
|
export declare const CREDENTIALS_FORM_SESSION_HEADER = "X-Usemcpkit-Session";
|
|
@@ -100,6 +149,20 @@ export declare interface DomainField {
|
|
|
100
149
|
knownHosts: readonly string[];
|
|
101
150
|
/** Hosts the server suggests (`domain.suggestedHosts`), offered after the known ones; none is picked for the user. */
|
|
102
151
|
suggestedHosts?: readonly string[];
|
|
152
|
+
/** Whether a Check button after the field asks the server its version (`domain.check`). */
|
|
153
|
+
check?: boolean;
|
|
154
|
+
/** The manifest's OpenAPI sources, in order: the first whose hosts match the typed host is the one in use. */
|
|
155
|
+
sources?: readonly DomainSource[];
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/** One OpenAPI source of the server, so the page can tell which one a typed host belongs to. */
|
|
159
|
+
export declare interface DomainSource {
|
|
160
|
+
name: string;
|
|
161
|
+
label: string;
|
|
162
|
+
/** Host suffixes; absent, the source matches any host. */
|
|
163
|
+
hosts?: readonly string[];
|
|
164
|
+
/** Whether the server can be asked its version, which the Check button does. */
|
|
165
|
+
versioned: boolean;
|
|
103
166
|
}
|
|
104
167
|
|
|
105
168
|
/** Lets one server talk to any host of the same API, for example a self-hosted GitHub Enterprise. */
|
|
@@ -118,6 +181,11 @@ export declare interface DomainSpec {
|
|
|
118
181
|
suggestedHosts?: readonly string[];
|
|
119
182
|
/** Reaches a `localhost` or `127.0.0.1` domain over `http://`, for servers that usually run locally without TLS. */
|
|
120
183
|
loopbackHttp?: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* Puts a Check button after the host field of the credentials form, which asks the server its version when the
|
|
186
|
+
* OpenAPI source matching the host has a version probe.
|
|
187
|
+
*/
|
|
188
|
+
check?: boolean;
|
|
121
189
|
}
|
|
122
190
|
|
|
123
191
|
/** A deployment of the same API that needs other requests, for example Atlassian Cloud next to Data Center. */
|
|
@@ -167,17 +235,35 @@ declare interface HeaderAuth {
|
|
|
167
235
|
prefix?: string;
|
|
168
236
|
/** Texts, field labels and buttons of the credentials page for this entry. */
|
|
169
237
|
ui?: UiSpec;
|
|
238
|
+
/** In an OpenAPI manifest, the sources and versions the credentials form offers this entry for. */
|
|
239
|
+
applies?: Applies;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** What the Check button posts: the typed host, and the picked option with what is typed into it so far. */
|
|
243
|
+
export declare interface HostCheckRequest {
|
|
244
|
+
domain: string;
|
|
245
|
+
option?: number;
|
|
246
|
+
values?: Readonly<Record<string, string>>;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** The source a checked host belongs to and the version its server runs (absent for a source without versions). */
|
|
250
|
+
export declare interface HostCheckResult {
|
|
251
|
+
source: string;
|
|
252
|
+
label: string;
|
|
253
|
+
version?: string;
|
|
170
254
|
}
|
|
171
255
|
|
|
172
256
|
declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
|
|
173
257
|
|
|
174
258
|
export declare type HttpMethod = (typeof HTTP_METHODS)[number];
|
|
175
259
|
|
|
176
|
-
/** An MCP server reached over Streamable HTTP;
|
|
260
|
+
/** An MCP server reached over Streamable HTTP; its own `auth` signs the requests, the manifest's when it has none. */
|
|
177
261
|
export declare interface HttpUpstream {
|
|
178
262
|
type: "http";
|
|
179
263
|
/** May contain `{domain}`. */
|
|
180
264
|
url: string;
|
|
265
|
+
/** Tried like the manifest's `auth`; set when the manifest has tools of its own that sign in differently. */
|
|
266
|
+
auth?: readonly AuthSpec[];
|
|
181
267
|
/** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
|
|
182
268
|
naming?: readonly UpstreamNameRule[];
|
|
183
269
|
}
|
|
@@ -216,7 +302,7 @@ export declare interface Manifest {
|
|
|
216
302
|
category: string;
|
|
217
303
|
version: string;
|
|
218
304
|
description?: string;
|
|
219
|
-
/** May contain `{domain}`, as may the oauth URLs (`discovery` included) and an HTTP upstream's `url`; `domain` then says where the value comes from.
|
|
305
|
+
/** May contain `{domain}`, as may the oauth URLs (`discovery` included) and an HTTP upstream's `url`; `domain` then says where the value comes from. A manifest with an `upstream` and no tools never requests it, so it only names the service's https home. */
|
|
220
306
|
baseUrl: string;
|
|
221
307
|
domain?: DomainSpec;
|
|
222
308
|
/** Deployments picked by the domain's host; a domain matching none uses the tools' own requests. */
|
|
@@ -226,8 +312,10 @@ export declare interface Manifest {
|
|
|
226
312
|
auth?: readonly AuthSpec[];
|
|
227
313
|
/** Page-wide texts of the credentials page, replacing usemcpkit's defaults. */
|
|
228
314
|
ui?: UiSpec;
|
|
229
|
-
/** Another MCP server this one fronts: its tools are discovered at runtime
|
|
315
|
+
/** Another MCP server this one fronts: its tools are discovered at runtime and listed beside `tools`, which may be empty. An HTTP upstream may have its own `auth`. */
|
|
230
316
|
upstream?: UpstreamSpec;
|
|
317
|
+
/** Tools built on the user's machine from the OpenAPI document of the server's version; the hand-written `tools` replace built ones of the same name where their `applies` says. */
|
|
318
|
+
openapi?: OpenApiSpec;
|
|
231
319
|
tools: readonly ToolSpec[];
|
|
232
320
|
}
|
|
233
321
|
|
|
@@ -285,6 +373,36 @@ declare interface OAuthSignInOptions {
|
|
|
285
373
|
|
|
286
374
|
export declare const oneOf: (values: readonly string[], description?: string, options?: ParamOptions) => Param;
|
|
287
375
|
|
|
376
|
+
export declare interface OpenApiSource {
|
|
377
|
+
/** Names the source in `applies`, for example `datacenter`. */
|
|
378
|
+
name: string;
|
|
379
|
+
/** What the credentials form calls the deployment, for example `Data Center`; the name when absent. */
|
|
380
|
+
label?: string;
|
|
381
|
+
/** Host suffixes such as `.atlassian.net`; absent, the source serves the hosts no source names. */
|
|
382
|
+
hosts?: readonly string[];
|
|
383
|
+
/** The document, absolute or relative to the registry folder; `{version}` is replaced by the version picked. */
|
|
384
|
+
url: string;
|
|
385
|
+
/** Hex SHA-256 of the document a url without `{version}` must serve. */
|
|
386
|
+
sha256?: string;
|
|
387
|
+
version?: SpecVersioning;
|
|
388
|
+
/** Put before every path of the document; the path of the document's first server (or Swagger `basePath`) when absent. */
|
|
389
|
+
basePath?: string;
|
|
390
|
+
options?: ConversionOptions;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/**
|
|
394
|
+
* Tools built on the user's machine from OpenAPI (or Swagger 2.0) documents, for the version the user's server runs.
|
|
395
|
+
* A tool is named after its endpoint, `<path>:<method>` (`repos/{owner}/{repo}/branches:get`); a hand-written tool of
|
|
396
|
+
* the same name replaces it.
|
|
397
|
+
*/
|
|
398
|
+
export declare interface OpenApiSpec {
|
|
399
|
+
/**
|
|
400
|
+
* The documents of each deployment: every source whose `hosts` match the domain is used, their tools merged in order;
|
|
401
|
+
* when none does, every source without `hosts`.
|
|
402
|
+
*/
|
|
403
|
+
sources: readonly OpenApiSource[];
|
|
404
|
+
}
|
|
405
|
+
|
|
288
406
|
/** Marks a param as not required. Params with a default are optional implicitly. */
|
|
289
407
|
export declare const optional: (param: Param) => Param;
|
|
290
408
|
|
|
@@ -307,6 +425,8 @@ declare interface QueryAuth {
|
|
|
307
425
|
label?: string;
|
|
308
426
|
/** Texts, field labels and buttons of the credentials page for this entry. */
|
|
309
427
|
ui?: UiSpec;
|
|
428
|
+
/** In an OpenAPI manifest, the sources and versions the credentials form offers this entry for. */
|
|
429
|
+
applies?: Applies;
|
|
310
430
|
}
|
|
311
431
|
|
|
312
432
|
/** One program run inside the clone after checkout, such as an install or a build; no shell. */
|
|
@@ -358,6 +478,17 @@ export declare interface SignInCredentialResponse {
|
|
|
358
478
|
domain?: string;
|
|
359
479
|
}
|
|
360
480
|
|
|
481
|
+
/** How the version of the user's server is found and which published document belongs to it. */
|
|
482
|
+
export declare interface SpecVersioning {
|
|
483
|
+
probe: VersionProbe;
|
|
484
|
+
/** Env var that pins the version instead of asking the server. */
|
|
485
|
+
env?: string;
|
|
486
|
+
/** Where the published versions are listed; without it (or `known`) only the exact version is tried. */
|
|
487
|
+
list?: VersionList;
|
|
488
|
+
/** Published versions by version, each with the text `{version}` is replaced by, for vendors without a listing. */
|
|
489
|
+
known?: Readonly<Record<string, string>>;
|
|
490
|
+
}
|
|
491
|
+
|
|
361
492
|
/** An MCP server started as a child process and spoken to over its stdio. */
|
|
362
493
|
export declare interface StdioUpstream {
|
|
363
494
|
type: "stdio";
|
|
@@ -417,6 +548,8 @@ export declare interface ToolSpec {
|
|
|
417
548
|
response?: ResponseSpec;
|
|
418
549
|
/** Per-edition overrides, keyed by the manifest's `editions`. */
|
|
419
550
|
editions?: Readonly<Record<string, ToolEdition>>;
|
|
551
|
+
/** In an OpenAPI manifest, the sources and versions this hand-written tool applies to. */
|
|
552
|
+
applies?: Applies;
|
|
420
553
|
}
|
|
421
554
|
|
|
422
555
|
export declare type UiAction = UiLinkAction | UiCliAction;
|
|
@@ -459,8 +592,8 @@ export declare interface UiSpec {
|
|
|
459
592
|
}
|
|
460
593
|
|
|
461
594
|
/**
|
|
462
|
-
* Every string the credentials page shows. `{server}` is filled in by usemcpkit; `{key}`, `{name}`, `{label}
|
|
463
|
-
* `{status}` are filled in where the text is used.
|
|
595
|
+
* Every string the credentials page shows. `{server}` is filled in by usemcpkit; `{key}`, `{name}`, `{label}`,
|
|
596
|
+
* `{status}`, `{source}` and `{version}` are filled in where the text is used.
|
|
464
597
|
*/
|
|
465
598
|
export declare interface UiTexts {
|
|
466
599
|
brand: string;
|
|
@@ -472,6 +605,9 @@ export declare interface UiTexts {
|
|
|
472
605
|
domainPlaceholder: string;
|
|
473
606
|
domainNewHost: string;
|
|
474
607
|
domainShowHosts: string;
|
|
608
|
+
domainCheck: string;
|
|
609
|
+
domainChecking: string;
|
|
610
|
+
domainChecked: string;
|
|
475
611
|
signInLabel: string;
|
|
476
612
|
tokenDivider: string;
|
|
477
613
|
credentialLegend: string;
|
|
@@ -518,4 +654,24 @@ export declare interface UpstreamRepo {
|
|
|
518
654
|
|
|
519
655
|
export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
|
|
520
656
|
|
|
657
|
+
/** A JSON listing of the published versions, for example GitHub's folder listing or jsDelivr's npm versions. */
|
|
658
|
+
export declare interface VersionList {
|
|
659
|
+
url: string;
|
|
660
|
+
/** Dotted path to the array (or object, whose keys are read) in the answer; the answer itself when absent. */
|
|
661
|
+
items?: string;
|
|
662
|
+
/** Field of each item when the items are objects, for example `name`. */
|
|
663
|
+
field?: string;
|
|
664
|
+
/** Regex whose first capture is the version, for example `^ghes-(\d+\.\d+)$`; items it does not match are skipped. */
|
|
665
|
+
match: string;
|
|
666
|
+
}
|
|
667
|
+
|
|
668
|
+
/** A GET to `path` of the server, with the user's credentials, whose JSON `field` holds the version. */
|
|
669
|
+
export declare interface VersionProbe {
|
|
670
|
+
path: string;
|
|
671
|
+
/** Dotted path into the JSON answer, for example `installed_version`. */
|
|
672
|
+
field: string;
|
|
673
|
+
/** Regex whose first capture is the version, for example `^(\d+\.\d+)` for `3.14.2`. */
|
|
674
|
+
match: string;
|
|
675
|
+
}
|
|
676
|
+
|
|
521
677
|
export { }
|
package/build/usemcpkit.core.js
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
var CREDENTIALS_FORM_API = {
|
|
4
4
|
submit: "/api/submit",
|
|
5
5
|
cancel: "/api/cancel",
|
|
6
|
-
import: "/api/import"
|
|
6
|
+
import: "/api/import",
|
|
7
|
+
check: "/api/check"
|
|
7
8
|
};
|
|
8
9
|
var CREDENTIALS_REQUEST_ELEMENT_ID = "usemcpkit-request";
|
|
9
10
|
/**
|
|
@@ -136,7 +137,8 @@ var applyDomain = (manifest, domain) => {
|
|
|
136
137
|
baseUrl: fillDomainUrl(manifest.baseUrl, domain, loopbackHttp),
|
|
137
138
|
upstream: manifest.upstream?.type === "http" ? {
|
|
138
139
|
...manifest.upstream,
|
|
139
|
-
url: fillDomainUrl(manifest.upstream.url, domain, loopbackHttp)
|
|
140
|
+
url: fillDomainUrl(manifest.upstream.url, domain, loopbackHttp),
|
|
141
|
+
...manifest.upstream.auth && { auth: manifest.upstream.auth.map((auth) => applyAuthDomain(auth, domain, loopbackHttp)) }
|
|
140
142
|
} : manifest.upstream,
|
|
141
143
|
auth: manifest.auth?.map((auth) => applyAuthDomain(auth, domain, loopbackHttp)),
|
|
142
144
|
tools: manifest.tools.map((tool) => applyToolEdition(tool, editionName))
|
|
@@ -166,6 +168,9 @@ var DEFAULT_UI_TEXTS = {
|
|
|
166
168
|
domainPlaceholder: "api.example.com",
|
|
167
169
|
domainNewHost: "New host, saved with its own credentials.",
|
|
168
170
|
domainShowHosts: "Show saved hosts",
|
|
171
|
+
domainCheck: "Check",
|
|
172
|
+
domainChecking: "Checking…",
|
|
173
|
+
domainChecked: "{source} {version}",
|
|
169
174
|
signInLabel: "Sign in with OAuth2",
|
|
170
175
|
tokenDivider: "or use an access token",
|
|
171
176
|
credentialLegend: "Credential",
|