@withone/mcp 1.0.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 +172 -0
- package/build/client.d.ts +102 -0
- package/build/client.js +362 -0
- package/build/helpers.d.ts +53 -0
- package/build/helpers.js +150 -0
- package/build/index.d.ts +10 -0
- package/build/index.js +281 -0
- package/build/schemas.d.ts +285 -0
- package/build/schemas.js +110 -0
- package/build/server.d.ts +27 -0
- package/build/server.js +215 -0
- package/build/types.d.ts +182 -0
- package/build/types.js +9 -0
- package/package.json +47 -0
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP Tool Schemas
|
|
3
|
+
*
|
|
4
|
+
* This file contains all tool schema definitions for MCP tools using zod.
|
|
5
|
+
* Centralizing schemas here improves maintainability and reusability.
|
|
6
|
+
*
|
|
7
|
+
* @fileoverview Complete tool schema definitions for all MCP tools
|
|
8
|
+
* @author Pica
|
|
9
|
+
*/
|
|
10
|
+
import { z } from 'zod';
|
|
11
|
+
/**
|
|
12
|
+
* Schema for listing Pica integrations (no parameters required)
|
|
13
|
+
*/
|
|
14
|
+
export declare const listPicaIntegrationsInputSchema: {};
|
|
15
|
+
/**
|
|
16
|
+
* Schema for searching platform actions
|
|
17
|
+
*/
|
|
18
|
+
export declare const searchPicaPlatformActionsInputSchema: {
|
|
19
|
+
platform: z.ZodString;
|
|
20
|
+
query: z.ZodString;
|
|
21
|
+
agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Schema for getting action knowledge
|
|
25
|
+
*/
|
|
26
|
+
export declare const getPicaActionKnowledgeInputSchema: {
|
|
27
|
+
actionId: z.ZodString;
|
|
28
|
+
platform: z.ZodString;
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Schema for executing Pica actions
|
|
32
|
+
*/
|
|
33
|
+
export declare const executePicaActionInputSchema: {
|
|
34
|
+
platform: z.ZodString;
|
|
35
|
+
actionId: z.ZodString;
|
|
36
|
+
connectionKey: z.ZodString;
|
|
37
|
+
data: z.ZodOptional<z.ZodAny>;
|
|
38
|
+
pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
39
|
+
queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
|
|
40
|
+
headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
41
|
+
isFormData: z.ZodOptional<z.ZodBoolean>;
|
|
42
|
+
isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* Output schemas for list_pica_integrations tool
|
|
46
|
+
*/
|
|
47
|
+
export declare const listPicaIntegrationsOutputSchema: {
|
|
48
|
+
connections: z.ZodArray<z.ZodObject<{
|
|
49
|
+
platform: z.ZodString;
|
|
50
|
+
key: z.ZodString;
|
|
51
|
+
tags: z.ZodArray<z.ZodString, "many">;
|
|
52
|
+
}, "strip", z.ZodTypeAny, {
|
|
53
|
+
key: string;
|
|
54
|
+
platform: string;
|
|
55
|
+
tags: string[];
|
|
56
|
+
}, {
|
|
57
|
+
key: string;
|
|
58
|
+
platform: string;
|
|
59
|
+
tags: string[];
|
|
60
|
+
}>, "many">;
|
|
61
|
+
availablePlatforms: z.ZodArray<z.ZodObject<{
|
|
62
|
+
platform: z.ZodString;
|
|
63
|
+
name: z.ZodString;
|
|
64
|
+
category: z.ZodString;
|
|
65
|
+
}, "strip", z.ZodTypeAny, {
|
|
66
|
+
platform: string;
|
|
67
|
+
name: string;
|
|
68
|
+
category: string;
|
|
69
|
+
}, {
|
|
70
|
+
platform: string;
|
|
71
|
+
name: string;
|
|
72
|
+
category: string;
|
|
73
|
+
}>, "many">;
|
|
74
|
+
summary: z.ZodObject<{
|
|
75
|
+
connectedCount: z.ZodNumber;
|
|
76
|
+
availableCount: z.ZodNumber;
|
|
77
|
+
}, "strip", z.ZodTypeAny, {
|
|
78
|
+
connectedCount: number;
|
|
79
|
+
availableCount: number;
|
|
80
|
+
}, {
|
|
81
|
+
connectedCount: number;
|
|
82
|
+
availableCount: number;
|
|
83
|
+
}>;
|
|
84
|
+
};
|
|
85
|
+
/**
|
|
86
|
+
* Output schemas for search_pica_platform_actions tool
|
|
87
|
+
*/
|
|
88
|
+
export declare const searchPicaPlatformActionsOutputSchema: {
|
|
89
|
+
actions: z.ZodArray<z.ZodObject<{
|
|
90
|
+
actionId: z.ZodString;
|
|
91
|
+
title: z.ZodString;
|
|
92
|
+
method: z.ZodString;
|
|
93
|
+
path: z.ZodString;
|
|
94
|
+
}, "strip", z.ZodTypeAny, {
|
|
95
|
+
method: string;
|
|
96
|
+
actionId: string;
|
|
97
|
+
path: string;
|
|
98
|
+
title: string;
|
|
99
|
+
}, {
|
|
100
|
+
method: string;
|
|
101
|
+
actionId: string;
|
|
102
|
+
path: string;
|
|
103
|
+
title: string;
|
|
104
|
+
}>, "many">;
|
|
105
|
+
metadata: z.ZodObject<{
|
|
106
|
+
platform: z.ZodString;
|
|
107
|
+
query: z.ZodString;
|
|
108
|
+
count: z.ZodNumber;
|
|
109
|
+
}, "strip", z.ZodTypeAny, {
|
|
110
|
+
query: string;
|
|
111
|
+
platform: string;
|
|
112
|
+
count: number;
|
|
113
|
+
}, {
|
|
114
|
+
query: string;
|
|
115
|
+
platform: string;
|
|
116
|
+
count: number;
|
|
117
|
+
}>;
|
|
118
|
+
};
|
|
119
|
+
/**
|
|
120
|
+
* Tool configuration objects for registerTool
|
|
121
|
+
*/
|
|
122
|
+
export declare const listPicaIntegrationsToolConfig: {
|
|
123
|
+
title: string;
|
|
124
|
+
description: string;
|
|
125
|
+
inputSchema: {};
|
|
126
|
+
outputSchema: {
|
|
127
|
+
connections: z.ZodArray<z.ZodObject<{
|
|
128
|
+
platform: z.ZodString;
|
|
129
|
+
key: z.ZodString;
|
|
130
|
+
tags: z.ZodArray<z.ZodString, "many">;
|
|
131
|
+
}, "strip", z.ZodTypeAny, {
|
|
132
|
+
key: string;
|
|
133
|
+
platform: string;
|
|
134
|
+
tags: string[];
|
|
135
|
+
}, {
|
|
136
|
+
key: string;
|
|
137
|
+
platform: string;
|
|
138
|
+
tags: string[];
|
|
139
|
+
}>, "many">;
|
|
140
|
+
availablePlatforms: z.ZodArray<z.ZodObject<{
|
|
141
|
+
platform: z.ZodString;
|
|
142
|
+
name: z.ZodString;
|
|
143
|
+
category: z.ZodString;
|
|
144
|
+
}, "strip", z.ZodTypeAny, {
|
|
145
|
+
platform: string;
|
|
146
|
+
name: string;
|
|
147
|
+
category: string;
|
|
148
|
+
}, {
|
|
149
|
+
platform: string;
|
|
150
|
+
name: string;
|
|
151
|
+
category: string;
|
|
152
|
+
}>, "many">;
|
|
153
|
+
summary: z.ZodObject<{
|
|
154
|
+
connectedCount: z.ZodNumber;
|
|
155
|
+
availableCount: z.ZodNumber;
|
|
156
|
+
}, "strip", z.ZodTypeAny, {
|
|
157
|
+
connectedCount: number;
|
|
158
|
+
availableCount: number;
|
|
159
|
+
}, {
|
|
160
|
+
connectedCount: number;
|
|
161
|
+
availableCount: number;
|
|
162
|
+
}>;
|
|
163
|
+
};
|
|
164
|
+
};
|
|
165
|
+
export declare const searchPicaPlatformActionsToolConfig: {
|
|
166
|
+
title: string;
|
|
167
|
+
description: string;
|
|
168
|
+
inputSchema: {
|
|
169
|
+
platform: z.ZodString;
|
|
170
|
+
query: z.ZodString;
|
|
171
|
+
agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
|
|
172
|
+
};
|
|
173
|
+
outputSchema: {
|
|
174
|
+
actions: z.ZodArray<z.ZodObject<{
|
|
175
|
+
actionId: z.ZodString;
|
|
176
|
+
title: z.ZodString;
|
|
177
|
+
method: z.ZodString;
|
|
178
|
+
path: z.ZodString;
|
|
179
|
+
}, "strip", z.ZodTypeAny, {
|
|
180
|
+
method: string;
|
|
181
|
+
actionId: string;
|
|
182
|
+
path: string;
|
|
183
|
+
title: string;
|
|
184
|
+
}, {
|
|
185
|
+
method: string;
|
|
186
|
+
actionId: string;
|
|
187
|
+
path: string;
|
|
188
|
+
title: string;
|
|
189
|
+
}>, "many">;
|
|
190
|
+
metadata: z.ZodObject<{
|
|
191
|
+
platform: z.ZodString;
|
|
192
|
+
query: z.ZodString;
|
|
193
|
+
count: z.ZodNumber;
|
|
194
|
+
}, "strip", z.ZodTypeAny, {
|
|
195
|
+
query: string;
|
|
196
|
+
platform: string;
|
|
197
|
+
count: number;
|
|
198
|
+
}, {
|
|
199
|
+
query: string;
|
|
200
|
+
platform: string;
|
|
201
|
+
count: number;
|
|
202
|
+
}>;
|
|
203
|
+
};
|
|
204
|
+
};
|
|
205
|
+
export declare const getPicaActionKnowledgeToolConfig: {
|
|
206
|
+
title: string;
|
|
207
|
+
description: string;
|
|
208
|
+
inputSchema: {
|
|
209
|
+
actionId: z.ZodString;
|
|
210
|
+
platform: z.ZodString;
|
|
211
|
+
};
|
|
212
|
+
};
|
|
213
|
+
export declare const executePicaActionToolConfig: {
|
|
214
|
+
title: string;
|
|
215
|
+
description: string;
|
|
216
|
+
inputSchema: {
|
|
217
|
+
platform: z.ZodString;
|
|
218
|
+
actionId: z.ZodString;
|
|
219
|
+
connectionKey: z.ZodString;
|
|
220
|
+
data: z.ZodOptional<z.ZodAny>;
|
|
221
|
+
pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
222
|
+
queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
|
|
223
|
+
headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
224
|
+
isFormData: z.ZodOptional<z.ZodBoolean>;
|
|
225
|
+
isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
|
|
226
|
+
};
|
|
227
|
+
};
|
|
228
|
+
/**
|
|
229
|
+
* Zod object schemas for type inference (for internal use)
|
|
230
|
+
*/
|
|
231
|
+
export declare const listPicaIntegrationsZodSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
|
|
232
|
+
export declare const searchPicaPlatformActionsZodSchema: z.ZodObject<{
|
|
233
|
+
platform: z.ZodString;
|
|
234
|
+
query: z.ZodString;
|
|
235
|
+
agentType: z.ZodOptional<z.ZodEnum<["execute", "knowledge"]>>;
|
|
236
|
+
}, "strip", z.ZodTypeAny, {
|
|
237
|
+
query: string;
|
|
238
|
+
platform: string;
|
|
239
|
+
agentType?: "execute" | "knowledge" | undefined;
|
|
240
|
+
}, {
|
|
241
|
+
query: string;
|
|
242
|
+
platform: string;
|
|
243
|
+
agentType?: "execute" | "knowledge" | undefined;
|
|
244
|
+
}>;
|
|
245
|
+
export declare const getPicaActionKnowledgeZodSchema: z.ZodObject<{
|
|
246
|
+
actionId: z.ZodString;
|
|
247
|
+
platform: z.ZodString;
|
|
248
|
+
}, "strip", z.ZodTypeAny, {
|
|
249
|
+
actionId: string;
|
|
250
|
+
platform: string;
|
|
251
|
+
}, {
|
|
252
|
+
actionId: string;
|
|
253
|
+
platform: string;
|
|
254
|
+
}>;
|
|
255
|
+
export declare const executePicaActionZodSchema: z.ZodObject<{
|
|
256
|
+
platform: z.ZodString;
|
|
257
|
+
actionId: z.ZodString;
|
|
258
|
+
connectionKey: z.ZodString;
|
|
259
|
+
data: z.ZodOptional<z.ZodAny>;
|
|
260
|
+
pathVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
261
|
+
queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
|
|
262
|
+
headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
263
|
+
isFormData: z.ZodOptional<z.ZodBoolean>;
|
|
264
|
+
isFormUrlEncoded: z.ZodOptional<z.ZodBoolean>;
|
|
265
|
+
}, "strip", z.ZodTypeAny, {
|
|
266
|
+
actionId: string;
|
|
267
|
+
connectionKey: string;
|
|
268
|
+
platform: string;
|
|
269
|
+
headers?: Record<string, string> | undefined;
|
|
270
|
+
data?: any;
|
|
271
|
+
pathVariables?: Record<string, string | number | boolean> | undefined;
|
|
272
|
+
queryParams?: Record<string, any> | undefined;
|
|
273
|
+
isFormData?: boolean | undefined;
|
|
274
|
+
isFormUrlEncoded?: boolean | undefined;
|
|
275
|
+
}, {
|
|
276
|
+
actionId: string;
|
|
277
|
+
connectionKey: string;
|
|
278
|
+
platform: string;
|
|
279
|
+
headers?: Record<string, string> | undefined;
|
|
280
|
+
data?: any;
|
|
281
|
+
pathVariables?: Record<string, string | number | boolean> | undefined;
|
|
282
|
+
queryParams?: Record<string, any> | undefined;
|
|
283
|
+
isFormData?: boolean | undefined;
|
|
284
|
+
isFormUrlEncoded?: boolean | undefined;
|
|
285
|
+
}>;
|
package/build/schemas.js
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP Tool Schemas
|
|
3
|
+
*
|
|
4
|
+
* This file contains all tool schema definitions for MCP tools using zod.
|
|
5
|
+
* Centralizing schemas here improves maintainability and reusability.
|
|
6
|
+
*
|
|
7
|
+
* @fileoverview Complete tool schema definitions for all MCP tools
|
|
8
|
+
* @author One
|
|
9
|
+
*/
|
|
10
|
+
import { z } from 'zod';
|
|
11
|
+
/**
|
|
12
|
+
* Schema for listing One integrations (no parameters required)
|
|
13
|
+
*/
|
|
14
|
+
export const listOneIntegrationsInputSchema = {};
|
|
15
|
+
/**
|
|
16
|
+
* Schema for searching platform actions
|
|
17
|
+
*/
|
|
18
|
+
export const searchOnePlatformActionsInputSchema = {
|
|
19
|
+
platform: z.string().describe("The platform name to search actions for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section."),
|
|
20
|
+
query: z.string().describe("The search query to find relevant actions (e.g., 'search contacts', 'create customer', 'send email'). Be specific about what you want to do."),
|
|
21
|
+
agentType: z.enum(["execute", "knowledge"]).optional().describe("The type of agent context: 'execute' if the user wants to execute an action, 'knowledge' if they want to get information or write code. Defaults to 'knowledge' if not specified.")
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Schema for getting action knowledge
|
|
25
|
+
*/
|
|
26
|
+
export const getOneActionKnowledgeInputSchema = {
|
|
27
|
+
actionId: z.string().describe("The action ID to get knowledge for (from the actions list returned by search_one_platform_actions). REQUIRED: This tool must be called before execute_one_action to load the action's documentation into context."),
|
|
28
|
+
platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section.")
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Schema for executing One actions
|
|
32
|
+
*/
|
|
33
|
+
export const executeOneActionInputSchema = {
|
|
34
|
+
platform: z.string().describe("Platform name"),
|
|
35
|
+
actionId: z.string().describe("Action ID from search_one_platform_actions"),
|
|
36
|
+
connectionKey: z.string().describe("Key of the connection to use"),
|
|
37
|
+
data: z.any().optional().describe("Request data (for POST, PUT, etc.)"),
|
|
38
|
+
pathVariables: z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Variables to replace in the path"),
|
|
39
|
+
queryParams: z.record(z.any()).optional().describe("Query parameters"),
|
|
40
|
+
headers: z.record(z.string()).optional().describe("Additional headers"),
|
|
41
|
+
isFormData: z.boolean().optional().describe("Whether to send data as multipart/form-data"),
|
|
42
|
+
isFormUrlEncoded: z.boolean().optional().describe("Whether to send data as application/x-www-form-urlencoded")
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* Output schemas for list_one_integrations tool
|
|
46
|
+
*/
|
|
47
|
+
export const listOneIntegrationsOutputSchema = {
|
|
48
|
+
connections: z.array(z.object({
|
|
49
|
+
platform: z.string(),
|
|
50
|
+
key: z.string(),
|
|
51
|
+
tags: z.array(z.string())
|
|
52
|
+
})).describe("Array of user's active connections"),
|
|
53
|
+
availablePlatforms: z.array(z.object({
|
|
54
|
+
platform: z.string(),
|
|
55
|
+
name: z.string(),
|
|
56
|
+
category: z.string()
|
|
57
|
+
})).describe("Array of available platforms that can be connected"),
|
|
58
|
+
summary: z.object({
|
|
59
|
+
connectedCount: z.number(),
|
|
60
|
+
availableCount: z.number()
|
|
61
|
+
}).describe("Summary statistics of connections and available platforms")
|
|
62
|
+
};
|
|
63
|
+
/**
|
|
64
|
+
* Output schemas for search_one_platform_actions tool
|
|
65
|
+
*/
|
|
66
|
+
export const searchOnePlatformActionsOutputSchema = {
|
|
67
|
+
actions: z.array(z.object({
|
|
68
|
+
actionId: z.string().describe("Unique identifier for the action"),
|
|
69
|
+
title: z.string().describe("Human-readable action name"),
|
|
70
|
+
method: z.string().describe("HTTP method (GET, POST, etc.)"),
|
|
71
|
+
path: z.string().describe("API endpoint path")
|
|
72
|
+
})).describe("Array of matching actions (max 5)"),
|
|
73
|
+
metadata: z.object({
|
|
74
|
+
platform: z.string().describe("Platform that was searched"),
|
|
75
|
+
query: z.string().describe("Search query used"),
|
|
76
|
+
count: z.number().describe("Number of results returned")
|
|
77
|
+
}).describe("Metadata about the search results")
|
|
78
|
+
};
|
|
79
|
+
/**
|
|
80
|
+
* Tool configuration objects for registerTool
|
|
81
|
+
*/
|
|
82
|
+
export const listOneIntegrationsToolConfig = {
|
|
83
|
+
title: "List One Integrations",
|
|
84
|
+
description: "List all available One integrations and platforms. ALWAYS call this tool first in any workflow to discover what platforms and connections are available. This returns the connections that the user has and all available One platforms in kebab-case format (e.g., 'ship-station', 'shopify') which you'll need for subsequent tool calls.",
|
|
85
|
+
inputSchema: listOneIntegrationsInputSchema,
|
|
86
|
+
outputSchema: listOneIntegrationsOutputSchema
|
|
87
|
+
};
|
|
88
|
+
export const searchOnePlatformActionsToolConfig = {
|
|
89
|
+
title: "Search Platform Actions",
|
|
90
|
+
description: "Search for relevant actions on a specific platform using a query. Call this after list_one_integrations to find actions that match your intent. Returns the top 5 most relevant actions based on your search query. Use the exact kebab-case platform name from the integrations list.",
|
|
91
|
+
inputSchema: searchOnePlatformActionsInputSchema,
|
|
92
|
+
outputSchema: searchOnePlatformActionsOutputSchema
|
|
93
|
+
};
|
|
94
|
+
export const getOneActionKnowledgeToolConfig = {
|
|
95
|
+
title: "Get Action Knowledge",
|
|
96
|
+
description: "Get comprehensive documentation for a specific action including parameters, requirements, and usage examples. MANDATORY: You MUST call this tool before execute_one_action to understand the action's requirements, parameter structure, caveats, and proper usage. This loads the action documentation into context and is required for successful execution.",
|
|
97
|
+
inputSchema: getOneActionKnowledgeInputSchema
|
|
98
|
+
};
|
|
99
|
+
export const executeOneActionToolConfig = {
|
|
100
|
+
title: "Execute One Action",
|
|
101
|
+
description: "Execute a One action to perform actual operations on third-party platforms. CRITICAL: Only call this when the user's intent is to EXECUTE an action (e.g., 'read my last Gmail email', 'fetch 5 contacts from HubSpot', 'create a task in Asana'). DO NOT call this when the user wants to BUILD or CREATE code/forms/applications - in those cases, stop after get_one_action_knowledge and provide implementation guidance instead. REQUIRED WORKFLOW: Must call get_one_action_knowledge first. If uncertain about execution intent or parameters, ask for confirmation before proceeding.",
|
|
102
|
+
inputSchema: executeOneActionInputSchema
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* Zod object schemas for type inference (for internal use)
|
|
106
|
+
*/
|
|
107
|
+
export const listOneIntegrationsZodSchema = z.object(listOneIntegrationsInputSchema);
|
|
108
|
+
export const searchOnePlatformActionsZodSchema = z.object(searchOnePlatformActionsInputSchema);
|
|
109
|
+
export const getOneActionKnowledgeZodSchema = z.object(getOneActionKnowledgeInputSchema);
|
|
110
|
+
export const executeOneActionZodSchema = z.object(executeOneActionInputSchema);
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pica MCP Server Factory
|
|
3
|
+
*
|
|
4
|
+
* Exports a factory function that registers all Pica tools on a provided McpServer instance.
|
|
5
|
+
*
|
|
6
|
+
* @fileoverview createPicaServer() factory for reuse across stdio and HTTP transports
|
|
7
|
+
* @author Pica
|
|
8
|
+
*/
|
|
9
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
10
|
+
import { PermissionLevel } from './types.js';
|
|
11
|
+
export interface CreatePicaServerOptions {
|
|
12
|
+
secret: string;
|
|
13
|
+
baseUrl?: string;
|
|
14
|
+
identity?: string;
|
|
15
|
+
identityType?: 'user' | 'team' | 'organization' | 'project';
|
|
16
|
+
permissions?: PermissionLevel;
|
|
17
|
+
connectionKeys?: string[];
|
|
18
|
+
actionIds?: string[];
|
|
19
|
+
knowledgeAgent?: boolean;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Registers all Pica MCP tools on the provided server instance.
|
|
23
|
+
*
|
|
24
|
+
* @param server - An McpServer instance to register tools on
|
|
25
|
+
* @param options - Configuration options (secret is required, rest have sensible defaults)
|
|
26
|
+
*/
|
|
27
|
+
export declare function createPicaServer(server: McpServer, options: CreatePicaServerOptions): Promise<void>;
|
package/build/server.js
ADDED
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pica MCP Server Factory
|
|
3
|
+
*
|
|
4
|
+
* Exports a factory function that registers all Pica tools on a provided McpServer instance.
|
|
5
|
+
*
|
|
6
|
+
* @fileoverview createPicaServer() factory for reuse across stdio and HTTP transports
|
|
7
|
+
* @author Pica
|
|
8
|
+
*/
|
|
9
|
+
import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
|
|
10
|
+
import { PicaClient } from './client.js';
|
|
11
|
+
import { buildActionKnowledgeWithGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, } from './helpers.js';
|
|
12
|
+
import { listPicaIntegrationsToolConfig, searchPicaPlatformActionsToolConfig, getPicaActionKnowledgeToolConfig, executePicaActionToolConfig, } from './schemas.js';
|
|
13
|
+
/**
|
|
14
|
+
* Registers all Pica MCP tools on the provided server instance.
|
|
15
|
+
*
|
|
16
|
+
* @param server - An McpServer instance to register tools on
|
|
17
|
+
* @param options - Configuration options (secret is required, rest have sensible defaults)
|
|
18
|
+
*/
|
|
19
|
+
export async function createPicaServer(server, options) {
|
|
20
|
+
const { secret, baseUrl, identity, identityType, permissions = 'admin', connectionKeys = ['*'], actionIds = ['*'], knowledgeAgent = false, } = options;
|
|
21
|
+
const picaClient = new PicaClient({
|
|
22
|
+
secret,
|
|
23
|
+
baseUrl,
|
|
24
|
+
identity,
|
|
25
|
+
identityType,
|
|
26
|
+
connectionKeys,
|
|
27
|
+
});
|
|
28
|
+
let picaInitialized = false;
|
|
29
|
+
let initializationPromise = null;
|
|
30
|
+
const initializePica = async () => {
|
|
31
|
+
if (picaInitialized) {
|
|
32
|
+
return;
|
|
33
|
+
}
|
|
34
|
+
if (initializationPromise) {
|
|
35
|
+
return initializationPromise;
|
|
36
|
+
}
|
|
37
|
+
initializationPromise = (async () => {
|
|
38
|
+
try {
|
|
39
|
+
await picaClient.initialize();
|
|
40
|
+
picaInitialized = true;
|
|
41
|
+
}
|
|
42
|
+
catch (error) {
|
|
43
|
+
console.error("Failed to initialize Pica client:", error);
|
|
44
|
+
initializationPromise = null;
|
|
45
|
+
throw error;
|
|
46
|
+
}
|
|
47
|
+
})();
|
|
48
|
+
return initializationPromise;
|
|
49
|
+
};
|
|
50
|
+
// --- Tool handlers ---
|
|
51
|
+
async function handleGetIntegrations(_args) {
|
|
52
|
+
try {
|
|
53
|
+
const connectedIntegrations = picaClient.getUserConnections();
|
|
54
|
+
const availableIntegrations = picaClient.getAvailableConnectors();
|
|
55
|
+
const activeConnections = connectedIntegrations.filter(conn => conn.active);
|
|
56
|
+
let activePlatforms = availableIntegrations.filter(def => def.active && !def.deprecated);
|
|
57
|
+
if (!connectionKeys.includes("*")) {
|
|
58
|
+
const connectedPlatforms = new Set(activeConnections.map(conn => conn.platform));
|
|
59
|
+
activePlatforms = activePlatforms.filter(def => connectedPlatforms.has(def.platform));
|
|
60
|
+
}
|
|
61
|
+
const structuredResponse = {
|
|
62
|
+
connections: activeConnections.map(conn => ({
|
|
63
|
+
platform: conn.platform,
|
|
64
|
+
key: conn.key,
|
|
65
|
+
tags: conn.tags ?? [],
|
|
66
|
+
})),
|
|
67
|
+
availablePlatforms: activePlatforms.map(def => ({
|
|
68
|
+
platform: def.platform,
|
|
69
|
+
name: def.name,
|
|
70
|
+
category: def.category,
|
|
71
|
+
})),
|
|
72
|
+
summary: {
|
|
73
|
+
connectedCount: activeConnections.length,
|
|
74
|
+
availableCount: activePlatforms.length,
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
return {
|
|
78
|
+
content: [
|
|
79
|
+
{
|
|
80
|
+
type: "text",
|
|
81
|
+
text: JSON.stringify(structuredResponse, null, 2),
|
|
82
|
+
},
|
|
83
|
+
],
|
|
84
|
+
structuredContent: structuredResponse,
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
catch (error) {
|
|
88
|
+
throw new McpError(ErrorCode.InternalError, `Failed to retrieve integrations: ${error instanceof Error ? error.message : 'Unknown error'}`);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
async function handleSearchPlatformActions(args) {
|
|
92
|
+
try {
|
|
93
|
+
const agentType = knowledgeAgent ? "knowledge" : args.agentType;
|
|
94
|
+
let actions = await picaClient.searchAvailableActions(args.platform, args.query, agentType);
|
|
95
|
+
actions = filterByPermissions(actions, permissions);
|
|
96
|
+
actions = actions.filter(a => isActionAllowed(a.systemId, actionIds));
|
|
97
|
+
const cleanedActions = actions.map(action => ({
|
|
98
|
+
actionId: action.systemId,
|
|
99
|
+
title: action.title,
|
|
100
|
+
method: action.method,
|
|
101
|
+
path: action.path,
|
|
102
|
+
}));
|
|
103
|
+
if (cleanedActions.length === 0) {
|
|
104
|
+
const suggestionsText = `No actions found for platform '${args.platform}' matching query '${args.query}'.
|
|
105
|
+
|
|
106
|
+
SUGGESTIONS:
|
|
107
|
+
- Try a more general query (e.g., 'list', 'get', 'search', 'create')
|
|
108
|
+
- Verify the platform name is correct
|
|
109
|
+
- Check that actions exist for this platform using list_pica_integrations
|
|
110
|
+
|
|
111
|
+
EXAMPLES OF GOOD QUERIES:
|
|
112
|
+
- "search contacts"
|
|
113
|
+
- "send email"
|
|
114
|
+
- "create customer"
|
|
115
|
+
- "list orders"`;
|
|
116
|
+
return {
|
|
117
|
+
content: [
|
|
118
|
+
{
|
|
119
|
+
type: "text",
|
|
120
|
+
text: suggestionsText,
|
|
121
|
+
},
|
|
122
|
+
],
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
const structuredResponse = {
|
|
126
|
+
actions: cleanedActions,
|
|
127
|
+
metadata: {
|
|
128
|
+
platform: args.platform,
|
|
129
|
+
query: args.query,
|
|
130
|
+
count: cleanedActions.length,
|
|
131
|
+
},
|
|
132
|
+
};
|
|
133
|
+
const responseText = `Found ${cleanedActions.length} action(s) for platform '${args.platform}' matching query '${args.query}':
|
|
134
|
+
|
|
135
|
+
${JSON.stringify(structuredResponse, null, 2)}
|
|
136
|
+
|
|
137
|
+
NEXT STEP: Use get_pica_action_knowledge with an actionId to get detailed documentation before building requests or executing actions.`;
|
|
138
|
+
return {
|
|
139
|
+
content: [
|
|
140
|
+
{
|
|
141
|
+
type: "text",
|
|
142
|
+
text: responseText,
|
|
143
|
+
},
|
|
144
|
+
],
|
|
145
|
+
structuredContent: structuredResponse,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
catch (error) {
|
|
149
|
+
throw new McpError(ErrorCode.InternalError, `Failed to search platform actions: ${error instanceof Error ? error.message : 'Unknown error'}`);
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
async function handleGetActionKnowledge(args) {
|
|
153
|
+
try {
|
|
154
|
+
const actionId = args.actionId;
|
|
155
|
+
if (!isActionAllowed(actionId, actionIds)) {
|
|
156
|
+
throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is not in the allowed action list`);
|
|
157
|
+
}
|
|
158
|
+
const { knowledge, method } = await picaClient.getActionKnowledge(actionId);
|
|
159
|
+
const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(knowledge, method, picaClient.getBaseUrl(), args.platform, actionId);
|
|
160
|
+
return {
|
|
161
|
+
content: [
|
|
162
|
+
{
|
|
163
|
+
type: "text",
|
|
164
|
+
text: knowledgeWithGuidance,
|
|
165
|
+
},
|
|
166
|
+
],
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
catch (error) {
|
|
170
|
+
throw new McpError(ErrorCode.InternalError, `Failed to retrieve action knowledge: ${error instanceof Error ? error.message : 'Unknown error'}`);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
async function handleExecutePicaAction(args) {
|
|
174
|
+
try {
|
|
175
|
+
if (!isActionAllowed(args.actionId, actionIds)) {
|
|
176
|
+
throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is not in the allowed action list`);
|
|
177
|
+
}
|
|
178
|
+
const actionDetails = await picaClient.getActionDetails(args.actionId);
|
|
179
|
+
if (!isMethodAllowed(actionDetails.method, permissions)) {
|
|
180
|
+
throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`);
|
|
181
|
+
}
|
|
182
|
+
const result = await picaClient.executePassthroughRequest(args, actionDetails);
|
|
183
|
+
return {
|
|
184
|
+
content: [
|
|
185
|
+
{
|
|
186
|
+
type: "text",
|
|
187
|
+
text: JSON.stringify(result, null, 2),
|
|
188
|
+
},
|
|
189
|
+
],
|
|
190
|
+
};
|
|
191
|
+
}
|
|
192
|
+
catch (error) {
|
|
193
|
+
throw new McpError(ErrorCode.InternalError, `Failed to execute Pica action: ${error instanceof Error ? error.message : 'Unknown error'}`);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
// --- Register tools ---
|
|
197
|
+
server.registerTool("list_pica_integrations", listPicaIntegrationsToolConfig, async (args) => {
|
|
198
|
+
await initializePica();
|
|
199
|
+
return await handleGetIntegrations(args);
|
|
200
|
+
});
|
|
201
|
+
server.registerTool("search_pica_platform_actions", searchPicaPlatformActionsToolConfig, async (args) => {
|
|
202
|
+
await initializePica();
|
|
203
|
+
return await handleSearchPlatformActions(args);
|
|
204
|
+
});
|
|
205
|
+
server.registerTool("get_pica_action_knowledge", getPicaActionKnowledgeToolConfig, async (args) => {
|
|
206
|
+
await initializePica();
|
|
207
|
+
return await handleGetActionKnowledge(args);
|
|
208
|
+
});
|
|
209
|
+
if (!knowledgeAgent) {
|
|
210
|
+
server.registerTool("execute_pica_action", executePicaActionToolConfig, async (args) => {
|
|
211
|
+
await initializePica();
|
|
212
|
+
return await handleExecutePicaAction(args);
|
|
213
|
+
});
|
|
214
|
+
}
|
|
215
|
+
}
|