@usemcpkit/core 0.1.0 → 0.4.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 +191 -0
- package/build/mcpkit.core.d.ts +98 -22
- package/build/mcpkit.core.js +702 -171
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# @usemcpkit/core
|
|
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.
|
|
6
|
+
|
|
7
|
+
Public surface: `src/main.ts` (built to `build/mcpkit.core.js` with bundled types in `build/mcpkit.core.d.ts`).
|
|
8
|
+
|
|
9
|
+
## Manifest format
|
|
10
|
+
|
|
11
|
+
```jsonc
|
|
12
|
+
{
|
|
13
|
+
"name": "github", // [a-z][a-z0-9_]*
|
|
14
|
+
"category": "git", // [a-z][a-z0-9-]*, groups servers of one kind
|
|
15
|
+
"version": "1.0.0",
|
|
16
|
+
"baseUrl": "https://{domain}", // https only; {domain} is optional, see Domain
|
|
17
|
+
"domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" },
|
|
18
|
+
"headers": { "Accept": "application/vnd.github+json" },
|
|
19
|
+
"auth": [ // tried top to bottom, see Auth
|
|
20
|
+
{ "type": "bearer", "env": "GITHUB_TOKEN" }
|
|
21
|
+
],
|
|
22
|
+
"tools": [
|
|
23
|
+
{
|
|
24
|
+
"name": "list_issues",
|
|
25
|
+
"description": "List issues in a repository.",
|
|
26
|
+
"input": { "type": "object", "properties": { ... }, "required": ["owner", "repo"] },
|
|
27
|
+
"request": {
|
|
28
|
+
"method": "GET",
|
|
29
|
+
"path": "/repos/{owner}/{repo}/issues", // {arg} → URL-encoded argument
|
|
30
|
+
"query": ["state", "per_page"], // or { "q": "query" } to rename
|
|
31
|
+
"body": ["title"], // JSON body for non-GET, see Request bodies
|
|
32
|
+
"commaQuery": ["tags"], // optional: array query keys joined with commas (others repeat the key)
|
|
33
|
+
"fileArgs": ["file"], // optional: args holding a local file path; sent as multipart parts (contentType multipart/form-data) or as the raw bodyArg
|
|
34
|
+
"saveToArg": "save_to", // optional: arg holding a local path; a successful response is written there and a summary returned
|
|
35
|
+
"fixedQuery": { "sort": "updated" }, // optional: constant query values
|
|
36
|
+
"contentType": "text/plain", // optional: default application/json; text/* sends bodyArg as plain text
|
|
37
|
+
"fixedHeaders": { "X-Atlassian-Token": "no-check" }, // optional: constant request headers
|
|
38
|
+
"fixedBody": { "type": "issue" }, // optional: constant body values, args win
|
|
39
|
+
"bodyArg": "body" // optional: send this arg as the whole JSON body (array, string or free-form object); excludes body/fixedBody
|
|
40
|
+
},
|
|
41
|
+
"response": {
|
|
42
|
+
"root": "items", // optional: dig into the payload
|
|
43
|
+
"fields": { "author": "user.login", "labels": "labels[].name" }
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
]
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Request bodies.** Outgoing body keys may be dotted paths that build nested JSON, with numbers as array
|
|
51
|
+
indexes: `{ "fields.project.key": "project_key", "ancestors.0.id": "parent_id" }` sends
|
|
52
|
+
`{"fields":{"project":{"key":"..."}},"ancestors":[{"id":"..."}]}`. `fixedBody` keys work the same way. Fixed values
|
|
53
|
+
are strings, numbers or booleans.
|
|
54
|
+
|
|
55
|
+
**Editions.** One server can cover deployments whose endpoints differ, such as Atlassian Cloud and Data Center. The
|
|
56
|
+
manifest names them with the host suffixes that select them; a tool overrides its `request` (and `response`, when
|
|
57
|
+
given) per edition. A domain matching no edition uses the tool's own request:
|
|
58
|
+
|
|
59
|
+
```jsonc
|
|
60
|
+
"editions": { "cloud": { "label": "Cloud", "hosts": [".atlassian.net"] } }, // names: [a-z][a-z0-9-]*
|
|
61
|
+
"tools": [
|
|
62
|
+
{
|
|
63
|
+
"name": "search_issues",
|
|
64
|
+
"request": { "method": "GET", "path": "/rest/api/2/search", "query": ["jql"] },
|
|
65
|
+
"editions": {
|
|
66
|
+
"cloud": { "request": { "method": "GET", "path": "/rest/api/2/search/jql", "query": ["jql"] } }
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The edition follows the domain in use, including one typed in the credentials form.
|
|
73
|
+
|
|
74
|
+
## Auth
|
|
75
|
+
|
|
76
|
+
`auth` lists OAuth2 entries (`oauth`) first, then fallbacks. A server can use fallbacks only:
|
|
77
|
+
|
|
78
|
+
```jsonc
|
|
79
|
+
"auth": [
|
|
80
|
+
{ "type": "oauth", "authorizationUrl": "...", "tokenUrl": "...", "clientId": "..." }, // optional
|
|
81
|
+
{ "type": "bearer", "env": "GITHUB_TOKEN" } // fallback
|
|
82
|
+
]
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Every tool call tries, in this order, and uses the first that works:
|
|
86
|
+
|
|
87
|
+
1. the server's OAuth2 token in `tokens.json`, refreshed if it expired (only when `auth` has `oauth` entries);
|
|
88
|
+
2. each fallback whose value is set, top to bottom. A value comes from its env var, or else from `config.json`;
|
|
89
|
+
3. the **credentials form**: a local page opened in the browser that asks for the missing values (and the domain,
|
|
90
|
+
see below), or offers "Sign in with OAuth2" when the server has `oauth` entries.
|
|
91
|
+
|
|
92
|
+
An option is skipped when its credentials are missing or the API answers `401`. A fallback that worked is tried right after `tokens.json` on later calls in the same process. If nothing works, the call fails with one line per option
|
|
93
|
+
saying why. `none` can only be the last entry. Leaving out `auth` means no auth.
|
|
94
|
+
|
|
95
|
+
**Fallbacks.** The manifest never holds a secret, only where to find it:
|
|
96
|
+
`none`, `bearer {env}`, `header {env, name, prefix?}`, `query {env, name}`, `basic {usernameEnv, passwordEnv}`
|
|
97
|
+
(each also takes an optional `label`, the option's title in the form; all but `none` take an optional
|
|
98
|
+
`ui`, see below).
|
|
99
|
+
Env vars always win, so CI keeps working without a browser.
|
|
100
|
+
|
|
101
|
+
**Credentials form.** `mcpkit serve` starts a one-off server on `127.0.0.1` (a free port), prints its URL to
|
|
102
|
+
stderr and opens the browser. Only the page that was opened can answer: the URL carries a session token in its
|
|
103
|
+
`#fragment` and the server checks it and the `Host` header. Concurrent calls share one form; it closes after
|
|
104
|
+
an answer, on Cancel, or after 5 minutes. Secrets are saved **only after the API accepts them**, so a typo is never
|
|
105
|
+
stored.
|
|
106
|
+
|
|
107
|
+
**Config file.** The hosts and the saved credentials live together in `~/.mcpkit/config.json`, by category, server and host
|
|
108
|
+
(`{ "servers": { "git": { "gitlab": { "hosts": { "git.acme.com": { "secrets": { "GITLAB_TOKEN": "glpat-…" } } }, "projects": { "/work/app": "git.acme.com" } } } } }`),
|
|
109
|
+
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
|
+
its env var; the host its project (git root) was bound to the first time you answered the form; the saved host the
|
|
111
|
+
project's `origin` remote points at (servers whose manifest sets `domain.matchGitRemote`, such as GitHub and GitLab);
|
|
112
|
+
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
|
|
114
|
+
protect your account and disk; to forget a credential, delete its entry or the file. Environment variables always win
|
|
115
|
+
over the file.
|
|
116
|
+
|
|
117
|
+
**Form UI.** The page holds no text of its own. The CLI injects the whole view model, built from the manifest, into
|
|
118
|
+
the page as JSON, and the page only renders it. Wording and buttons come from the manifest through `defineUI`:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
import { defineServer, defineUI } from '@usemcpkit/core';
|
|
122
|
+
|
|
123
|
+
defineServer({
|
|
124
|
+
// ...
|
|
125
|
+
ui: defineUI({ texts: { title: 'Connect {server}', submit: 'Save' } }), // any key of the default texts
|
|
126
|
+
auth: [
|
|
127
|
+
{
|
|
128
|
+
type: 'bearer',
|
|
129
|
+
env: 'GITHUB_TOKEN',
|
|
130
|
+
ui: defineUI({
|
|
131
|
+
inputs: { GITHUB_TOKEN: { label: 'Token', hint: '…', placeholder: 'ghp_…' } },
|
|
132
|
+
actions: [
|
|
133
|
+
{ type: 'link', label: 'Create on GitHub ↗', url: 'https://{webHost}/settings/tokens/new?name=mcpkit+{server}' },
|
|
134
|
+
{ type: 'cli', label: 'Use GitHub CLI', command: 'gh', args: ['auth', 'token', '--hostname', '{webHost}'] },
|
|
135
|
+
],
|
|
136
|
+
}),
|
|
137
|
+
},
|
|
138
|
+
],
|
|
139
|
+
});
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- `texts` (on the manifest) overrides the defaults in core (`DEFAULT_UI_TEXTS`); `{server}` is filled in. `domain`
|
|
143
|
+
also takes `hint` and `placeholder`.
|
|
144
|
+
- `inputs` (on an auth entry, keyed by env var name) sets a field's `label`, `hint` and `placeholder`.
|
|
145
|
+
- A `link` action opens an `https://` URL. `{domain}` is the typed domain, `{webHost}` its web host
|
|
146
|
+
(`api.github.com` → `github.com`, `api.<name>.ghe.com` → `<name>.ghe.com`, `<host>/api/v3` → `<host>`), `{server}`
|
|
147
|
+
the server name. The link follows the domain field and stays hidden while it needs a domain and there is none.
|
|
148
|
+
- A `cli` action carries its own `command` and `args`; core has no list of tools. `command` must be a program name
|
|
149
|
+
found on PATH (no path, no arguments), and `args` may use `{domain}` and `{webHost}`. On click the CLI process, not
|
|
150
|
+
the page, runs it without a shell, with a 15 s timeout; the token it prints goes straight to the API check and never
|
|
151
|
+
reaches the browser. It is offered only for an entry with a single credential, and only when the program is on PATH
|
|
152
|
+
when the form opens. Nothing runs without the click.
|
|
153
|
+
|
|
154
|
+
GitLab offers **Use GitLab CLI**, which runs `glab config get token --host <host>`. **Create on GitLab ↗** opens the personal access token page of the server's
|
|
155
|
+
host (`<host>/-/user_settings/personal_access_tokens`, under the relative URL root if the domain has one), prefilled
|
|
156
|
+
with a name and the `api` scope.
|
|
157
|
+
|
|
158
|
+
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
|
+
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.
|
|
161
|
+
|
|
162
|
+
**Domain.** A server whose host differs per user (GitHub Enterprise, self-hosted GitLab, Jira...) writes
|
|
163
|
+
`{domain}` in `baseUrl` and, if it has them, in the OAuth URLs, and declares `domain`:
|
|
164
|
+
|
|
165
|
+
```jsonc
|
|
166
|
+
"domain": { "label": "GitHub API host", "default": "api.github.com", "env": "GITHUB_API_HOST" } // all optional
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
The domain comes from the env var, else `config.json`, else `default`. The form shows it prefilled and lets the
|
|
170
|
+
user change it (`host[:port][/path]`, no scheme), unless the env var is set.
|
|
171
|
+
|
|
172
|
+
**OAuth 2.0 with PKCE.** The user signs in once in the browser against the provider directly:
|
|
173
|
+
|
|
174
|
+
```jsonc
|
|
175
|
+
{
|
|
176
|
+
"type": "oauth",
|
|
177
|
+
"authorizationUrl": "https://example.com/oauth/authorize", // https only, {domain} allowed
|
|
178
|
+
"tokenUrl": "https://example.com/oauth/token", // https only, {domain} allowed
|
|
179
|
+
"clientId": "public-client-id",
|
|
180
|
+
"clientSecretEnv": "EXAMPLE_CLIENT_SECRET", // optional, for providers that need one
|
|
181
|
+
"scopes": ["read", "write"], // optional
|
|
182
|
+
"redirectPort": 8976 // optional, 0 picks a free port
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
The sign-in starts on the first tool call that has no working token: `mcpkit serve` prints the URL to stderr
|
|
187
|
+
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)
|
|
189
|
+
with file mode `0600`, together with the entry that issued it. Tool calls send it as a Bearer token and refresh
|
|
190
|
+
it before it expires. Concurrent calls share one sign-in. If the MCP client gives up waiting, the sign-in still
|
|
191
|
+
finishes and the next call uses the token.
|
package/build/mcpkit.core.d.ts
CHANGED
|
@@ -9,6 +9,8 @@ export declare const array: (items: JsonSchema, description?: string) => Param;
|
|
|
9
9
|
export declare interface AuthContext {
|
|
10
10
|
env: Env;
|
|
11
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;
|
|
12
14
|
/** Shows the user the URL that starts a browser sign-in; without it a call never signs in. */
|
|
13
15
|
onAuthorizationUrl?: (url: string) => void;
|
|
14
16
|
/** Credentials saved from the credentials form; env vars win over them. */
|
|
@@ -23,7 +25,7 @@ export declare class AuthError extends Error {
|
|
|
23
25
|
export declare type AuthSpec = NoneAuth | BearerAuth | HeaderAuth | QueryAuth | BasicAuth | OAuthAuth;
|
|
24
26
|
|
|
25
27
|
declare interface BasicAuth {
|
|
26
|
-
type:
|
|
28
|
+
type: "basic";
|
|
27
29
|
usernameEnv: string;
|
|
28
30
|
passwordEnv: string;
|
|
29
31
|
/** Shown for this option in the credentials form instead of its auth type and env vars. */
|
|
@@ -33,7 +35,7 @@ declare interface BasicAuth {
|
|
|
33
35
|
}
|
|
34
36
|
|
|
35
37
|
declare interface BearerAuth {
|
|
36
|
-
type:
|
|
38
|
+
type: "bearer";
|
|
37
39
|
env: string;
|
|
38
40
|
/** Shown for this option in the credentials form instead of its auth type and env vars. */
|
|
39
41
|
label?: string;
|
|
@@ -43,7 +45,7 @@ declare interface BearerAuth {
|
|
|
43
45
|
|
|
44
46
|
export declare const boolean: (description?: string, options?: ParamOptions) => Param;
|
|
45
47
|
|
|
46
|
-
/** Expects args already passed through prepareToolArgs. */
|
|
48
|
+
/** Expects args already passed through prepareToolArgs and loadFileArgs. */
|
|
47
49
|
export declare const buildRequest: (manifest: Manifest, tool: ToolSpec, args: ToolArgs, auth: ResolvedAuth) => HttpRequest;
|
|
48
50
|
|
|
49
51
|
/** A command that prints a token on stdout; run without a shell. */
|
|
@@ -54,7 +56,7 @@ export declare interface CliTokenCommand {
|
|
|
54
56
|
|
|
55
57
|
export declare const compareVersions: (left: string, right: string) => number;
|
|
56
58
|
|
|
57
|
-
/** Plain text in
|
|
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. */
|
|
58
60
|
export declare const createFileSecretStore: (env?: Env) => SecretStore;
|
|
59
61
|
|
|
60
62
|
export declare interface CredentialField {
|
|
@@ -122,6 +124,8 @@ export declare interface DomainField {
|
|
|
122
124
|
placeholder: string;
|
|
123
125
|
/** The domain in use, prefilled in the form; empty when there is none yet. */
|
|
124
126
|
value: string;
|
|
127
|
+
/** Hosts already used with this server, offered for picking; the user can still type a new one. */
|
|
128
|
+
knownHosts: readonly string[];
|
|
125
129
|
}
|
|
126
130
|
|
|
127
131
|
/** Lets one server talk to any host of the same API, for example a self-hosted GitHub Enterprise. */
|
|
@@ -134,6 +138,8 @@ export declare interface DomainSpec {
|
|
|
134
138
|
default?: string;
|
|
135
139
|
/** Env var that sets the domain; when it is set the form does not ask for one. */
|
|
136
140
|
env?: string;
|
|
141
|
+
/** Picks the saved host the git remote of the working directory points at, so a repository needs no question. */
|
|
142
|
+
matchGitRemote?: boolean;
|
|
137
143
|
}
|
|
138
144
|
|
|
139
145
|
/** A deployment of the same API that needs other requests, for example Atlassian Cloud next to Data Center. */
|
|
@@ -149,9 +155,10 @@ export declare interface ExecuteOptions {
|
|
|
149
155
|
fetchImpl?: typeof fetch;
|
|
150
156
|
timeoutMs?: number;
|
|
151
157
|
env?: Env;
|
|
152
|
-
onAuthorizationUrl?: AuthContext[
|
|
153
|
-
|
|
154
|
-
|
|
158
|
+
onAuthorizationUrl?: AuthContext["onAuthorizationUrl"];
|
|
159
|
+
projectDir?: AuthContext["projectDir"];
|
|
160
|
+
secretStore?: AuthContext["secretStore"];
|
|
161
|
+
requestCredentials?: AuthContext["requestCredentials"];
|
|
155
162
|
}
|
|
156
163
|
|
|
157
164
|
export declare const executeTool: (manifest: Manifest, tool: ToolSpec, rawArgs: ToolArgs | undefined, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<unknown>;
|
|
@@ -177,7 +184,7 @@ export declare type FixedValues = Readonly<Record<string, FixedValue>>;
|
|
|
177
184
|
export declare const getPath: (source: unknown, path: string) => unknown;
|
|
178
185
|
|
|
179
186
|
declare interface HeaderAuth {
|
|
180
|
-
type:
|
|
187
|
+
type: "header";
|
|
181
188
|
env: string;
|
|
182
189
|
name: string;
|
|
183
190
|
/** Shown for this option in the credentials form instead of its auth type and env vars. */
|
|
@@ -195,14 +202,21 @@ export declare interface HttpRequest {
|
|
|
195
202
|
url: string;
|
|
196
203
|
method: HttpMethod;
|
|
197
204
|
headers: Readonly<Record<string, string>>;
|
|
198
|
-
body?: string;
|
|
205
|
+
body?: string | FormData | Blob;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** An MCP server reached over Streamable HTTP; the manifest's `auth` signs the requests. */
|
|
209
|
+
export declare interface HttpUpstream {
|
|
210
|
+
type: "http";
|
|
211
|
+
/** May contain `{domain}`. */
|
|
212
|
+
url: string;
|
|
199
213
|
}
|
|
200
214
|
|
|
201
215
|
/** Builds an object input schema; `required` is derived from the params. */
|
|
202
216
|
export declare const input: (params?: ParamMap) => InputSchema;
|
|
203
217
|
|
|
204
218
|
export declare interface InputSchema extends JsonSchema {
|
|
205
|
-
type:
|
|
219
|
+
type: "object";
|
|
206
220
|
}
|
|
207
221
|
|
|
208
222
|
export declare type InteractiveAuth = OAuthAuth;
|
|
@@ -221,7 +235,7 @@ export declare const isValidCredentialResponse: (request: CredentialRequest, res
|
|
|
221
235
|
export declare const isValidManifest: (value: unknown) => value is Manifest;
|
|
222
236
|
|
|
223
237
|
export declare interface JsonSchema {
|
|
224
|
-
type?:
|
|
238
|
+
type?: "string" | "number" | "integer" | "boolean" | "array" | "object";
|
|
225
239
|
description?: string;
|
|
226
240
|
default?: unknown;
|
|
227
241
|
enum?: readonly unknown[];
|
|
@@ -238,7 +252,7 @@ export declare interface Manifest {
|
|
|
238
252
|
category: string;
|
|
239
253
|
version: string;
|
|
240
254
|
description?: string;
|
|
241
|
-
/** May contain `{domain}`, as may the oauth URLs; `domain` then says where the value comes from. */
|
|
255
|
+
/** May contain `{domain}`, as may the oauth URLs; `domain` then says where the value comes from. An `upstream` manifest never requests it, so it only names the service's https home. */
|
|
242
256
|
baseUrl: string;
|
|
243
257
|
domain?: DomainSpec;
|
|
244
258
|
/** Deployments picked by the domain's host; a domain matching none uses the tools' own requests. */
|
|
@@ -248,6 +262,8 @@ export declare interface Manifest {
|
|
|
248
262
|
auth?: readonly AuthSpec[];
|
|
249
263
|
/** Page-wide texts of the credentials page, replacing mcpkit's defaults. */
|
|
250
264
|
ui?: UiSpec;
|
|
265
|
+
/** Another MCP server this one fronts: its tools are discovered at runtime, so `tools` stays empty. */
|
|
266
|
+
upstream?: UpstreamSpec;
|
|
251
267
|
tools: readonly ToolSpec[];
|
|
252
268
|
}
|
|
253
269
|
|
|
@@ -258,14 +274,14 @@ declare type NameList = readonly string[];
|
|
|
258
274
|
export declare type NameMapping = Readonly<Record<string, string>>;
|
|
259
275
|
|
|
260
276
|
declare interface NoneAuth {
|
|
261
|
-
type:
|
|
277
|
+
type: "none";
|
|
262
278
|
}
|
|
263
279
|
|
|
264
280
|
export declare const number: (description?: string, options?: ParamOptions) => Param;
|
|
265
281
|
|
|
266
282
|
/** OAuth 2.0 authorization code flow with PKCE; the browser sign-in starts on the first tool call without a stored token. */
|
|
267
283
|
export declare interface OAuthAuth {
|
|
268
|
-
type:
|
|
284
|
+
type: "oauth";
|
|
269
285
|
authorizationUrl: string;
|
|
270
286
|
tokenUrl: string;
|
|
271
287
|
clientId: string;
|
|
@@ -273,6 +289,12 @@ export declare interface OAuthAuth {
|
|
|
273
289
|
scopes?: readonly string[];
|
|
274
290
|
/** Loopback port for the redirect URI; 0 picks a free port. */
|
|
275
291
|
redirectPort?: number;
|
|
292
|
+
/** Extra query parameters on the authorization URL, e.g. a provider's flag for a long-lived refresh token. */
|
|
293
|
+
authorizationParams?: Readonly<Record<string, string>>;
|
|
294
|
+
/** Where the client id and secret travel on token requests: the form body (default) or an HTTP Basic header (an absent secret is sent empty). */
|
|
295
|
+
clientAuthentication?: "body" | "basic";
|
|
296
|
+
/** Extra headers on token requests, for providers that reject anonymous clients. */
|
|
297
|
+
tokenHeaders?: Readonly<Record<string, string>>;
|
|
276
298
|
}
|
|
277
299
|
|
|
278
300
|
export declare const oneOf: (values: readonly string[], description?: string, options?: ParamOptions) => Param;
|
|
@@ -289,12 +311,12 @@ export declare interface Param extends JsonSchema {
|
|
|
289
311
|
|
|
290
312
|
export declare type ParamMap = Readonly<Record<string, Param>>;
|
|
291
313
|
|
|
292
|
-
export declare type ParamOptions = Pick<JsonSchema,
|
|
314
|
+
export declare type ParamOptions = Pick<JsonSchema, "default" | "enum">;
|
|
293
315
|
|
|
294
316
|
export declare const prepareToolArgs: (tool: ToolSpec, rawArgs?: ToolArgs) => any;
|
|
295
317
|
|
|
296
318
|
declare interface QueryAuth {
|
|
297
|
-
type:
|
|
319
|
+
type: "query";
|
|
298
320
|
env: string;
|
|
299
321
|
name: string;
|
|
300
322
|
/** Shown for this option in the credentials form instead of its auth type and env vars. */
|
|
@@ -310,7 +332,22 @@ declare interface RequestSpec {
|
|
|
310
332
|
query?: ArgSpec;
|
|
311
333
|
/** Outgoing keys may be dotted paths such as `fields.project.key` or `ancestors.0.id` to build nested JSON. */
|
|
312
334
|
body?: ArgSpec;
|
|
335
|
+
/** Names the argument sent unchanged as the whole JSON body (an array, string or free-form object); excludes `body` and `fixedBody`. */
|
|
336
|
+
bodyArg?: string;
|
|
337
|
+
/** Defaults to `application/json`. A `text/*` type sends `bodyArg` as plain text, `multipart/form-data` sends `body` fields and `fileArgs` as form parts; any other type is sent as JSON. */
|
|
338
|
+
contentType?: string;
|
|
339
|
+
/** Outgoing query keys whose array values are joined with commas; other arrays repeat the key once per item. */
|
|
340
|
+
commaQuery?: readonly string[];
|
|
341
|
+
/**
|
|
342
|
+
* Names of arguments holding a local file path or an array of them. With `contentType` multipart/form-data the files become form
|
|
343
|
+
* parts; with `bodyArg` naming one of them the file is the raw request body.
|
|
344
|
+
*/
|
|
345
|
+
fileArgs?: readonly string[];
|
|
346
|
+
/** Names the argument holding the local path a successful response is saved to, instead of being returned. */
|
|
347
|
+
saveToArg?: string;
|
|
313
348
|
fixedQuery?: FixedValues;
|
|
349
|
+
/** Header values sent on every call; auth headers win over them. */
|
|
350
|
+
fixedHeaders?: Readonly<Record<string, string>>;
|
|
314
351
|
/** Dotted paths like `body`; an argument with the same key wins. */
|
|
315
352
|
fixedBody?: FixedValues;
|
|
316
353
|
}
|
|
@@ -335,8 +372,10 @@ export declare interface ResponseSpec {
|
|
|
335
372
|
fields?: FieldSpec;
|
|
336
373
|
}
|
|
337
374
|
|
|
338
|
-
/** The server a stored secret belongs to. */
|
|
339
|
-
export declare
|
|
375
|
+
/** The server, and the host of it, a stored secret belongs to. */
|
|
376
|
+
export declare interface SecretOwner extends ServerKey {
|
|
377
|
+
domain?: string;
|
|
378
|
+
}
|
|
340
379
|
|
|
341
380
|
/** Where credentials and domains entered in the credentials form are kept, per server and key. */
|
|
342
381
|
export declare interface SecretStore {
|
|
@@ -346,11 +385,14 @@ export declare interface SecretStore {
|
|
|
346
385
|
|
|
347
386
|
export declare const SERVER_NAME_PATTERN: RegExp;
|
|
348
387
|
|
|
388
|
+
/** Where a server's settings live in the config: `servers.<category>.<name>`. */
|
|
389
|
+
declare type ServerKey = Pick<Manifest, "name" | "category">;
|
|
390
|
+
|
|
349
391
|
/** Runs the authorization code + PKCE flow through a loopback redirect and stores the token. */
|
|
350
392
|
export declare const signIn: (serverName: string, auth: InteractiveAuth, { context, onAuthorizationUrl }: SignInOptions) => Promise<SignInResult>;
|
|
351
393
|
|
|
352
394
|
export declare interface SignInCredentialResponse {
|
|
353
|
-
method:
|
|
395
|
+
method: "sign-in";
|
|
354
396
|
domain?: string;
|
|
355
397
|
}
|
|
356
398
|
|
|
@@ -365,6 +407,16 @@ export declare interface SignInResult {
|
|
|
365
407
|
tokensFile: string;
|
|
366
408
|
}
|
|
367
409
|
|
|
410
|
+
/** An MCP server started as a child process and spoken to over its stdio. */
|
|
411
|
+
export declare interface StdioUpstream {
|
|
412
|
+
type: "stdio";
|
|
413
|
+
/** A program name on PATH, never a path. */
|
|
414
|
+
command: string;
|
|
415
|
+
args?: readonly string[];
|
|
416
|
+
/** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables. */
|
|
417
|
+
forwardEnv?: readonly string[];
|
|
418
|
+
}
|
|
419
|
+
|
|
368
420
|
declare interface StoredToken {
|
|
369
421
|
accessToken: string;
|
|
370
422
|
tokenType: string;
|
|
@@ -379,7 +431,7 @@ declare interface StoredToken {
|
|
|
379
431
|
export declare const string: (description?: string, options?: ParamOptions) => Param;
|
|
380
432
|
|
|
381
433
|
export declare interface TokenCredentialResponse {
|
|
382
|
-
method:
|
|
434
|
+
method: "token";
|
|
383
435
|
/** `index` of the chosen credential option. */
|
|
384
436
|
option: number;
|
|
385
437
|
/** Values per field key. */
|
|
@@ -397,6 +449,9 @@ export declare interface TokenImportRequest {
|
|
|
397
449
|
|
|
398
450
|
export declare const toNameMapping: (spec: NameList | NameMapping) => Readonly<Record<string, string>>;
|
|
399
451
|
|
|
452
|
+
/** `resource:action`, for example `pull_request:list`; the action part is optional. */
|
|
453
|
+
export declare const TOOL_NAME_PATTERN: RegExp;
|
|
454
|
+
|
|
400
455
|
export declare type ToolArgs = Readonly<Record<string, unknown>>;
|
|
401
456
|
|
|
402
457
|
/** Replaces the tool's request, and its response mapping when given, for one edition. */
|
|
@@ -425,7 +480,7 @@ export declare type UiAction = UiLinkAction | UiCliAction;
|
|
|
425
480
|
* and `args` may use `{domain}` and `{webHost}`.
|
|
426
481
|
*/
|
|
427
482
|
export declare interface UiCliAction {
|
|
428
|
-
type:
|
|
483
|
+
type: "cli";
|
|
429
484
|
label: string;
|
|
430
485
|
command: string;
|
|
431
486
|
args: readonly string[];
|
|
@@ -440,7 +495,7 @@ export declare interface UiInputSpec {
|
|
|
440
495
|
|
|
441
496
|
/** A button that opens `url` in a new tab; `{domain}`, `{webHost}` and `{server}` are filled in. */
|
|
442
497
|
export declare interface UiLinkAction {
|
|
443
|
-
type:
|
|
498
|
+
type: "link";
|
|
444
499
|
label: string;
|
|
445
500
|
url: string;
|
|
446
501
|
}
|
|
@@ -467,6 +522,8 @@ export declare interface UiTexts {
|
|
|
467
522
|
domainLabel: string;
|
|
468
523
|
domainHint: string;
|
|
469
524
|
domainPlaceholder: string;
|
|
525
|
+
domainNewHost: string;
|
|
526
|
+
domainShowHosts: string;
|
|
470
527
|
signInLabel: string;
|
|
471
528
|
tokenDivider: string;
|
|
472
529
|
credentialLegend: string;
|
|
@@ -490,10 +547,29 @@ export declare interface UiTexts {
|
|
|
490
547
|
requestFailed: string;
|
|
491
548
|
}
|
|
492
549
|
|
|
550
|
+
/** An upstream answered 401: the auth option that produced the credentials is rejected and the next one is tried. */
|
|
551
|
+
export declare class UnauthorizedError extends Error {
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
/** Everything needed to open one upstream connection: where to go, how requests are signed, what the child gets. */
|
|
555
|
+
export declare interface UpstreamAccess {
|
|
556
|
+
upstream: UpstreamSpec;
|
|
557
|
+
headers: Readonly<Record<string, string>>;
|
|
558
|
+
env: Readonly<Record<string, string>>;
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
export declare type UpstreamSpec = HttpUpstream | StdioUpstream;
|
|
562
|
+
|
|
493
563
|
/** The form answer comes over a local HTTP request, so it is checked against what was asked. */
|
|
494
564
|
export declare const validateCredentialResponse: (request: CredentialRequest, response: unknown) => string[];
|
|
495
565
|
|
|
496
566
|
/** Manifests can be downloaded at runtime, so they are treated as untrusted input. */
|
|
497
567
|
export declare const validateManifest: (manifest: unknown) => string[];
|
|
498
568
|
|
|
569
|
+
/**
|
|
570
|
+
* Runs `run` with the access of an `upstream` manifest. A stdio upstream gets its forwarded credentials; an HTTP one
|
|
571
|
+
* tries the manifest's auth options in order like an API call does, moving on when `run` throws UnauthorizedError.
|
|
572
|
+
*/
|
|
573
|
+
export declare const withUpstreamAccess: <T>(manifest: Manifest, run: (access: UpstreamAccess) => Promise<T>, { fetchImpl, timeoutMs, env, ...hooks }?: ExecuteOptions) => Promise<T>;
|
|
574
|
+
|
|
499
575
|
export { }
|