bigtool-ts 0.1.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/CHANGELOG.md +27 -0
- package/LICENSE +21 -0
- package/README.md +641 -0
- package/dist/adapters/agent-protocol.d.ts +149 -0
- package/dist/adapters/agent-protocol.d.ts.map +1 -0
- package/dist/adapters/agent-protocol.js +133 -0
- package/dist/adapters/agent-protocol.js.map +1 -0
- package/dist/adapters/index.d.ts +39 -0
- package/dist/adapters/index.d.ts.map +1 -0
- package/dist/adapters/index.js +42 -0
- package/dist/adapters/index.js.map +1 -0
- package/dist/adapters/inngest.d.ts +234 -0
- package/dist/adapters/inngest.d.ts.map +1 -0
- package/dist/adapters/inngest.js +276 -0
- package/dist/adapters/inngest.js.map +1 -0
- package/dist/adapters/mastra.d.ts +201 -0
- package/dist/adapters/mastra.d.ts.map +1 -0
- package/dist/adapters/mastra.js +250 -0
- package/dist/adapters/mastra.js.map +1 -0
- package/dist/adapters/types.d.ts +42 -0
- package/dist/adapters/types.d.ts.map +1 -0
- package/dist/adapters/types.js +6 -0
- package/dist/adapters/types.js.map +1 -0
- package/dist/adapters/vercel-ai.d.ts +176 -0
- package/dist/adapters/vercel-ai.d.ts.map +1 -0
- package/dist/adapters/vercel-ai.js +244 -0
- package/dist/adapters/vercel-ai.js.map +1 -0
- package/dist/catalog/index.d.ts +177 -0
- package/dist/catalog/index.d.ts.map +1 -0
- package/dist/catalog/index.js +244 -0
- package/dist/catalog/index.js.map +1 -0
- package/dist/graph/agent.d.ts +214 -0
- package/dist/graph/agent.d.ts.map +1 -0
- package/dist/graph/agent.js +196 -0
- package/dist/graph/agent.js.map +1 -0
- package/dist/graph/index.d.ts +5 -0
- package/dist/graph/index.d.ts.map +1 -0
- package/dist/graph/index.js +4 -0
- package/dist/graph/index.js.map +1 -0
- package/dist/graph/nodes.d.ts +100 -0
- package/dist/graph/nodes.d.ts.map +1 -0
- package/dist/graph/nodes.js +190 -0
- package/dist/graph/nodes.js.map +1 -0
- package/dist/graph/search-tool.d.ts +34 -0
- package/dist/graph/search-tool.d.ts.map +1 -0
- package/dist/graph/search-tool.js +54 -0
- package/dist/graph/search-tool.js.map +1 -0
- package/dist/graph/state.d.ts +26 -0
- package/dist/graph/state.d.ts.map +1 -0
- package/dist/graph/state.js +29 -0
- package/dist/graph/state.js.map +1 -0
- package/dist/index.d.ts +69 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +85 -0
- package/dist/index.js.map +1 -0
- package/dist/loader/index.d.ts +172 -0
- package/dist/loader/index.d.ts.map +1 -0
- package/dist/loader/index.js +179 -0
- package/dist/loader/index.js.map +1 -0
- package/dist/loader/loader.d.ts +114 -0
- package/dist/loader/loader.d.ts.map +1 -0
- package/dist/loader/loader.js +185 -0
- package/dist/loader/loader.js.map +1 -0
- package/dist/search/cache.d.ts +76 -0
- package/dist/search/cache.d.ts.map +1 -0
- package/dist/search/cache.js +135 -0
- package/dist/search/cache.js.map +1 -0
- package/dist/search/index.d.ts +63 -0
- package/dist/search/index.d.ts.map +1 -0
- package/dist/search/index.js +122 -0
- package/dist/search/index.js.map +1 -0
- package/dist/search/normalize.d.ts +104 -0
- package/dist/search/normalize.d.ts.map +1 -0
- package/dist/search/normalize.js +211 -0
- package/dist/search/normalize.js.map +1 -0
- package/dist/search/orama.d.ts +256 -0
- package/dist/search/orama.d.ts.map +1 -0
- package/dist/search/orama.js +511 -0
- package/dist/search/orama.js.map +1 -0
- package/dist/search/types.d.ts +96 -0
- package/dist/search/types.d.ts.map +1 -0
- package/dist/search/types.js +8 -0
- package/dist/search/types.js.map +1 -0
- package/dist/sources/dynamic.d.ts +200 -0
- package/dist/sources/dynamic.d.ts.map +1 -0
- package/dist/sources/dynamic.js +194 -0
- package/dist/sources/dynamic.js.map +1 -0
- package/dist/sources/index.d.ts +11 -0
- package/dist/sources/index.d.ts.map +1 -0
- package/dist/sources/index.js +14 -0
- package/dist/sources/index.js.map +1 -0
- package/dist/sources/local.d.ts +128 -0
- package/dist/sources/local.d.ts.map +1 -0
- package/dist/sources/local.js +155 -0
- package/dist/sources/local.js.map +1 -0
- package/dist/sources/mcp.d.ts +438 -0
- package/dist/sources/mcp.d.ts.map +1 -0
- package/dist/sources/mcp.js +438 -0
- package/dist/sources/mcp.js.map +1 -0
- package/dist/sources/types.d.ts +16 -0
- package/dist/sources/types.d.ts.map +1 -0
- package/dist/sources/types.js +7 -0
- package/dist/sources/types.js.map +1 -0
- package/dist/sources/with-metadata.d.ts +7 -0
- package/dist/sources/with-metadata.d.ts.map +1 -0
- package/dist/sources/with-metadata.js +7 -0
- package/dist/sources/with-metadata.js.map +1 -0
- package/dist/types/index.d.ts +7 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +8 -0
- package/dist/types/index.js.map +1 -0
- package/dist/types.d.ts +700 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +97 -0
- package/dist/types.js.map +1 -0
- package/package.json +118 -0
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* LocalSource module.
|
|
3
|
+
*
|
|
4
|
+
* Provides a ToolSource implementation for in-memory StructuredTool instances.
|
|
5
|
+
*
|
|
6
|
+
* @module sources/local
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* A tool source backed by local StructuredTool instances.
|
|
10
|
+
*
|
|
11
|
+
* LocalSource is the simplest way to add tools to the discovery system.
|
|
12
|
+
* It wraps an array of StructuredTool instances and exposes them through
|
|
13
|
+
* the ToolSource interface.
|
|
14
|
+
*
|
|
15
|
+
* Tools are stored in memory and returned immediately when requested.
|
|
16
|
+
* Use {@link withMetadata} to add categories and keywords for better
|
|
17
|
+
* search matching.
|
|
18
|
+
*
|
|
19
|
+
* @example Basic usage
|
|
20
|
+
* ```typescript
|
|
21
|
+
* import { LocalSource } from '@repo/bigtool-ts';
|
|
22
|
+
*
|
|
23
|
+
* const source = new LocalSource([
|
|
24
|
+
* calculatorTool,
|
|
25
|
+
* weatherTool,
|
|
26
|
+
* searchTool,
|
|
27
|
+
* ]);
|
|
28
|
+
*
|
|
29
|
+
* // Register with catalog
|
|
30
|
+
* await catalog.register(source);
|
|
31
|
+
* ```
|
|
32
|
+
*
|
|
33
|
+
* @example With custom ID
|
|
34
|
+
* ```typescript
|
|
35
|
+
* const utilitySource = new LocalSource(utilityTools, 'utilities');
|
|
36
|
+
* const aiSource = new LocalSource(aiTools, 'ai');
|
|
37
|
+
*
|
|
38
|
+
* // Tools will be namespaced: 'utilities:calculator', 'ai:chat'
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* @example With enhanced metadata
|
|
42
|
+
* ```typescript
|
|
43
|
+
* import { LocalSource, withMetadata } from '@repo/bigtool-ts';
|
|
44
|
+
*
|
|
45
|
+
* const tools = [
|
|
46
|
+
* withMetadata(createPRTool, {
|
|
47
|
+
* categories: ['github', 'git'],
|
|
48
|
+
* keywords: ['PR', 'pull request', 'merge'],
|
|
49
|
+
* }),
|
|
50
|
+
* withMetadata(reviewPRTool, {
|
|
51
|
+
* categories: ['github', 'git'],
|
|
52
|
+
* keywords: ['review', 'approve', 'comment'],
|
|
53
|
+
* }),
|
|
54
|
+
* ];
|
|
55
|
+
*
|
|
56
|
+
* const source = new LocalSource(tools, 'github');
|
|
57
|
+
* ```
|
|
58
|
+
*/
|
|
59
|
+
export class LocalSource {
|
|
60
|
+
/**
|
|
61
|
+
* Unique identifier for this source.
|
|
62
|
+
*
|
|
63
|
+
* Used to namespace tool IDs (e.g., 'local:calculator').
|
|
64
|
+
*/
|
|
65
|
+
id;
|
|
66
|
+
/** @internal Map of tool name to StructuredTool */
|
|
67
|
+
tools;
|
|
68
|
+
/** @internal Cached metadata for all tools */
|
|
69
|
+
metadata;
|
|
70
|
+
/**
|
|
71
|
+
* Creates a new LocalSource.
|
|
72
|
+
*
|
|
73
|
+
* @param tools - Array of StructuredTool instances to expose
|
|
74
|
+
* @param id - Optional source identifier (default: 'local')
|
|
75
|
+
*
|
|
76
|
+
* @example
|
|
77
|
+
* ```typescript
|
|
78
|
+
* const source = new LocalSource([tool1, tool2]);
|
|
79
|
+
* const namedSource = new LocalSource([tool1, tool2], 'my-tools');
|
|
80
|
+
* ```
|
|
81
|
+
*/
|
|
82
|
+
constructor(tools, id) {
|
|
83
|
+
this.id = id ?? 'local';
|
|
84
|
+
this.tools = new Map();
|
|
85
|
+
this.metadata = [];
|
|
86
|
+
for (const tool of tools) {
|
|
87
|
+
this.tools.set(tool.name, tool);
|
|
88
|
+
this.metadata.push(this.extractMetadata(tool));
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Extracts metadata from a StructuredTool.
|
|
93
|
+
*
|
|
94
|
+
* @internal
|
|
95
|
+
* @param tool - The tool to extract metadata from
|
|
96
|
+
* @returns Tool metadata for indexing
|
|
97
|
+
*/
|
|
98
|
+
extractMetadata(tool) {
|
|
99
|
+
const toolWithMeta = tool;
|
|
100
|
+
const enhancement = toolWithMeta.__bigtool_metadata ?? toolWithMeta.metadata;
|
|
101
|
+
// Namespace the tool ID with the source prefix
|
|
102
|
+
const namespacedId = `${this.id}:${tool.name}`;
|
|
103
|
+
return {
|
|
104
|
+
id: namespacedId,
|
|
105
|
+
name: tool.name,
|
|
106
|
+
description: tool.description,
|
|
107
|
+
parameters: tool.schema ? JSON.parse(JSON.stringify(tool.schema)) : undefined,
|
|
108
|
+
categories: enhancement?.categories,
|
|
109
|
+
keywords: enhancement?.keywords,
|
|
110
|
+
source: 'local',
|
|
111
|
+
sourceId: this.id,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Get metadata for all tools in this source.
|
|
116
|
+
*
|
|
117
|
+
* Returns cached metadata extracted during construction.
|
|
118
|
+
* This is synchronous internally but returns a Promise for
|
|
119
|
+
* interface compatibility.
|
|
120
|
+
*
|
|
121
|
+
* @returns Promise resolving to array of tool metadata
|
|
122
|
+
*
|
|
123
|
+
* @example
|
|
124
|
+
* ```typescript
|
|
125
|
+
* const metadata = await source.getMetadata();
|
|
126
|
+
* console.log(`Found ${metadata.length} tools`);
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
129
|
+
async getMetadata() {
|
|
130
|
+
return this.metadata;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Get a tool by its ID.
|
|
134
|
+
*
|
|
135
|
+
* Accepts both prefixed IDs (e.g., 'local:calculator') and bare
|
|
136
|
+
* tool names (e.g., 'calculator'). Returns the tool immediately
|
|
137
|
+
* from memory.
|
|
138
|
+
*
|
|
139
|
+
* @param id - Tool ID or bare name
|
|
140
|
+
* @returns Promise resolving to the tool, or null if not found
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```typescript
|
|
144
|
+
* const tool = await source.getTool('local:calculator');
|
|
145
|
+
* // or
|
|
146
|
+
* const tool = await source.getTool('calculator');
|
|
147
|
+
* ```
|
|
148
|
+
*/
|
|
149
|
+
async getTool(id) {
|
|
150
|
+
// Handle both prefixed ID (local:toolName) and bare name (toolName)
|
|
151
|
+
const bareName = id.startsWith(`${this.id}:`) ? id.slice(this.id.length + 1) : id;
|
|
152
|
+
return this.tools.get(bareName) ?? null;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
//# sourceMappingURL=local.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/sources/local.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,OAAO,WAAW;IACtB;;;;OAIG;IACM,EAAE,CAAS;IAEpB,mDAAmD;IAC3C,KAAK,CAA8B;IAE3C,8CAA8C;IACtC,QAAQ,CAAiB;IAEjC;;;;;;;;;;;OAWG;IACH,YAAY,KAAuB,EAAE,EAAW;QAC9C,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,OAAO,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,eAAe,CAAC,IAAoB;QAM1C,MAAM,YAAY,GAAG,IAAyC,CAAC;QAC/D,MAAM,WAAW,GAAG,YAAY,CAAC,kBAAkB,IAAI,YAAY,CAAC,QAAQ,CAAC;QAE7E,+CAA+C;QAC/C,MAAM,YAAY,GAAG,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAE/C,OAAO;YACL,EAAE,EAAE,YAAY;YAChB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;YAC7E,UAAU,EAAE,WAAW,EAAE,UAAU;YACnC,QAAQ,EAAE,WAAW,EAAE,QAAQ;YAC/B,MAAM,EAAE,OAAO;YACf,QAAQ,EAAE,IAAI,CAAC,EAAE;SAClB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,WAAW;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,oEAAoE;QACpE,MAAM,QAAQ,GAAG,EAAE,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClF,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC;IAC1C,CAAC;CACF"}
|
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCPSource module.
|
|
3
|
+
*
|
|
4
|
+
* Provides a ToolSource implementation that connects to an MCP
|
|
5
|
+
* (Model Context Protocol) server and exposes its tools.
|
|
6
|
+
*
|
|
7
|
+
* Supports two patterns:
|
|
8
|
+
* 1. Pre-connected client: Pass an already-connected MCPClient
|
|
9
|
+
* 2. Config-based: Pass server config and MCPSource manages the connection
|
|
10
|
+
*
|
|
11
|
+
* @module sources/mcp
|
|
12
|
+
*/
|
|
13
|
+
import type { StructuredTool } from "@langchain/core/tools";
|
|
14
|
+
import type { ToolSource, ToolMetadata, EventEmitter } from "../types.js";
|
|
15
|
+
/**
|
|
16
|
+
* MCP Client interface.
|
|
17
|
+
*
|
|
18
|
+
* This is a subset of the @modelcontextprotocol/sdk Client interface.
|
|
19
|
+
* Using an interface allows MCPSource to work with any compatible
|
|
20
|
+
* client without a hard dependency on the MCP SDK.
|
|
21
|
+
*
|
|
22
|
+
* @example Using with MCP SDK
|
|
23
|
+
* ```typescript
|
|
24
|
+
* import { Client } from '@modelcontextprotocol/sdk/client';
|
|
25
|
+
*
|
|
26
|
+
* const client = new Client({ name: 'github' });
|
|
27
|
+
* await client.connect(transport);
|
|
28
|
+
*
|
|
29
|
+
* const source = new MCPSource(client);
|
|
30
|
+
* ```
|
|
31
|
+
*/
|
|
32
|
+
export interface MCPClient {
|
|
33
|
+
/**
|
|
34
|
+
* Client name, used as default namespace.
|
|
35
|
+
*
|
|
36
|
+
* If not provided, 'mcp' is used.
|
|
37
|
+
*/
|
|
38
|
+
name?: string;
|
|
39
|
+
/**
|
|
40
|
+
* List available tools from the MCP server.
|
|
41
|
+
*
|
|
42
|
+
* @returns Promise with array of tool definitions
|
|
43
|
+
*/
|
|
44
|
+
listTools(): Promise<{
|
|
45
|
+
tools: Array<{
|
|
46
|
+
name: string;
|
|
47
|
+
description?: string;
|
|
48
|
+
inputSchema?: Record<string, unknown>;
|
|
49
|
+
}>;
|
|
50
|
+
}>;
|
|
51
|
+
/**
|
|
52
|
+
* Call a tool on the MCP server.
|
|
53
|
+
*
|
|
54
|
+
* @param params - Tool call parameters
|
|
55
|
+
* @returns Promise with tool execution result
|
|
56
|
+
*/
|
|
57
|
+
callTool(params: {
|
|
58
|
+
name: string;
|
|
59
|
+
arguments?: Record<string, unknown>;
|
|
60
|
+
}): Promise<{
|
|
61
|
+
content?: Array<{
|
|
62
|
+
type: string;
|
|
63
|
+
text?: string;
|
|
64
|
+
}>;
|
|
65
|
+
isError?: boolean;
|
|
66
|
+
}>;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Configuration options for MCPSource.
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```typescript
|
|
73
|
+
* const options: MCPSourceOptions = {
|
|
74
|
+
* namespace: 'github',
|
|
75
|
+
* refreshInterval: 60000, // Refresh every minute
|
|
76
|
+
* };
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
export interface MCPSourceOptions {
|
|
80
|
+
/**
|
|
81
|
+
* Namespace for tool IDs.
|
|
82
|
+
*
|
|
83
|
+
* Tool IDs are formatted as 'mcp:{namespace}:{toolName}'.
|
|
84
|
+
*
|
|
85
|
+
* @default client.name or 'default'
|
|
86
|
+
*/
|
|
87
|
+
namespace?: string;
|
|
88
|
+
/**
|
|
89
|
+
* Refresh interval in milliseconds.
|
|
90
|
+
*
|
|
91
|
+
* If set, the source will periodically refresh its tool list
|
|
92
|
+
* from the MCP server. Set to 0 or omit to disable.
|
|
93
|
+
*
|
|
94
|
+
* @default undefined (no auto-refresh)
|
|
95
|
+
*/
|
|
96
|
+
refreshInterval?: number;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* MCPSource connects to an MCP server and provides its tools.
|
|
100
|
+
*
|
|
101
|
+
* Tools are fetched from the MCP server on first access and cached.
|
|
102
|
+
* Wrapper tools are created lazily that delegate execution back to
|
|
103
|
+
* the server.
|
|
104
|
+
*
|
|
105
|
+
* The source can optionally refresh its tool list periodically to
|
|
106
|
+
* pick up new tools or changes from the server.
|
|
107
|
+
*
|
|
108
|
+
* @example Basic usage
|
|
109
|
+
* ```typescript
|
|
110
|
+
* import { MCPSource } from '@repo/bigtool-ts';
|
|
111
|
+
* import { Client } from '@modelcontextprotocol/sdk/client';
|
|
112
|
+
*
|
|
113
|
+
* const client = new Client({ name: 'github' });
|
|
114
|
+
* await client.connect(transport);
|
|
115
|
+
*
|
|
116
|
+
* const source = new MCPSource(client);
|
|
117
|
+
* await catalog.register(source);
|
|
118
|
+
* ```
|
|
119
|
+
*
|
|
120
|
+
* @example With auto-refresh
|
|
121
|
+
* ```typescript
|
|
122
|
+
* const source = new MCPSource(client, {
|
|
123
|
+
* namespace: 'github',
|
|
124
|
+
* refreshInterval: 60000, // Check for new tools every minute
|
|
125
|
+
* });
|
|
126
|
+
*
|
|
127
|
+
* // Listen for refresh events
|
|
128
|
+
* source.onRefresh.subscribe((metadata) => {
|
|
129
|
+
* console.log(`Refreshed: ${metadata.length} tools`);
|
|
130
|
+
* });
|
|
131
|
+
* ```
|
|
132
|
+
*/
|
|
133
|
+
export declare class MCPSource implements ToolSource {
|
|
134
|
+
/**
|
|
135
|
+
* Unique identifier for this source.
|
|
136
|
+
*
|
|
137
|
+
* Format: 'mcp:{namespace}' (e.g., 'mcp:github').
|
|
138
|
+
*/
|
|
139
|
+
readonly id: string;
|
|
140
|
+
/** @internal The MCP client */
|
|
141
|
+
private client;
|
|
142
|
+
/** @internal Cached tool metadata */
|
|
143
|
+
private metadata;
|
|
144
|
+
/** @internal Cache of wrapped tools */
|
|
145
|
+
private toolCache;
|
|
146
|
+
/** @internal Timer for periodic refresh */
|
|
147
|
+
private refreshTimer?;
|
|
148
|
+
/** @internal Whether initial fetch has completed */
|
|
149
|
+
private initialized;
|
|
150
|
+
/**
|
|
151
|
+
* Event emitter for refresh notifications.
|
|
152
|
+
*
|
|
153
|
+
* Subscribe to be notified when the tool list is refreshed
|
|
154
|
+
* from the MCP server.
|
|
155
|
+
*/
|
|
156
|
+
readonly onRefresh: EventEmitter<ToolMetadata[]>;
|
|
157
|
+
/**
|
|
158
|
+
* Creates a new MCPSource.
|
|
159
|
+
*
|
|
160
|
+
* @param client - MCP client instance (must be connected)
|
|
161
|
+
* @param options - Configuration options
|
|
162
|
+
*
|
|
163
|
+
* @example
|
|
164
|
+
* ```typescript
|
|
165
|
+
* const source = new MCPSource(client, {
|
|
166
|
+
* namespace: 'github',
|
|
167
|
+
* refreshInterval: 60000,
|
|
168
|
+
* });
|
|
169
|
+
* ```
|
|
170
|
+
*/
|
|
171
|
+
constructor(client: MCPClient, options?: MCPSourceOptions);
|
|
172
|
+
/**
|
|
173
|
+
* Get metadata for all tools from this MCP server.
|
|
174
|
+
*
|
|
175
|
+
* Fetches from the server on first call, then returns cached metadata.
|
|
176
|
+
* Call refresh() to update the metadata from the server.
|
|
177
|
+
*
|
|
178
|
+
* @returns Promise resolving to array of tool metadata
|
|
179
|
+
*
|
|
180
|
+
* @example
|
|
181
|
+
* ```typescript
|
|
182
|
+
* const metadata = await source.getMetadata();
|
|
183
|
+
* console.log(`MCP server has ${metadata.length} tools`);
|
|
184
|
+
* ```
|
|
185
|
+
*/
|
|
186
|
+
getMetadata(): Promise<ToolMetadata[]>;
|
|
187
|
+
/**
|
|
188
|
+
* Get a tool by its ID.
|
|
189
|
+
*
|
|
190
|
+
* Creates a wrapper tool on first request that delegates execution
|
|
191
|
+
* to the MCP server. Wrappers are cached for subsequent calls.
|
|
192
|
+
*
|
|
193
|
+
* @param id - Tool ID (e.g., 'mcp:github:create_pr' or just 'create_pr')
|
|
194
|
+
* @returns Promise resolving to the tool wrapper, or null if not found
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* ```typescript
|
|
198
|
+
* const tool = await source.getTool('mcp:github:create_pr');
|
|
199
|
+
* if (tool) {
|
|
200
|
+
* const result = await tool.invoke({ title: 'My PR' });
|
|
201
|
+
* }
|
|
202
|
+
* ```
|
|
203
|
+
*/
|
|
204
|
+
getTool(id: string): Promise<StructuredTool | null>;
|
|
205
|
+
/**
|
|
206
|
+
* Refresh the tool list from the MCP server.
|
|
207
|
+
*
|
|
208
|
+
* Fetches the current tool list, updates metadata, clears the
|
|
209
|
+
* tool wrapper cache, and emits an onRefresh event.
|
|
210
|
+
*
|
|
211
|
+
* @throws MCPSourceError if the server request fails
|
|
212
|
+
*
|
|
213
|
+
* @example
|
|
214
|
+
* ```typescript
|
|
215
|
+
* // Manually refresh tools
|
|
216
|
+
* await source.refresh();
|
|
217
|
+
*
|
|
218
|
+
* // Or listen for auto-refresh events
|
|
219
|
+
* source.onRefresh.subscribe((metadata) => {
|
|
220
|
+
* console.log('Tools refreshed:', metadata.length);
|
|
221
|
+
* });
|
|
222
|
+
* ```
|
|
223
|
+
*/
|
|
224
|
+
refresh(): Promise<void>;
|
|
225
|
+
/**
|
|
226
|
+
* Create a wrapper tool that delegates execution to the MCP server.
|
|
227
|
+
*/
|
|
228
|
+
private createToolWrapper;
|
|
229
|
+
/**
|
|
230
|
+
* Create a Zod-like schema from MCP input schema.
|
|
231
|
+
* For simplicity, we create a pass-through schema.
|
|
232
|
+
*/
|
|
233
|
+
private createSchemaFromParameters;
|
|
234
|
+
/**
|
|
235
|
+
* Clean up resources.
|
|
236
|
+
*
|
|
237
|
+
* Stops the refresh timer and clears all event subscriptions.
|
|
238
|
+
* Call this when you're done with the source to prevent memory leaks.
|
|
239
|
+
*
|
|
240
|
+
* @example
|
|
241
|
+
* ```typescript
|
|
242
|
+
* // When shutting down
|
|
243
|
+
* source.dispose();
|
|
244
|
+
* catalog.unregister(source.id);
|
|
245
|
+
* ```
|
|
246
|
+
*/
|
|
247
|
+
dispose(): void;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Error thrown when MCP source operations fail.
|
|
251
|
+
*
|
|
252
|
+
* This error indicates a problem with the MCP server connection
|
|
253
|
+
* or protocol, such as failing to list tools.
|
|
254
|
+
*
|
|
255
|
+
* @example
|
|
256
|
+
* ```typescript
|
|
257
|
+
* try {
|
|
258
|
+
* await source.refresh();
|
|
259
|
+
* } catch (error) {
|
|
260
|
+
* if (error instanceof MCPSourceError) {
|
|
261
|
+
* console.error('MCP server error:', error.message);
|
|
262
|
+
* }
|
|
263
|
+
* }
|
|
264
|
+
* ```
|
|
265
|
+
*/
|
|
266
|
+
export declare class MCPSourceError extends Error {
|
|
267
|
+
/**
|
|
268
|
+
* Creates a new MCPSourceError.
|
|
269
|
+
*
|
|
270
|
+
* @param message - Error message
|
|
271
|
+
* @param options - Error options (e.g., cause)
|
|
272
|
+
*/
|
|
273
|
+
constructor(message: string, options?: ErrorOptions);
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Error thrown when MCP tool execution fails.
|
|
277
|
+
*
|
|
278
|
+
* This error indicates a problem executing a specific tool on
|
|
279
|
+
* the MCP server, such as invalid arguments or server-side errors.
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* ```typescript
|
|
283
|
+
* try {
|
|
284
|
+
* await tool.invoke({ title: '' });
|
|
285
|
+
* } catch (error) {
|
|
286
|
+
* if (error instanceof MCPToolError) {
|
|
287
|
+
* console.error('Tool execution failed:', error.message);
|
|
288
|
+
* }
|
|
289
|
+
* }
|
|
290
|
+
* ```
|
|
291
|
+
*/
|
|
292
|
+
export declare class MCPToolError extends Error {
|
|
293
|
+
/**
|
|
294
|
+
* Creates a new MCPToolError.
|
|
295
|
+
*
|
|
296
|
+
* @param message - Error message
|
|
297
|
+
* @param options - Error options (e.g., cause)
|
|
298
|
+
*/
|
|
299
|
+
constructor(message: string, options?: ErrorOptions);
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Configuration for connecting to an MCP server via stdio transport.
|
|
303
|
+
*
|
|
304
|
+
* Used when the MCP server is a local process that communicates via stdin/stdout.
|
|
305
|
+
*
|
|
306
|
+
* @example
|
|
307
|
+
* ```typescript
|
|
308
|
+
* const config: MCPStdioConfig = {
|
|
309
|
+
* name: 'github',
|
|
310
|
+
* transport: 'stdio',
|
|
311
|
+
* command: 'npx',
|
|
312
|
+
* args: ['-y', '@modelcontextprotocol/server-github'],
|
|
313
|
+
* env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
|
|
314
|
+
* };
|
|
315
|
+
* ```
|
|
316
|
+
*/
|
|
317
|
+
export interface MCPStdioConfig {
|
|
318
|
+
/** Unique name for this server (used as namespace) */
|
|
319
|
+
name: string;
|
|
320
|
+
/** Transport type */
|
|
321
|
+
transport: "stdio";
|
|
322
|
+
/** Command to execute (e.g., 'npx', 'node', 'python') */
|
|
323
|
+
command: string;
|
|
324
|
+
/** Command arguments */
|
|
325
|
+
args?: string[];
|
|
326
|
+
/** Environment variables to pass to the process */
|
|
327
|
+
env?: Record<string, string | undefined>;
|
|
328
|
+
/** Working directory for the process */
|
|
329
|
+
cwd?: string;
|
|
330
|
+
/** Refresh interval in milliseconds (optional) */
|
|
331
|
+
refreshInterval?: number;
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* Configuration for connecting to an MCP server via SSE transport.
|
|
335
|
+
*
|
|
336
|
+
* Used when the MCP server is a remote HTTP server using Server-Sent Events.
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```typescript
|
|
340
|
+
* const config: MCPSSEConfig = {
|
|
341
|
+
* name: 'remote-tools',
|
|
342
|
+
* transport: 'sse',
|
|
343
|
+
* url: 'https://mcp.example.com/sse',
|
|
344
|
+
* headers: { Authorization: 'Bearer xxx' },
|
|
345
|
+
* };
|
|
346
|
+
* ```
|
|
347
|
+
*/
|
|
348
|
+
export interface MCPSSEConfig {
|
|
349
|
+
/** Unique name for this server (used as namespace) */
|
|
350
|
+
name: string;
|
|
351
|
+
/** Transport type */
|
|
352
|
+
transport: "sse";
|
|
353
|
+
/** SSE endpoint URL */
|
|
354
|
+
url: string;
|
|
355
|
+
/** Optional HTTP headers for authentication */
|
|
356
|
+
headers?: Record<string, string>;
|
|
357
|
+
/** Refresh interval in milliseconds (optional) */
|
|
358
|
+
refreshInterval?: number;
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Configuration for connecting to an MCP server via WebSocket transport.
|
|
362
|
+
*
|
|
363
|
+
* @example
|
|
364
|
+
* ```typescript
|
|
365
|
+
* const config: MCPWebSocketConfig = {
|
|
366
|
+
* name: 'realtime-tools',
|
|
367
|
+
* transport: 'websocket',
|
|
368
|
+
* url: 'wss://mcp.example.com/ws',
|
|
369
|
+
* };
|
|
370
|
+
* ```
|
|
371
|
+
*/
|
|
372
|
+
export interface MCPWebSocketConfig {
|
|
373
|
+
/** Unique name for this server (used as namespace) */
|
|
374
|
+
name: string;
|
|
375
|
+
/** Transport type */
|
|
376
|
+
transport: "websocket";
|
|
377
|
+
/** WebSocket endpoint URL */
|
|
378
|
+
url: string;
|
|
379
|
+
/** Refresh interval in milliseconds (optional) */
|
|
380
|
+
refreshInterval?: number;
|
|
381
|
+
}
|
|
382
|
+
/**
|
|
383
|
+
* Union type for all MCP server configurations.
|
|
384
|
+
*/
|
|
385
|
+
export type MCPServerConfig = MCPStdioConfig | MCPSSEConfig | MCPWebSocketConfig;
|
|
386
|
+
/**
|
|
387
|
+
* Creates an MCPSource from a server configuration.
|
|
388
|
+
*
|
|
389
|
+
* This is the preferred way to create an MCPSource when you don't have
|
|
390
|
+
* a pre-connected MCP client. The function handles:
|
|
391
|
+
* - Starting the MCP server process (for stdio transport)
|
|
392
|
+
* - Connecting to remote servers (for SSE/WebSocket transport)
|
|
393
|
+
* - Managing the client lifecycle
|
|
394
|
+
*
|
|
395
|
+
* @param config - Server configuration
|
|
396
|
+
* @returns Promise resolving to a configured MCPSource
|
|
397
|
+
*
|
|
398
|
+
* @example stdio transport (local server)
|
|
399
|
+
* ```typescript
|
|
400
|
+
* import { createMCPSource } from '@repo/bigtool-ts';
|
|
401
|
+
*
|
|
402
|
+
* const source = await createMCPSource({
|
|
403
|
+
* name: 'github',
|
|
404
|
+
* transport: 'stdio',
|
|
405
|
+
* command: 'npx',
|
|
406
|
+
* args: ['-y', '@modelcontextprotocol/server-github'],
|
|
407
|
+
* env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
|
|
408
|
+
* });
|
|
409
|
+
*
|
|
410
|
+
* // Use like any ToolSource
|
|
411
|
+
* await catalog.register(source);
|
|
412
|
+
* ```
|
|
413
|
+
*
|
|
414
|
+
* @example SSE transport (remote server)
|
|
415
|
+
* ```typescript
|
|
416
|
+
* const source = await createMCPSource({
|
|
417
|
+
* name: 'remote-tools',
|
|
418
|
+
* transport: 'sse',
|
|
419
|
+
* url: 'https://mcp.example.com/sse',
|
|
420
|
+
* headers: { Authorization: `Bearer ${apiKey}` },
|
|
421
|
+
* });
|
|
422
|
+
* ```
|
|
423
|
+
*
|
|
424
|
+
* @example Multiple servers
|
|
425
|
+
* ```typescript
|
|
426
|
+
* const sources = await Promise.all([
|
|
427
|
+
* createMCPSource({ name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@mcp/server-github'] }),
|
|
428
|
+
* createMCPSource({ name: 'slack', transport: 'stdio', command: 'npx', args: ['-y', '@mcp/server-slack'] }),
|
|
429
|
+
* createMCPSource({ name: 'notion', transport: 'stdio', command: 'npx', args: ['-y', '@mcp/server-notion'] }),
|
|
430
|
+
* ]);
|
|
431
|
+
*
|
|
432
|
+
* for (const source of sources) {
|
|
433
|
+
* await catalog.register(source);
|
|
434
|
+
* }
|
|
435
|
+
* ```
|
|
436
|
+
*/
|
|
437
|
+
export declare function createMCPSource(config: MCPServerConfig): Promise<MCPSource>;
|
|
438
|
+
//# sourceMappingURL=mcp.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/sources/mcp.ts"],"names":[],"mappings":"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"}
|