@usemcpkit/core 0.13.5 → 0.14.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.
@@ -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; the manifest's `auth` signs the requests. */
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. An `upstream` manifest never requests it, so it only names the service's https home. */
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, so `tools` stays empty. */
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}` and
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 { }
@@ -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",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usemcpkit/core",
3
- "version": "0.13.5",
3
+ "version": "0.14.0",
4
4
  "description": "The usemcpkit manifest format: types, the server SDK and the credentials form contract.",
5
5
  "repository": {
6
6
  "type": "git",