@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 CHANGED
@@ -1,10 +1,12 @@
1
1
  # @usemcpkit/core
2
2
 
3
- Library behind mcpkit: the manifest format and its validation, the server SDK (`defineServer`, `defineTool`,
4
- `defineUI`), the HTTP executor with response mapping, and auth (fallbacks, OAuth 2.0 PKCE, the credentials form
5
- contract). Published to npm. It contains no per-provider code: a server differs from another only in its manifest.
3
+ The authoring side of usemcpkit: the manifest format, the server SDK (`defineServer`,
4
+ `defineTool`, `defineUI`), the upstream naming rules (`nameUpstreamTool`) and the credentials form contract the
5
+ page uses (`CREDENTIALS_FORM_API`, the `Credential*` types). Published to npm. It runs nothing: the `usemcpkit`
6
+ binaries (Rust, `apps/runner` and `apps/server`) execute the manifests, sign in and keep the credentials, as
7
+ described below. It contains no per-provider code: a server differs from another only in its manifest.
6
8
 
7
- Public surface: `src/main.ts` (built to `build/mcpkit.core.js` with bundled types in `build/mcpkit.core.d.ts`).
9
+ Public surface: `src/main.ts` (built to `build/usemcpkit.core.js` with bundled types in `build/usemcpkit.core.d.ts`).
8
10
 
9
11
  ## Manifest format
10
12
 
@@ -98,19 +100,19 @@ saying why. `none` can only be the last entry. Leaving out `auth` means no auth.
98
100
  `ui`, see below).
99
101
  Env vars always win, so CI keeps working without a browser.
100
102
 
101
- **Credentials form.** `mcpkit serve` starts a one-off server on `127.0.0.1` (a free port), prints its URL to
103
+ **Credentials form.** `usemcpkit serve` starts a one-off server on `127.0.0.1` (a free port), prints its URL to
102
104
  stderr and opens the browser. Only the page that was opened can answer: the URL carries a session token in its
103
105
  `#fragment` and the server checks it and the `Host` header. Concurrent calls share one form; it closes after
104
106
  an answer, on Cancel, or after 5 minutes. Secrets are saved **only after the API accepts them**, so a typo is never
105
107
  stored.
106
108
 
107
- **Config file.** The hosts and the saved credentials live together in `~/.mcpkit/config.json`, by category, server and host
109
+ **Config file.** The hosts and the saved credentials live together in `~/.usemcpkit/config.json`, by category, server and host
108
110
  (`{ "servers": { "git": { "gitlab": { "hosts": { "git.acme.com": { "secrets": { "GITLAB_TOKEN": "glpat-…" } } }, "projects": { "/work/app": "git.acme.com" } } } } }`),
109
111
  which you can edit by hand. Credentials never cross hosts. With several hosts for one server, the host of a call is, in order:
110
112
  its env var; the host its project (git root) was bound to the first time you answered the form; the saved host the
111
113
  project's `origin` remote points at (servers whose manifest sets `domain.matchGitRemote`, such as GitHub and GitLab);
112
114
  otherwise the form asks, and the answer is remembered for that project. Credentials are plain text, with file mode `0600` in a `0700` directory, the way `gh` and `glab` keep
113
- their tokens. The file carries a `version` (now 2); a file without one is version 1 and, like an older `secrets.json`, is upgraded on first use by the migration list in `auth/config/config-migrations.ts` (a new version is one appended entry), and a file from a newer mcpkit is refused rather than overwritten. There is no password and nothing to unlock. Any program running as your user can read the file, so
115
+ their tokens. The file carries a `version` (now 2); a file without one is version 1 and, like an older `secrets.json`, is upgraded on first use by the migration list in `crates/auth/src/config/config_migrations.rs` (a new version is one appended entry), and a file from a newer usemcpkit is refused rather than overwritten. There is no password and nothing to unlock. Any program running as your user can read the file, so
114
116
  protect your account and disk; to forget a credential, delete its entry or the file. Environment variables always win
115
117
  over the file.
116
118
 
