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.
Files changed (116) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/LICENSE +21 -0
  3. package/README.md +641 -0
  4. package/dist/adapters/agent-protocol.d.ts +149 -0
  5. package/dist/adapters/agent-protocol.d.ts.map +1 -0
  6. package/dist/adapters/agent-protocol.js +133 -0
  7. package/dist/adapters/agent-protocol.js.map +1 -0
  8. package/dist/adapters/index.d.ts +39 -0
  9. package/dist/adapters/index.d.ts.map +1 -0
  10. package/dist/adapters/index.js +42 -0
  11. package/dist/adapters/index.js.map +1 -0
  12. package/dist/adapters/inngest.d.ts +234 -0
  13. package/dist/adapters/inngest.d.ts.map +1 -0
  14. package/dist/adapters/inngest.js +276 -0
  15. package/dist/adapters/inngest.js.map +1 -0
  16. package/dist/adapters/mastra.d.ts +201 -0
  17. package/dist/adapters/mastra.d.ts.map +1 -0
  18. package/dist/adapters/mastra.js +250 -0
  19. package/dist/adapters/mastra.js.map +1 -0
  20. package/dist/adapters/types.d.ts +42 -0
  21. package/dist/adapters/types.d.ts.map +1 -0
  22. package/dist/adapters/types.js +6 -0
  23. package/dist/adapters/types.js.map +1 -0
  24. package/dist/adapters/vercel-ai.d.ts +176 -0
  25. package/dist/adapters/vercel-ai.d.ts.map +1 -0
  26. package/dist/adapters/vercel-ai.js +244 -0
  27. package/dist/adapters/vercel-ai.js.map +1 -0
  28. package/dist/catalog/index.d.ts +177 -0
  29. package/dist/catalog/index.d.ts.map +1 -0
  30. package/dist/catalog/index.js +244 -0
  31. package/dist/catalog/index.js.map +1 -0
  32. package/dist/graph/agent.d.ts +214 -0
  33. package/dist/graph/agent.d.ts.map +1 -0
  34. package/dist/graph/agent.js +196 -0
  35. package/dist/graph/agent.js.map +1 -0
  36. package/dist/graph/index.d.ts +5 -0
  37. package/dist/graph/index.d.ts.map +1 -0
  38. package/dist/graph/index.js +4 -0
  39. package/dist/graph/index.js.map +1 -0
  40. package/dist/graph/nodes.d.ts +100 -0
  41. package/dist/graph/nodes.d.ts.map +1 -0
  42. package/dist/graph/nodes.js +190 -0
  43. package/dist/graph/nodes.js.map +1 -0
  44. package/dist/graph/search-tool.d.ts +34 -0
  45. package/dist/graph/search-tool.d.ts.map +1 -0
  46. package/dist/graph/search-tool.js +54 -0
  47. package/dist/graph/search-tool.js.map +1 -0
  48. package/dist/graph/state.d.ts +26 -0
  49. package/dist/graph/state.d.ts.map +1 -0
  50. package/dist/graph/state.js +29 -0
  51. package/dist/graph/state.js.map +1 -0
  52. package/dist/index.d.ts +69 -0
  53. package/dist/index.d.ts.map +1 -0
  54. package/dist/index.js +85 -0
  55. package/dist/index.js.map +1 -0
  56. package/dist/loader/index.d.ts +172 -0
  57. package/dist/loader/index.d.ts.map +1 -0
  58. package/dist/loader/index.js +179 -0
  59. package/dist/loader/index.js.map +1 -0
  60. package/dist/loader/loader.d.ts +114 -0
  61. package/dist/loader/loader.d.ts.map +1 -0
  62. package/dist/loader/loader.js +185 -0
  63. package/dist/loader/loader.js.map +1 -0
  64. package/dist/search/cache.d.ts +76 -0
  65. package/dist/search/cache.d.ts.map +1 -0
  66. package/dist/search/cache.js +135 -0
  67. package/dist/search/cache.js.map +1 -0
  68. package/dist/search/index.d.ts +63 -0
  69. package/dist/search/index.d.ts.map +1 -0
  70. package/dist/search/index.js +122 -0
  71. package/dist/search/index.js.map +1 -0
  72. package/dist/search/normalize.d.ts +104 -0
  73. package/dist/search/normalize.d.ts.map +1 -0
  74. package/dist/search/normalize.js +211 -0
  75. package/dist/search/normalize.js.map +1 -0
  76. package/dist/search/orama.d.ts +256 -0
  77. package/dist/search/orama.d.ts.map +1 -0
  78. package/dist/search/orama.js +511 -0
  79. package/dist/search/orama.js.map +1 -0
  80. package/dist/search/types.d.ts +96 -0
  81. package/dist/search/types.d.ts.map +1 -0
  82. package/dist/search/types.js +8 -0
  83. package/dist/search/types.js.map +1 -0
  84. package/dist/sources/dynamic.d.ts +200 -0
  85. package/dist/sources/dynamic.d.ts.map +1 -0
  86. package/dist/sources/dynamic.js +194 -0
  87. package/dist/sources/dynamic.js.map +1 -0
  88. package/dist/sources/index.d.ts +11 -0
  89. package/dist/sources/index.d.ts.map +1 -0
  90. package/dist/sources/index.js +14 -0
  91. package/dist/sources/index.js.map +1 -0
  92. package/dist/sources/local.d.ts +128 -0
  93. package/dist/sources/local.d.ts.map +1 -0
  94. package/dist/sources/local.js +155 -0
  95. package/dist/sources/local.js.map +1 -0
  96. package/dist/sources/mcp.d.ts +438 -0
  97. package/dist/sources/mcp.d.ts.map +1 -0
  98. package/dist/sources/mcp.js +438 -0
  99. package/dist/sources/mcp.js.map +1 -0
  100. package/dist/sources/types.d.ts +16 -0
  101. package/dist/sources/types.d.ts.map +1 -0
  102. package/dist/sources/types.js +7 -0
  103. package/dist/sources/types.js.map +1 -0
  104. package/dist/sources/with-metadata.d.ts +7 -0
  105. package/dist/sources/with-metadata.d.ts.map +1 -0
  106. package/dist/sources/with-metadata.js +7 -0
  107. package/dist/sources/with-metadata.js.map +1 -0
  108. package/dist/types/index.d.ts +7 -0
  109. package/dist/types/index.d.ts.map +1 -0
  110. package/dist/types/index.js +8 -0
  111. package/dist/types/index.js.map +1 -0
  112. package/dist/types.d.ts +700 -0
  113. package/dist/types.d.ts.map +1 -0
  114. package/dist/types.js +97 -0
  115. package/dist/types.js.map +1 -0
  116. 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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"}