@haikit/mcp 0.0.0-stage → 0.32.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/LICENSE +21 -0
- package/README.md +63 -2
- package/dist/errors.d.ts +60 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +54 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +127 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +412 -0
- package/dist/index.js.map +1 -0
- package/dist/text.d.ts +16 -0
- package/dist/text.d.ts.map +1 -0
- package/dist/text.js +51 -0
- package/dist/text.js.map +1 -0
- package/dist/transports.d.ts +20 -0
- package/dist/transports.d.ts.map +1 -0
- package/dist/transports.js +28 -0
- package/dist/transports.js.map +1 -0
- package/package.json +52 -4
- package/src/errors.ts +78 -0
- package/src/index.ts +535 -0
- package/src/text.ts +60 -0
- package/src/transports.ts +33 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 hai contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,64 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @haikit/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Call an MCP server's tools from inside your own HaiKIT tools.
|
|
4
|
+
|
|
5
|
+
The model never sees an MCP tool. You declare the server tools your app may
|
|
6
|
+
call, typed by schemas you own, and call them from a tool's `run` or an action
|
|
7
|
+
handler, as you would a database. Your tool decides what the model hears of
|
|
8
|
+
the result and what the browser shows. Nothing a third-party server says
|
|
9
|
+
reaches the model unless your code puts it there: not its tools' names or
|
|
10
|
+
descriptions, not its instructions, and not its results.
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { mcpServer, http } from "@haikit/mcp";
|
|
14
|
+
import { defineTool } from "@haikit/core";
|
|
15
|
+
import { z } from "zod";
|
|
16
|
+
|
|
17
|
+
const github = mcpServer({
|
|
18
|
+
name: "github",
|
|
19
|
+
transport: http("https://api.example.com/mcp", { headers: { Authorization: `Bearer ${token}` } }),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
// each server tool the app may call, checked both ways by your schemas
|
|
23
|
+
const searchIssues = github.tool("search_issues", {
|
|
24
|
+
args: z.object({ q: z.string(), per_page: z.number() }),
|
|
25
|
+
result: z.object({ items: z.array(Issue) }),
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
// what the model sees is yours: the name, the description, the schema
|
|
29
|
+
export const findIssues = defineTool({
|
|
30
|
+
name: "find_issues",
|
|
31
|
+
description: "Search this project's issues.",
|
|
32
|
+
input: z.object({ query: z.string() }),
|
|
33
|
+
inputJsonSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
|
|
34
|
+
async run({ query }, ctx) {
|
|
35
|
+
const { items } = await searchIssues.call({ q: `repo:acme/app ${query}`, per_page: 50 }, ctx);
|
|
36
|
+
return ctx.render(issueList, { issues: items }); // rows to the browser, the digest to the model
|
|
37
|
+
},
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
await github.connect(); // at startup: stops here if a declared tool isn't on the server
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
- `stdio({ command, args })` starts a local server as a child process instead.
|
|
44
|
+
The child gets only a short list of safe environment variables, not yours.
|
|
45
|
+
- A call throws `McpToolError` when the tool reports an error, and `McpError`
|
|
46
|
+
when there's no result: bad args, a result your schema refuses, a timeout,
|
|
47
|
+
a lost connection, a refusal. The message names only the server and the
|
|
48
|
+
tool. What the server said is on `err.text`, so a tool that lets the error
|
|
49
|
+
through doesn't pass the server's words to the model.
|
|
50
|
+
- Progress from the server reaches `ctx.progress`, and keeps a long call alive.
|
|
51
|
+
A call times out after 30 s without word from the server, and after 90 s in
|
|
52
|
+
all, connecting included, inside the 120 s turn lease.
|
|
53
|
+
- `textOf(result)` turns a result into text, for a tool that decides to pass
|
|
54
|
+
some of it on. A cut is always marked in the text.
|
|
55
|
+
|
|
56
|
+
`McpTool` isn't a HaiKIT `Tool`, so it can't be passed to
|
|
57
|
+
`createHai({ tools })`: `npm run typetest` checks that.
|
|
58
|
+
|
|
59
|
+
Imports only `@haikit/core`, never `@haikit/server`. Built on
|
|
60
|
+
[`@modelcontextprotocol/client`](https://www.npmjs.com/package/@modelcontextprotocol/client),
|
|
61
|
+
the official TypeScript SDK's client.
|
|
62
|
+
|
|
63
|
+
Everything it does, with every default and message:
|
|
64
|
+
[the reference manual](https://github.com/wfoxd/haikit/blob/main/docs/reference/mcp.md).
|
package/dist/errors.d.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { ContentBlock } from "@modelcontextprotocol/client";
|
|
2
|
+
/**
|
|
3
|
+
* Why a call failed:
|
|
4
|
+
*
|
|
5
|
+
* - `args`: the args didn't match the tool's `args` schema, so nothing was sent.
|
|
6
|
+
* - `result`: the result didn't match its `result` schema.
|
|
7
|
+
* - `timeout`: the server didn't answer within `timeoutMs` or `maxTotalMs`.
|
|
8
|
+
* - `connection`: the server couldn't be reached, or the connection dropped.
|
|
9
|
+
* - `protocol`: the server refused the call, such as for a tool it doesn't
|
|
10
|
+
* have, or asked for something this client doesn't do.
|
|
11
|
+
* - `closed`: `close()` was called.
|
|
12
|
+
*/
|
|
13
|
+
export type McpErrorReason = "args" | "result" | "timeout" | "connection" | "protocol" | "closed";
|
|
14
|
+
/**
|
|
15
|
+
* A call that didn't get a result. The message names only the server and the
|
|
16
|
+
* tool, never what the server said: a HaiKIT tool that lets this go reaches the
|
|
17
|
+
* model as `<name> failed: <message>`, and the server's words aren't the app's
|
|
18
|
+
* to pass on unread. Its words are on `text`, for logs and for code that
|
|
19
|
+
* decides.
|
|
20
|
+
*
|
|
21
|
+
* Detected by `name` rather than `instanceof`, as in @haikit/core: a duplicated
|
|
22
|
+
* install would give two distinct classes.
|
|
23
|
+
*/
|
|
24
|
+
export declare class McpError extends Error {
|
|
25
|
+
readonly name = "McpError";
|
|
26
|
+
/** The server's `name`. */
|
|
27
|
+
readonly server: string;
|
|
28
|
+
/** The tool called. Absent when `connect()` failed. */
|
|
29
|
+
readonly tool: string | undefined;
|
|
30
|
+
readonly reason: McpErrorReason;
|
|
31
|
+
/** What the server said about it, when it said anything: a JSON-RPC error's message. */
|
|
32
|
+
readonly text: string | undefined;
|
|
33
|
+
/** A JSON-RPC error's code. */
|
|
34
|
+
readonly code: number | undefined;
|
|
35
|
+
constructor(reason: McpErrorReason, message: string, detail: {
|
|
36
|
+
server: string;
|
|
37
|
+
tool?: string;
|
|
38
|
+
text?: string;
|
|
39
|
+
code?: number;
|
|
40
|
+
cause?: unknown;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The tool ran and reported an error (`isError` in its result). Its message
|
|
45
|
+
* says only that, for the reason `McpError`'s does; what the server said is on
|
|
46
|
+
* `text` and `content`.
|
|
47
|
+
*/
|
|
48
|
+
export declare class McpToolError extends Error {
|
|
49
|
+
readonly name = "McpToolError";
|
|
50
|
+
readonly server: string;
|
|
51
|
+
readonly tool: string;
|
|
52
|
+
/** The result's text blocks, joined by newlines. */
|
|
53
|
+
readonly text: string;
|
|
54
|
+
/** The result's content blocks, as the server sent them. */
|
|
55
|
+
readonly content: ContentBlock[];
|
|
56
|
+
constructor(server: string, tool: string, content: ContentBlock[]);
|
|
57
|
+
}
|
|
58
|
+
export declare const isMcpError: (err: unknown) => err is McpError;
|
|
59
|
+
export declare const isMcpToolError: (err: unknown) => err is McpToolError;
|
|
60
|
+
//# sourceMappingURL=errors.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElG;;;;;;;;;GASG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,cAAc;IAC3B,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGhC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAS3F;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,CAAC;gBAErB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE;CAOlE;AAED,eAAO,MAAM,UAAU,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,QAA2D,CAAC;AAE7G,eAAO,MAAM,cAAc,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,YACA,CAAC"}
|
package/dist/errors.js
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A call that didn't get a result. The message names only the server and the
|
|
3
|
+
* tool, never what the server said: a HaiKIT tool that lets this go reaches the
|
|
4
|
+
* model as `<name> failed: <message>`, and the server's words aren't the app's
|
|
5
|
+
* to pass on unread. Its words are on `text`, for logs and for code that
|
|
6
|
+
* decides.
|
|
7
|
+
*
|
|
8
|
+
* Detected by `name` rather than `instanceof`, as in @haikit/core: a duplicated
|
|
9
|
+
* install would give two distinct classes.
|
|
10
|
+
*/
|
|
11
|
+
export class McpError extends Error {
|
|
12
|
+
name = "McpError";
|
|
13
|
+
/** The server's `name`. */
|
|
14
|
+
server;
|
|
15
|
+
/** The tool called. Absent when `connect()` failed. */
|
|
16
|
+
tool;
|
|
17
|
+
reason;
|
|
18
|
+
/** What the server said about it, when it said anything: a JSON-RPC error's message. */
|
|
19
|
+
text;
|
|
20
|
+
/** A JSON-RPC error's code. */
|
|
21
|
+
code;
|
|
22
|
+
constructor(reason, message, detail) {
|
|
23
|
+
super(message, detail.cause === undefined ? undefined : { cause: detail.cause });
|
|
24
|
+
this.reason = reason;
|
|
25
|
+
this.server = detail.server;
|
|
26
|
+
this.tool = detail.tool;
|
|
27
|
+
this.text = detail.text;
|
|
28
|
+
this.code = detail.code;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The tool ran and reported an error (`isError` in its result). Its message
|
|
33
|
+
* says only that, for the reason `McpError`'s does; what the server said is on
|
|
34
|
+
* `text` and `content`.
|
|
35
|
+
*/
|
|
36
|
+
export class McpToolError extends Error {
|
|
37
|
+
name = "McpToolError";
|
|
38
|
+
server;
|
|
39
|
+
tool;
|
|
40
|
+
/** The result's text blocks, joined by newlines. */
|
|
41
|
+
text;
|
|
42
|
+
/** The result's content blocks, as the server sent them. */
|
|
43
|
+
content;
|
|
44
|
+
constructor(server, tool, content) {
|
|
45
|
+
super(`${server}/${tool} reported an error`);
|
|
46
|
+
this.server = server;
|
|
47
|
+
this.tool = tool;
|
|
48
|
+
this.content = content;
|
|
49
|
+
this.text = content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("\n");
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
export const isMcpError = (err) => err instanceof Error && err.name === "McpError";
|
|
53
|
+
export const isMcpToolError = (err) => err instanceof Error && err.name === "McpToolError";
|
|
54
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAeA;;;;;;;;;GASG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,IAAI,GAAG,UAAU,CAAC;IAC3B,2BAA2B;IAClB,MAAM,CAAS;IACxB,uDAAuD;IAC9C,IAAI,CAAqB;IACzB,MAAM,CAAiB;IAChC,wFAAwF;IAC/E,IAAI,CAAqB;IAClC,+BAA+B;IACtB,IAAI,CAAqB;IAElC,YACE,MAAsB,EACtB,OAAe,EACf,MAAwF;QAExF,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,GAAG,cAAc,CAAC;IACtB,MAAM,CAAS;IACf,IAAI,CAAS;IACtB,oDAAoD;IAC3C,IAAI,CAAS;IACtB,4DAA4D;IACnD,OAAO,CAAiB;IAEjC,YAAY,MAAc,EAAE,IAAY,EAAE,OAAuB;QAC/D,KAAK,CAAC,GAAG,MAAM,IAAI,IAAI,oBAAoB,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrF,CAAC;CACF;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAY,EAAmB,EAAE,CAAC,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AAE7G,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAY,EAAuB,EAAE,CAClE,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @haikit/mcp — call MCP servers' tools from inside your own tools.
|
|
3
|
+
*
|
|
4
|
+
* The model never sees an MCP tool. An app declares the server tools it calls,
|
|
5
|
+
* typed by schemas it owns, and calls them from a HaiKIT tool's `run` or an
|
|
6
|
+
* action handler, the way it would call a database: that code decides what the
|
|
7
|
+
* model hears of a result and what the browser shows. So nothing a third-party
|
|
8
|
+
* server says — its tools' names and descriptions, its instructions, its
|
|
9
|
+
* results — reaches the model unless app code puts it there.
|
|
10
|
+
*
|
|
11
|
+
* There is no way to make a HaiKIT `Tool` from an MCP tool here, on purpose:
|
|
12
|
+
* an `McpTool` has no `run`, so `createHai({ tools })` won't take one.
|
|
13
|
+
*
|
|
14
|
+
* Imports only @haikit/core, like the model adapters.
|
|
15
|
+
*/
|
|
16
|
+
import type { Progress, Schema } from "@haikit/core";
|
|
17
|
+
import { type ContentBlock, type Transport, type VersionNegotiationMode } from "@modelcontextprotocol/client";
|
|
18
|
+
export { McpError, McpToolError, isMcpError, isMcpToolError, type McpErrorReason } from "./errors.js";
|
|
19
|
+
export { textOf, type TextOptions } from "./text.js";
|
|
20
|
+
export { http, stdio, type HttpOptions } from "./transports.js";
|
|
21
|
+
export type { ContentBlock, Transport } from "@modelcontextprotocol/client";
|
|
22
|
+
export interface McpServerOptions {
|
|
23
|
+
/** Names the server in errors and warnings, as in `github/search_issues`. */
|
|
24
|
+
name: string;
|
|
25
|
+
/**
|
|
26
|
+
* Makes a connection: called by the first `connect()` or call, and again
|
|
27
|
+
* for each reconnect. `http(url)` and `stdio({ command })` make one.
|
|
28
|
+
*/
|
|
29
|
+
transport: () => Transport | Promise<Transport>;
|
|
30
|
+
/**
|
|
31
|
+
* How long the server may go without answering a call or reporting progress
|
|
32
|
+
* on it, in milliseconds. Also bounds making the transport, connecting and
|
|
33
|
+
* listing tools. Default 30,000.
|
|
34
|
+
*/
|
|
35
|
+
timeoutMs?: number;
|
|
36
|
+
/**
|
|
37
|
+
* The longest a call may take, progress or not, connecting included, in
|
|
38
|
+
* milliseconds. Default 90,000.
|
|
39
|
+
*/
|
|
40
|
+
maxTotalMs?: number;
|
|
41
|
+
/**
|
|
42
|
+
* A declared tool was removed from the server, or its schema changed: seen
|
|
43
|
+
* when the server says its tools changed, and on a reconnect. Calls go on
|
|
44
|
+
* as before; one to a removed tool fails. Default: a `console.warn`. If it
|
|
45
|
+
* throws, the error is logged with `console.error`.
|
|
46
|
+
*/
|
|
47
|
+
onChange?: (change: McpToolChange) => void;
|
|
48
|
+
/** The SDK's protocol version negotiation. Default `"legacy"`, the SDK's own: the 2025 handshake. */
|
|
49
|
+
versionNegotiation?: VersionNegotiationMode;
|
|
50
|
+
}
|
|
51
|
+
export interface McpToolChange {
|
|
52
|
+
server: string;
|
|
53
|
+
/** Declared tools the server no longer has. */
|
|
54
|
+
removed: string[];
|
|
55
|
+
/** Declared tools whose input or output schema, or task support, changed. */
|
|
56
|
+
changed: string[];
|
|
57
|
+
}
|
|
58
|
+
export interface McpToolDef<A, R> {
|
|
59
|
+
/** Checks the args before anything is sent. They must come out an object. */
|
|
60
|
+
args: Schema<A>;
|
|
61
|
+
/**
|
|
62
|
+
* Checks the result, which `call` then resolves to: the server's structured
|
|
63
|
+
* result, or, without one, the JSON in its one text block. Without this,
|
|
64
|
+
* `call` resolves to the result's content as the server sent it.
|
|
65
|
+
*/
|
|
66
|
+
result?: Schema<R>;
|
|
67
|
+
/** Overrides the server's `timeoutMs` for this tool. */
|
|
68
|
+
timeoutMs?: number;
|
|
69
|
+
/** Overrides the server's `maxTotalMs` for this tool. */
|
|
70
|
+
maxTotalMs?: number;
|
|
71
|
+
}
|
|
72
|
+
/** A result with no `result` schema: what the server sent, unchecked. */
|
|
73
|
+
export interface McpResult {
|
|
74
|
+
/** The content blocks, as the server sent them. */
|
|
75
|
+
content: ContentBlock[];
|
|
76
|
+
/** The server's structured result, when it sent one. */
|
|
77
|
+
structuredContent?: unknown;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* What a call is made for. A HaiKIT tool's `ctx` or an action handler's can
|
|
81
|
+
* be passed as it is.
|
|
82
|
+
*/
|
|
83
|
+
export interface McpCallCtx {
|
|
84
|
+
/**
|
|
85
|
+
* The conversation the call is for. Nothing reads it yet: it is here so a
|
|
86
|
+
* later version can pick a connection per user without calls changing.
|
|
87
|
+
*/
|
|
88
|
+
readonly conversationId?: string;
|
|
89
|
+
/** Hears the server's progress notifications, as `ToolCtx.progress` does. */
|
|
90
|
+
progress?(progress: Progress): void;
|
|
91
|
+
}
|
|
92
|
+
/** One of the server's tools, as the app declared it. Not a HaiKIT `Tool`: the model never sees it. */
|
|
93
|
+
export interface McpTool<A, R> {
|
|
94
|
+
readonly server: string;
|
|
95
|
+
readonly name: string;
|
|
96
|
+
/**
|
|
97
|
+
* Calls the tool. Throws `McpToolError` when the tool reports an error, and
|
|
98
|
+
* `McpError` when the call gets no result, or one its schema refuses.
|
|
99
|
+
*/
|
|
100
|
+
call(args: A, ctx?: McpCallCtx): Promise<R>;
|
|
101
|
+
}
|
|
102
|
+
/** The connection to one MCP server, and the tools the app may call on it. */
|
|
103
|
+
export interface McpConnection {
|
|
104
|
+
readonly name: string;
|
|
105
|
+
/**
|
|
106
|
+
* Declares one of the server's tools: the only way to call it. Declared
|
|
107
|
+
* after `connect()`, it is checked against the server's tools at once.
|
|
108
|
+
*/
|
|
109
|
+
tool<A, R>(name: string, def: McpToolDef<A, R> & {
|
|
110
|
+
result: Schema<R>;
|
|
111
|
+
}): McpTool<A, R>;
|
|
112
|
+
tool<A>(name: string, def: McpToolDef<A, unknown> & {
|
|
113
|
+
result?: undefined;
|
|
114
|
+
}): McpTool<A, McpResult>;
|
|
115
|
+
/**
|
|
116
|
+
* Connects, and checks every declared tool: it throws if the server has no
|
|
117
|
+
* tool of that name, or one that can only run as an MCP task. Call it at
|
|
118
|
+
* startup, so a mistake stops the app there; the first call connects
|
|
119
|
+
* otherwise, and fails with the same error.
|
|
120
|
+
*/
|
|
121
|
+
connect(): Promise<void>;
|
|
122
|
+
/** Closes the connection, and stops a `stdio` server. Final: a later call fails with reason `closed`. */
|
|
123
|
+
close(): Promise<void>;
|
|
124
|
+
}
|
|
125
|
+
/** The connection to an MCP server. Nothing connects until `connect()` or the first call. */
|
|
126
|
+
export declare function mcpServer(options: McpServerOptions): McpConnection;
|
|
127
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|