@@ -130,7 +132,7 @@ defineServer({
130
132
  ui: defineUI({
131
133
  inputs: { GITHUB_TOKEN: { label: 'Token', hint: '…', placeholder: 'ghp_…' } },
132
134
  actions: [
133
- { type: 'link', label: 'Create on GitHub ↗', url: 'https://{webHost}/settings/tokens/new?name=mcpkit+{server}' },
135
+ { type: 'link', label: 'Create on GitHub ↗', url: 'https://{webHost}/settings/tokens/new?name=usemcpkit+{server}' },
134
136
  { type: 'cli', label: 'Use GitHub CLI', command: 'gh', args: ['auth', 'token', '--hostname', '{webHost}'] },
135
137
  ],
136
138
  }),
@@ -157,7 +159,7 @@ with a name and the `api` scope.
157
159
 
158
160
  The CLI button is offered only for options with a single field. A domain typed in the form is used once it is valid. An imported token is saved like a
159
161
  typed one: only after the API accepts it. Manifests can be updated remotely (see below), so only use a registry you
160
- trust: its `cli` buttons name the programs mcpkit runs when you click them.
162
+ trust: its `cli` buttons name the programs usemcpkit runs when you click them.
161
163
 
162
164
  **Domain.** A server whose host differs per user (GitHub Enterprise, self-hosted GitLab, Jira...) writes
163
165
  `{domain}` in `baseUrl` and, if it has them, in the OAuth URLs, and declares `domain`:
@@ -168,6 +170,10 @@ trust: its `cli` buttons name the programs mcpkit runs when you click them.
168
170
 
169
171
  The domain comes from the env var, else `config.json`, else `default`. The form shows it prefilled and lets the
170
172
  user change it (`host[:port][/path]`, no scheme), unless the env var is set.
173
+ `suggestedHosts` lists hosts the field offers after the saved ones (n8n offers `app.n8n.cloud` and `localhost:5678`);
174
+ offering one does not pick it. With `loopbackHttp: true`, a `localhost` or `127.0.0.1` domain is reached over
175
+ `http://` in `baseUrl`, the upstream and OAuth URLs and `{domain}` links; every other server stays on `https://`, even on
176
+ localhost.
171
177
 
172
178
  **OAuth 2.0 with PKCE.** The user signs in once in the browser against the provider directly:
173
179
 
@@ -183,9 +189,9 @@ user change it (`host[:port][/path]`, no scheme), unless the env var is set.
183
189
  }
184
190
  ```
185
191
 
186
- The sign-in starts on the first tool call that has no working token: `mcpkit serve` prints the URL to stderr
192
+ The sign-in starts on the first tool call that has no working token: `usemcpkit serve` prints the URL to stderr
187
193
  and opens the browser. The redirect goes to `http://127.0.0.1:<port>/callback`, and the authorization code is
188
- exchanged with a S256 code verifier. The token is saved to `~/.mcpkit/tokens.json` (`MCPKIT_HOME` overrides)
194
+ exchanged with a S256 code verifier. The token is saved to `~/.usemcpkit/tokens.json` (`USEMCPKIT_HOME` overrides)
189
195
  with file mode `0600`, together with the entry that issued it. Tool calls send it as a Bearer token and refresh
190
196
  it before it expires. Concurrent calls share one sign-in. If the MCP client gives up waiting, the sign-in still
191
197
  finishes and the next call uses the token.
@@ -6,22 +6,6 @@ export declare type ArgSpec = NameList | NameMapping;
6
6
 
7
7
  export declare const array: (items: JsonSchema, description?: string) => Param;
8
8
 
9
- export declare interface AuthContext {
10
- env: Env;
11
- fetchImpl: typeof fetch;
12
- /** The directory the calling client works in; it picks the host of a server used on several hosts. */
13
- projectDir?: string;
14
- /** Shows the user the URL that starts a browser sign-in; without it a call never signs in. */
15
- onAuthorizationUrl?: (url: string) => void;
16
- /** Credentials saved from the credentials form; env vars win over them. */
17
- secretStore?: SecretStore;
18
- /** Asks the user for a domain and credentials when nothing provided works; without it no form is shown. */
19
- requestCredentials?: (request: CredentialRequest) => Promise<CredentialResponse>;
20
- }
21
-
22
- export declare class AuthError extends Error {
23
- }
24
-
25
9
  export declare type AuthSpec = NoneAuth | BearerAuth | HeaderAuth | QueryAuth | BasicAuth | OAuthAuth;
26
10
 
27
11
  declare interface BasicAuth {
@@ -45,20 +29,6 @@ declare interface BearerAuth {
45
29
 
46
30
  export declare const boolean: (description?: string, options?: ParamOptions) => Param;
47
31
 
48
- /** Expects args already passed through prepareToolArgs and loadFileArgs. */
49
- export declare const buildRequest: (manifest: Manifest, tool: ToolSpec, args: ToolArgs, auth: ResolvedAuth) => HttpRequest;
50
-
51
- /** A command that prints a token on stdout; run without a shell. */
52
- export declare interface CliTokenCommand {
53
- command: string;
54
- args: readonly string[];
55
- }
56
-
57
- export declare const compareVersions: (left: string, right: string) => number;
58
-
59
- /** Plain text in the 0600 config file under the mcpkit home, by server and host, read on every call so all running servers see each other's saves. */
60
- export declare const createFileSecretStore: (env?: Env) => SecretStore;
61
-
62
32
  export declare interface CredentialField {
63
33
  /** The env var that provides this value without the form. */
64
34
  key: string;
@@ -86,6 +56,8 @@ export declare interface CredentialRequest {
86
56
  domain?: DomainField;
87
57
  /** The domain in use when the form opened; the form's own domain field wins when it has one. */
88
58
  domainInUse?: string;
59
+ /** Links to a `localhost` or `127.0.0.1` domain open over `http://` (the manifest's `domain.loopbackHttp`). */
60
+ loopbackHttp?: boolean;
89
61
  options: readonly CredentialOption[];
90
62
  /** Whether the server offers an OAuth2 browser sign-in. */
91
63
  signIn: boolean;
@@ -100,9 +72,9 @@ export declare const CREDENTIALS_FORM_API: {
100
72
  readonly import: "/api/import";
101
73
  };
102
74
 
103
- export declare const CREDENTIALS_FORM_SESSION_HEADER = "X-Mcpkit-Session";
75
+ export declare const CREDENTIALS_FORM_SESSION_HEADER = "X-Usemcpkit-Session";
104
76
 
105
- export declare const CREDENTIALS_REQUEST_ELEMENT_ID = "mcpkit-request";
77
+ export declare const CREDENTIALS_REQUEST_ELEMENT_ID = "usemcpkit-request";
106
78
 
107
79
  export declare const DEFAULT_UI_TEXTS: Readonly<UiTexts>;
108
80
 
@@ -126,6 +98,8 @@ export declare interface DomainField {
126
98
  value: string;
127
99
  /** Hosts already used with this server, offered for picking; the user can still type a new one. */
128
100
  knownHosts: readonly string[];
101
+ /** Hosts the server suggests (`domain.suggestedHosts`), offered after the known ones; none is picked for the user. */
102
+ suggestedHosts?: readonly string[];
129
103
  }
130
104
 
131
105
  /** Lets one server talk to any host of the same API, for example a self-hosted GitHub Enterprise. */
@@ -140,6 +114,10 @@ export declare interface DomainSpec {
140
114
  env?: string;
141
115
  /** Picks the saved host the git remote of the working directory points at, so a repository needs no question. */
142
116
  matchGitRemote?: boolean;
117
+ /** Hosts the domain field offers besides the saved ones; offering one does not pick it. */
118
+ suggestedHosts?: readonly string[];
119
+ /** Reaches a `localhost` or `127.0.0.1` domain over `http://`, for servers that usually run locally without TLS. */
120
+ loopbackHttp?: boolean;
143
121
  }
144
122
 
145
123
  /** A deployment of the same API that needs other requests, for example Atlassian Cloud next to Data Center. */
@@ -149,20 +127,6 @@ export declare interface EditionSpec {
149
127
  hosts: readonly string[];
150
128
  }
151
129
 
152
- export declare type Env = Readonly<Record<string, string | undefined>>;
153
-
154
- export declare interface ExecuteOptions {
155
- fetchImpl?: typeof fetch;
156
- timeoutMs?: number;
157
- env?: Env;
158
- onAuthorizationUrl?: AuthContext["onAuthorizationUrl"];
159
- projectDir?: AuthContext["projectDir"];
160
- secretStore?: AuthContext["secretStore"];
161
- requestCredentials?: AuthContext["requestCredentials"];
162
- }
163
-
164
- export declare const executeTool: (manifest: Manifest, tool: ToolSpec, rawArgs: ToolArgs | undefined, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<unknown>;
165
-
166
130
  /** Auth whose credentials are provided up front: an env var, a saved value or the credentials form. */
167
131
  export declare type FallbackAuth = Exclude<AuthSpec, InteractiveAuth>;
168
132
 
@@ -182,17 +146,11 @@ export declare type FixedValues = Readonly<Record<string, FixedValue>>;
182
146
  * in the default browser (a webview has no tabs, so `target="_blank"` links go nowhere).
183
147
  */
184
148
  export declare const FORM_WINDOW_BINDINGS: {
185
- readonly close: "mcpkitCloseWindow";
186
- readonly fit: "mcpkitFitWindow";
187
- readonly openLink: "mcpkitOpenLink";
149
+ readonly close: "usemcpkitCloseWindow";
150
+ readonly fit: "usemcpkitFitWindow";
151
+ readonly openLink: "usemcpkitOpenLink";
188
152
  };
189
153
 
190
- /**
191
- * Resolves `a.b.c` paths; a `name[]` segment maps the rest of the path over an array.
192
- * The return type is declared because TypeScript cannot infer it for this recursive function.
193
- */
194
- export declare const getPath: (source: unknown, path: string) => unknown;
195
-
196
154
  declare interface HeaderAuth {
197
155
  type: "header";
198
156
  env: string;
@@ -208,13 +166,6 @@ declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
208
166
 
209
167
  export declare type HttpMethod = (typeof HTTP_METHODS)[number];
210
168
 
211
- export declare interface HttpRequest {
212
- url: string;
213
- method: HttpMethod;
214
- headers: Readonly<Record<string, string>>;
215
- body?: string | FormData | Blob;
216
- }
217
-
218
169
  /** An MCP server reached over Streamable HTTP; the manifest's `auth` signs the requests. */
219
170
  export declare interface HttpUpstream {
220
171
  type: "http";
@@ -240,12 +191,6 @@ export declare const isInteractiveAuth: (auth: AuthSpec) => auth is InteractiveA
240
191
 
241
192
  export declare const isJsonObject: (value: unknown) => value is Record<string, unknown>;
242
193
 
243
- export declare const isMissingFileError: (error: unknown) => boolean;
244
-
245
- export declare const isValidCredentialResponse: (request: CredentialRequest, response: unknown) => response is CredentialResponse;
246
-
247
- export declare const isValidManifest: (value: unknown) => value is Manifest;
248
-
249
194
  export declare interface JsonSchema {
250
195
  type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
251
196
  description?: string;
@@ -272,15 +217,13 @@ export declare interface Manifest {
272
217
  headers?: Readonly<Record<string, string>>;
273
218
  /** OAuth2 entries first, then fallbacks; tried top to bottom, the first that works is used. */
274
219
  auth?: readonly AuthSpec[];
275
- /** Page-wide texts of the credentials page, replacing mcpkit's defaults. */
220
+ /** Page-wide texts of the credentials page, replacing usemcpkit's defaults. */
276
221
  ui?: UiSpec;
277
222
  /** Another MCP server this one fronts: its tools are discovered at runtime, so `tools` stays empty. */
278
223
  upstream?: UpstreamSpec;
279
224
  tools: readonly ToolSpec[];
280
225
  }
281
226
 
282
- export declare const mapResponse: (data: unknown, response?: ResponseSpec) => unknown;
283
-
284
227
  declare type NameList = readonly string[];
285
228
 
286
229
  export declare type NameMapping = Readonly<Record<string, string>>;
@@ -332,8 +275,6 @@ export declare type ParamMap = Readonly<Record<string, Param>>;
332
275
 
333
276
  export declare type ParamOptions = Pick<JsonSchema, "default" | "enum">;
334
277
 
335
- export declare const prepareToolArgs: (tool: ToolSpec, rawArgs?: ToolArgs) => any;
336
-
337
278
  declare interface QueryAuth {
338
279
  type: "query";
339
280
  env: string;
@@ -378,61 +319,21 @@ declare interface RequestSpec {
378
319
  fixedBody?: FixedValues;
379
320
  }
380
321
 
381
- export declare const resolveCliCommand: (action: UiCliAction, domain: string | undefined) => CliTokenCommand;
382
-
383
- export declare interface ResolvedAuth {
384
- headers: Readonly<Record<string, string>>;
385
- query: Readonly<Record<string, string>>;
386
- }
387
-
388
- export declare const resolveHomeDir: (env?: Env) => string;
389
-
390
- /** Undefined while the link needs a domain and there is none yet. */
391
- export declare const resolveLinkUrl: (url: string, domain: string | undefined) => string | undefined;
392
-
393
- /** Builds a fallback entry's auth from its credential values, keyed by env var name. */
394
- export declare const resolveStaticAuth: (auth: FallbackAuth, serverName: string, env: Env) => ResolvedAuth;
322
+ /** Undefined while the link needs a domain and there is none yet; with `loopbackHttp` a link to a loopback domain opens over `http://`. */
323
+ export declare const resolveLinkUrl: (url: string, domain: string | undefined, loopbackHttp: boolean) => string | undefined;
395
324
 
396
325
  export declare interface ResponseSpec {
397
326
  root?: string;
398
327
  fields?: FieldSpec;
399
328
  }
400
329
 
401
- /** The server, and the host of it, a stored secret belongs to. */
402
- export declare interface SecretOwner extends ServerKey {
403
- domain?: string;
404
- }
405
-
406
- /** Where credentials and domains entered in the credentials form are kept, per server and key. */
407
- export declare interface SecretStore {
408
- get: (owner: SecretOwner, key: string) => Promise<string | undefined>;
409
- set: (owner: SecretOwner, key: string, value: string) => Promise<void>;
410
- }
411
-
412
330
  export declare const SERVER_NAME_PATTERN: RegExp;
413
331
 
414
- /** Where a server's settings live in the config: `servers.<category>.<name>`. */
415
- declare type ServerKey = Pick<Manifest, "name" | "category">;
416
-
417
- /** Runs the authorization code + PKCE flow through a loopback redirect and stores the token. */
418
- export declare const signIn: (serverName: string, auth: InteractiveAuth, { context, onAuthorizationUrl }: SignInOptions) => Promise<SignInResult>;
419
-
420
332
  export declare interface SignInCredentialResponse {
421
333
  method: "sign-in";
422
334
  domain?: string;
423
335
  }
424
336
 
425
- declare interface SignInOptions {
426
- context: AuthContext;
427
- /** Receives the URL the user must open to approve access. */
428
- onAuthorizationUrl: (url: string) => void;
429
- }
430
-
431
- export declare interface SignInResult {
432
- token: StoredToken;
433
- tokensFile: string;
434
- }
435
-
436
337
  /** An MCP server started as a child process and spoken to over its stdio. */
437
338
  export declare interface StdioUpstream {
438
339
  type: "stdio";
@@ -452,17 +353,6 @@ export declare interface StdioUpstream {
452
353
  naming?: readonly UpstreamNameRule[];
453
354
  }
454
355
 
455
- declare interface StoredToken {
456
- accessToken: string;
457
- tokenType: string;
458
- refreshToken?: string;
459
- /** Epoch milliseconds; absent when the provider issues non-expiring tokens. */
460
- expiresAt?: number;
461
- scope?: string;
462
- /** Identifies the manifest auth entry that issued the token, so it is refreshed against the same endpoint. */
463
- authKey?: string;
464
- }
465
-
466
356
  export declare const string: (description?: string, options?: ParamOptions) => Param;
467
357
 
468
358
  export declare interface TokenCredentialResponse {
@@ -495,9 +385,6 @@ export declare interface ToolEdition {
495
385
  response?: ResponseSpec;
496
386
  }
497
387
 
498
- export declare class ToolError extends Error {
499
- }
500
-
501
388
  export declare interface ToolSpec {
502
389
  name: string;
503
390
  description: string;
@@ -539,7 +426,7 @@ export declare interface UiLinkAction {
539
426
 
540
427
  /**
541
428
  * What the credentials page shows. On the manifest only `texts` applies (page-wide strings); on an auth entry
542
- * `inputs` (by env var name) and `actions` apply. Anything left out falls back to mcpkit's default text.
429
+ * `inputs` (by env var name) and `actions` apply. Anything left out falls back to usemcpkit's default text.
543
430
  */
544
431
  export declare interface UiSpec {
545
432
  texts?: Partial<UiTexts>;
@@ -548,7 +435,7 @@ export declare interface UiSpec {
548
435
  }
549
436
 
550
437
  /**
551
- * Every string the credentials page shows. `{server}` is filled in by mcpkit; `{key}`, `{name}`, `{label}` and
438
+ * Every string the credentials page shows. `{server}` is filled in by usemcpkit; `{key}`, `{name}`, `{label}` and
552
439
  * `{status}` are filled in where the text is used.
553
440
  */
554
441
  export declare interface UiTexts {
@@ -585,18 +472,7 @@ export declare interface UiTexts {
585
472
  requestFailed: string;
586
473
  }
587
474
 
588
- /** An upstream answered 401: the auth option that produced the credentials is rejected and the next one is tried. */
589
- export declare class UnauthorizedError extends Error {
590
- }
591
-
592
- /** Everything needed to open one upstream connection: where to go, how requests are signed, what the child gets. */
593
- export declare interface UpstreamAccess {
594
- upstream: UpstreamSpec;
595
- headers: Readonly<Record<string, string>>;
596
- env: Readonly<Record<string, string>>;
597
- }
598
-
599
- /** Renames the tools of an upstream server into mcpkit's `<group>:<resource>:<action>` form. */
475
+ /** Renames the tools of an upstream server into usemcpkit's `<group>:<resource>:<action>` form. */
600
476
  export declare interface UpstreamNameRule {
601
477
  /** A regular expression tested against the upstream tool name; the first rule that matches names the tool. */
602
478
  match: string;
@@ -604,7 +480,7 @@ export declare interface UpstreamNameRule {
604
480
  name: string;
605
481
  }
606
482
 
607
- /** A git repository the upstream server is run from, cloned on first use into `~/.mcpkit/repos/<category>/<name>`. */
483
+ /** A git repository the upstream server is run from, cloned on first use into `~/.usemcpkit/repos/<category>/<name>`. */
608
484
  export declare interface UpstreamRepo {
609
485
  url: string;
610
486
  /**
@@ -618,16 +494,4 @@ export declare interface UpstreamRepo {
618
494
 
619
495
  export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
620
496
 
621
- /** The form answer comes over a local HTTP request, so it is checked against what was asked. */
622
- export declare const validateCredentialResponse: (request: CredentialRequest, response: unknown) => string[];
623
-
624
- /** Manifests can be downloaded at runtime, so they are treated as untrusted input. */
625
- export declare const validateManifest: (manifest: unknown) => string[];
626
-
627
- /**
628
- * Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials, asked for in the credentials form when missing and saved once `run` succeeded; an HTTP one
629
- * tries the manifest's auth options in order like an API call does, moving on when `run` throws UnauthorizedError.
630
- */
631
- export declare const withUpstreamAccess: <T>(manifest: Manifest, run: (access: UpstreamAccess) => Promise<T>, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<T>;
632
-
633
497
  export { }