@forumviriumhelsinki/podio-mcp 2.3.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 +491 -0
- package/build/__tests__/integration/setup.integration.d.ts +104 -0
- package/build/__tests__/integration/setup.integration.d.ts.map +1 -0
- package/build/__tests__/integration/setup.integration.js +233 -0
- package/build/__tests__/integration/setup.integration.js.map +1 -0
- package/build/__tests__/mock-data/items-mock-data.d.ts +168 -0
- package/build/__tests__/mock-data/items-mock-data.d.ts.map +1 -0
- package/build/__tests__/mock-data/items-mock-data.js +370 -0
- package/build/__tests__/mock-data/items-mock-data.js.map +1 -0
- package/build/__tests__/mock-data/notification-mock-data.d.ts +55 -0
- package/build/__tests__/mock-data/notification-mock-data.d.ts.map +1 -0
- package/build/__tests__/mock-data/notification-mock-data.js +190 -0
- package/build/__tests__/mock-data/notification-mock-data.js.map +1 -0
- package/build/__tests__/mock-data/project-epic-mock-data.d.ts +45 -0
- package/build/__tests__/mock-data/project-epic-mock-data.d.ts.map +1 -0
- package/build/__tests__/mock-data/project-epic-mock-data.js +85 -0
- package/build/__tests__/mock-data/project-epic-mock-data.js.map +1 -0
- package/build/__tests__/mock-data/tasks-mock-data.d.ts +27 -0
- package/build/__tests__/mock-data/tasks-mock-data.d.ts.map +1 -0
- package/build/__tests__/mock-data/tasks-mock-data.js +104 -0
- package/build/__tests__/mock-data/tasks-mock-data.js.map +1 -0
- package/build/__tests__/mock-data/utility-mock-data.d.ts +19 -0
- package/build/__tests__/mock-data/utility-mock-data.d.ts.map +1 -0
- package/build/__tests__/mock-data/utility-mock-data.js +165 -0
- package/build/__tests__/mock-data/utility-mock-data.js.map +1 -0
- package/build/__tests__/setup.d.ts +8 -0
- package/build/__tests__/setup.d.ts.map +1 -0
- package/build/__tests__/setup.js +31 -0
- package/build/__tests__/setup.js.map +1 -0
- package/build/__tests__/utils/test-helpers.d.ts +110 -0
- package/build/__tests__/utils/test-helpers.d.ts.map +1 -0
- package/build/__tests__/utils/test-helpers.js +222 -0
- package/build/__tests__/utils/test-helpers.js.map +1 -0
- package/build/api/podio-api-client.d.ts +364 -0
- package/build/api/podio-api-client.d.ts.map +1 -0
- package/build/api/podio-api-client.js +696 -0
- package/build/api/podio-api-client.js.map +1 -0
- package/build/cache/app-cache.d.ts +77 -0
- package/build/cache/app-cache.d.ts.map +1 -0
- package/build/cache/app-cache.js +230 -0
- package/build/cache/app-cache.js.map +1 -0
- package/build/cache/base-cache-manager.d.ts +149 -0
- package/build/cache/base-cache-manager.d.ts.map +1 -0
- package/build/cache/base-cache-manager.js +312 -0
- package/build/cache/base-cache-manager.js.map +1 -0
- package/build/cache/cache-manager.d.ts +230 -0
- package/build/cache/cache-manager.d.ts.map +1 -0
- package/build/cache/cache-manager.js +362 -0
- package/build/cache/cache-manager.js.map +1 -0
- package/build/cache/cache-test.d.ts +9 -0
- package/build/cache/cache-test.d.ts.map +1 -0
- package/build/cache/cache-test.js +169 -0
- package/build/cache/cache-test.js.map +1 -0
- package/build/cache/index.d.ts +18 -0
- package/build/cache/index.d.ts.map +1 -0
- package/build/cache/index.js +20 -0
- package/build/cache/index.js.map +1 -0
- package/build/cache/migration-helper.d.ts +44 -0
- package/build/cache/migration-helper.d.ts.map +1 -0
- package/build/cache/migration-helper.js +235 -0
- package/build/cache/migration-helper.js.map +1 -0
- package/build/cache/project-epic-cache.d.ts +108 -0
- package/build/cache/project-epic-cache.d.ts.map +1 -0
- package/build/cache/project-epic-cache.js +278 -0
- package/build/cache/project-epic-cache.js.map +1 -0
- package/build/cache/space-members-cache.d.ts +99 -0
- package/build/cache/space-members-cache.d.ts.map +1 -0
- package/build/cache/space-members-cache.js +305 -0
- package/build/cache/space-members-cache.js.map +1 -0
- package/build/cache/storage-adapters.d.ts +100 -0
- package/build/cache/storage-adapters.d.ts.map +1 -0
- package/build/cache/storage-adapters.js +297 -0
- package/build/cache/storage-adapters.js.map +1 -0
- package/build/errors/api-errors.d.ts +52 -0
- package/build/errors/api-errors.d.ts.map +1 -0
- package/build/errors/api-errors.js +86 -0
- package/build/errors/api-errors.js.map +1 -0
- package/build/errors/auth-errors.d.ts +67 -0
- package/build/errors/auth-errors.d.ts.map +1 -0
- package/build/errors/auth-errors.js +114 -0
- package/build/errors/auth-errors.js.map +1 -0
- package/build/errors/base.d.ts +102 -0
- package/build/errors/base.d.ts.map +1 -0
- package/build/errors/base.js +131 -0
- package/build/errors/base.js.map +1 -0
- package/build/errors/cache-errors.d.ts +53 -0
- package/build/errors/cache-errors.d.ts.map +1 -0
- package/build/errors/cache-errors.js +83 -0
- package/build/errors/cache-errors.js.map +1 -0
- package/build/errors/config-errors.d.ts +58 -0
- package/build/errors/config-errors.d.ts.map +1 -0
- package/build/errors/config-errors.js +96 -0
- package/build/errors/config-errors.js.map +1 -0
- package/build/errors/index.d.ts +101 -0
- package/build/errors/index.d.ts.map +1 -0
- package/build/errors/index.js +135 -0
- package/build/errors/index.js.map +1 -0
- package/build/errors/structure-errors.d.ts +89 -0
- package/build/errors/structure-errors.d.ts.map +1 -0
- package/build/errors/structure-errors.js +182 -0
- package/build/errors/structure-errors.js.map +1 -0
- package/build/errors/validation-errors.d.ts +81 -0
- package/build/errors/validation-errors.d.ts.map +1 -0
- package/build/errors/validation-errors.js +169 -0
- package/build/errors/validation-errors.js.map +1 -0
- package/build/fields/field-mapper.d.ts +245 -0
- package/build/fields/field-mapper.d.ts.map +1 -0
- package/build/fields/field-mapper.js +404 -0
- package/build/fields/field-mapper.js.map +1 -0
- package/build/index.d.ts +550 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +1527 -0
- package/build/index.js.map +1 -0
- package/build/oauth-helper.d.ts +189 -0
- package/build/oauth-helper.d.ts.map +1 -0
- package/build/oauth-helper.js +422 -0
- package/build/oauth-helper.js.map +1 -0
- package/build/services/app-structure-service.d.ts +49 -0
- package/build/services/app-structure-service.d.ts.map +1 -0
- package/build/services/app-structure-service.js +122 -0
- package/build/services/app-structure-service.js.map +1 -0
- package/build/services/code-execution-service.d.ts +88 -0
- package/build/services/code-execution-service.d.ts.map +1 -0
- package/build/services/code-execution-service.js +342 -0
- package/build/services/code-execution-service.js.map +1 -0
- package/build/services/comment-service.d.ts +66 -0
- package/build/services/comment-service.d.ts.map +1 -0
- package/build/services/comment-service.js +139 -0
- package/build/services/comment-service.js.map +1 -0
- package/build/services/index.d.ts +16 -0
- package/build/services/index.d.ts.map +1 -0
- package/build/services/index.js +15 -0
- package/build/services/index.js.map +1 -0
- package/build/services/item-service.d.ts +104 -0
- package/build/services/item-service.d.ts.map +1 -0
- package/build/services/item-service.js +368 -0
- package/build/services/item-service.js.map +1 -0
- package/build/services/notification-service.d.ts +125 -0
- package/build/services/notification-service.d.ts.map +1 -0
- package/build/services/notification-service.js +321 -0
- package/build/services/notification-service.js.map +1 -0
- package/build/services/project-epic-service.d.ts +73 -0
- package/build/services/project-epic-service.d.ts.map +1 -0
- package/build/services/project-epic-service.js +248 -0
- package/build/services/project-epic-service.js.map +1 -0
- package/build/services/response-formatter.d.ts +190 -0
- package/build/services/response-formatter.d.ts.map +1 -0
- package/build/services/response-formatter.js +1221 -0
- package/build/services/response-formatter.js.map +1 -0
- package/build/services/search-service.d.ts +103 -0
- package/build/services/search-service.d.ts.map +1 -0
- package/build/services/search-service.js +273 -0
- package/build/services/search-service.js.map +1 -0
- package/build/services/task-service.d.ts +70 -0
- package/build/services/task-service.d.ts.map +1 -0
- package/build/services/task-service.js +156 -0
- package/build/services/task-service.js.map +1 -0
- package/build/tools/index.d.ts +8 -0
- package/build/tools/index.d.ts.map +1 -0
- package/build/tools/index.js +8 -0
- package/build/tools/index.js.map +1 -0
- package/build/tools/tool-definitions.d.ts +89 -0
- package/build/tools/tool-definitions.d.ts.map +1 -0
- package/build/tools/tool-definitions.js +1167 -0
- package/build/tools/tool-definitions.js.map +1 -0
- package/build/types/api-types.d.ts +106 -0
- package/build/types/api-types.d.ts.map +1 -0
- package/build/types/api-types.js +11 -0
- package/build/types/api-types.js.map +1 -0
- package/build/types/cache-types.d.ts +52 -0
- package/build/types/cache-types.d.ts.map +1 -0
- package/build/types/cache-types.js +12 -0
- package/build/types/cache-types.js.map +1 -0
- package/build/types/index.d.ts +31 -0
- package/build/types/index.d.ts.map +1 -0
- package/build/types/index.js +25 -0
- package/build/types/index.js.map +1 -0
- package/build/types/notification-types.d.ts +154 -0
- package/build/types/notification-types.d.ts.map +1 -0
- package/build/types/notification-types.js +7 -0
- package/build/types/notification-types.js.map +1 -0
- package/build/types/podio-types.d.ts +250 -0
- package/build/types/podio-types.d.ts.map +1 -0
- package/build/types/podio-types.js +11 -0
- package/build/types/podio-types.js.map +1 -0
- package/build/types/search-types.d.ts +188 -0
- package/build/types/search-types.d.ts.map +1 -0
- package/build/types/search-types.js +43 -0
- package/build/types/search-types.js.map +1 -0
- package/build/utils/debug.d.ts +58 -0
- package/build/utils/debug.d.ts.map +1 -0
- package/build/utils/debug.js +147 -0
- package/build/utils/debug.js.map +1 -0
- package/examples/claude-config-example.json +13 -0
- package/package.json +87 -0
- package/scripts/generate-claude-config.js +107 -0
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,550 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* @fileoverview Podio MCP Server - A Model Context Protocol server for integrating Podio with Claude Desktop.
|
|
4
|
+
*
|
|
5
|
+
* This server provides natural language management of Podio items and tasks through Claude conversations.
|
|
6
|
+
* It implements the MCP protocol to expose Podio operations as tools that can be called by AI assistants.
|
|
7
|
+
*
|
|
8
|
+
* @version 0.2.0 - Refactored with modular architecture
|
|
9
|
+
* @author Podio MCP Team
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Refactored MCP server class that coordinates modular components.
|
|
13
|
+
*
|
|
14
|
+
* This class now serves as a lightweight coordinator between the MCP protocol
|
|
15
|
+
* and specialized service classes. It delegates API calls, caching, field operations,
|
|
16
|
+
* and error handling to dedicated modules for better maintainability.
|
|
17
|
+
*
|
|
18
|
+
* The server uses dependency injection and modular architecture for improved
|
|
19
|
+
* testability and separation of concerns.
|
|
20
|
+
*
|
|
21
|
+
* @class PodioMCPServer
|
|
22
|
+
* @example
|
|
23
|
+
* ```typescript
|
|
24
|
+
* const server = new PodioMCPServer();
|
|
25
|
+
* await server.run();
|
|
26
|
+
* ```
|
|
27
|
+
*/
|
|
28
|
+
declare class PodioMCPServer {
|
|
29
|
+
/** The underlying MCP server instance */
|
|
30
|
+
private readonly server;
|
|
31
|
+
/** OAuth helper for managing authentication */
|
|
32
|
+
private oauthHelper;
|
|
33
|
+
/** API client for all Podio operations */
|
|
34
|
+
private apiClient;
|
|
35
|
+
/** Unified cache manager */
|
|
36
|
+
private cacheManager;
|
|
37
|
+
/** Map of loaded app structures with field mappers by coordinates key */
|
|
38
|
+
private loadedApps;
|
|
39
|
+
/** Default/active app coordinates for backward compatibility */
|
|
40
|
+
private activeAppKey;
|
|
41
|
+
/** Service layer instances */
|
|
42
|
+
private itemService;
|
|
43
|
+
private taskService;
|
|
44
|
+
private projectEpicService;
|
|
45
|
+
private appStructureService;
|
|
46
|
+
private notificationService;
|
|
47
|
+
private searchService;
|
|
48
|
+
private commentService;
|
|
49
|
+
private codeExecutionService;
|
|
50
|
+
/**
|
|
51
|
+
* Initialize the refactored Podio MCP server.
|
|
52
|
+
*
|
|
53
|
+
* Sets up the MCP server with modular components and initializes
|
|
54
|
+
* OAuth authentication and API client if credentials are available.
|
|
55
|
+
*
|
|
56
|
+
* Required environment variables:
|
|
57
|
+
* - PODIO_CLIENT_ID: Your Podio app's client ID
|
|
58
|
+
* - PODIO_CLIENT_SECRET: Your Podio app's client secret
|
|
59
|
+
* - PODIO_REDIRECT_URI: OAuth redirect URI (typically http://localhost:8080/callback)
|
|
60
|
+
*
|
|
61
|
+
* @constructor
|
|
62
|
+
*/
|
|
63
|
+
constructor();
|
|
64
|
+
/**
|
|
65
|
+
* Initialize OAuth helper and API client from environment variables.
|
|
66
|
+
*
|
|
67
|
+
* @private
|
|
68
|
+
*/
|
|
69
|
+
private initializeAuthAndApi;
|
|
70
|
+
/**
|
|
71
|
+
* Set up MCP request handlers for tools.
|
|
72
|
+
*
|
|
73
|
+
* Uses the modular tool definitions and proper error handling.
|
|
74
|
+
*
|
|
75
|
+
* @private
|
|
76
|
+
*/
|
|
77
|
+
private setupToolHandlers;
|
|
78
|
+
/**
|
|
79
|
+
* Route tool calls to appropriate handlers.
|
|
80
|
+
*
|
|
81
|
+
* @private
|
|
82
|
+
* @param name - Tool name
|
|
83
|
+
* @param args - Tool arguments
|
|
84
|
+
* @returns Tool response
|
|
85
|
+
*/
|
|
86
|
+
private handleToolCall;
|
|
87
|
+
/**
|
|
88
|
+
* Handle errors from tool execution with proper typing.
|
|
89
|
+
*
|
|
90
|
+
* @private
|
|
91
|
+
* @param toolName - Name of the tool that failed
|
|
92
|
+
* @param error - The error that occurred
|
|
93
|
+
* @returns Formatted error response
|
|
94
|
+
*/
|
|
95
|
+
private handleToolError;
|
|
96
|
+
/**
|
|
97
|
+
* Ensure API client and services are available and authenticated.
|
|
98
|
+
*
|
|
99
|
+
* @private
|
|
100
|
+
* @throws PodioAuthError if authentication is not available
|
|
101
|
+
*/
|
|
102
|
+
private ensureServicesAvailable;
|
|
103
|
+
/**
|
|
104
|
+
* Get the coordinate key for a given set of coordinates.
|
|
105
|
+
*
|
|
106
|
+
* @private
|
|
107
|
+
* @param coordinates - App coordinates
|
|
108
|
+
* @returns String key for the coordinates
|
|
109
|
+
*/
|
|
110
|
+
private getCoordinateKey;
|
|
111
|
+
/**
|
|
112
|
+
* Get the active app structure and field mapper.
|
|
113
|
+
*
|
|
114
|
+
* @private
|
|
115
|
+
* @returns Active app structure and field mapper or null
|
|
116
|
+
*/
|
|
117
|
+
private getActiveApp;
|
|
118
|
+
/**
|
|
119
|
+
* Get app context for an operation - either from provided coordinates or active app.
|
|
120
|
+
* Throws a helpful error if no app context is available.
|
|
121
|
+
*
|
|
122
|
+
* @private
|
|
123
|
+
* @param args - Arguments potentially containing coordinates
|
|
124
|
+
* @param operation - Operation name for error message
|
|
125
|
+
* @returns App context with structure and field mapper
|
|
126
|
+
*/
|
|
127
|
+
private getAppContextForOperation;
|
|
128
|
+
/**
|
|
129
|
+
* Ensure app structure is loaded using the app structure service.
|
|
130
|
+
* Supports loading multiple apps into memory simultaneously.
|
|
131
|
+
*
|
|
132
|
+
* @private
|
|
133
|
+
* @param args - Arguments with optional coordinates and force_refresh
|
|
134
|
+
* @returns The loaded app structure and field mapper
|
|
135
|
+
*/
|
|
136
|
+
private ensureAppStructureLoaded;
|
|
137
|
+
/**
|
|
138
|
+
* Load and cache the structure of a Podio app.
|
|
139
|
+
* Supports loading multiple apps simultaneously.
|
|
140
|
+
*
|
|
141
|
+
* @private
|
|
142
|
+
* @param args - Arguments containing optional org_label, space_label, app_label, force_refresh, set_as_active
|
|
143
|
+
* @returns MCP tool response with app structure information
|
|
144
|
+
*/
|
|
145
|
+
private getAppStructure;
|
|
146
|
+
/**
|
|
147
|
+
* Cache app structure by coordinates.
|
|
148
|
+
*
|
|
149
|
+
* @private
|
|
150
|
+
*/
|
|
151
|
+
private cacheAppStructure;
|
|
152
|
+
/**
|
|
153
|
+
* List all cached apps (both in memory and in persistent cache).
|
|
154
|
+
*
|
|
155
|
+
* @private
|
|
156
|
+
*/
|
|
157
|
+
private listCachedApps;
|
|
158
|
+
/**
|
|
159
|
+
* Refresh app cache.
|
|
160
|
+
*
|
|
161
|
+
* @private
|
|
162
|
+
*/
|
|
163
|
+
private refreshAppCache;
|
|
164
|
+
/**
|
|
165
|
+
* Set the active app for operations that don't specify coordinates.
|
|
166
|
+
*
|
|
167
|
+
* @private
|
|
168
|
+
* @param args - App coordinates to set as active
|
|
169
|
+
*/
|
|
170
|
+
private setActiveApp;
|
|
171
|
+
/**
|
|
172
|
+
* Clear app cache from both memory and persistent storage.
|
|
173
|
+
* Supports clearing a specific app or all apps.
|
|
174
|
+
*
|
|
175
|
+
* @private
|
|
176
|
+
* @param args - Optional app_id or coordinates to clear specific app
|
|
177
|
+
*/
|
|
178
|
+
private clearAppCache;
|
|
179
|
+
/**
|
|
180
|
+
* List items from the configured Podio app with optional filtering.
|
|
181
|
+
* Supports multi-app context by using coordinates or active app.
|
|
182
|
+
*
|
|
183
|
+
* @private
|
|
184
|
+
* @param args - Filter arguments
|
|
185
|
+
* @returns MCP tool response with formatted list of items
|
|
186
|
+
*/
|
|
187
|
+
private listItems;
|
|
188
|
+
/**
|
|
189
|
+
* Create a new item in the Podio app.
|
|
190
|
+
* Supports multi-app context by using coordinates or active app.
|
|
191
|
+
*
|
|
192
|
+
* @private
|
|
193
|
+
* @param args - Item data
|
|
194
|
+
* @returns MCP tool response with created item information
|
|
195
|
+
*/
|
|
196
|
+
private createItem;
|
|
197
|
+
/**
|
|
198
|
+
* Update an existing item in the Podio app.
|
|
199
|
+
*
|
|
200
|
+
* @private
|
|
201
|
+
* @param args - Update data
|
|
202
|
+
* @returns MCP tool response with update confirmation
|
|
203
|
+
*/
|
|
204
|
+
private updateItem;
|
|
205
|
+
/**
|
|
206
|
+
* Delete an item from the Podio app.
|
|
207
|
+
*
|
|
208
|
+
* @private
|
|
209
|
+
* @param args - Arguments containing item_id
|
|
210
|
+
* @returns MCP tool response with deletion confirmation
|
|
211
|
+
*/
|
|
212
|
+
private deleteItem;
|
|
213
|
+
/**
|
|
214
|
+
* Get detailed information about a specific item.
|
|
215
|
+
*
|
|
216
|
+
* @private
|
|
217
|
+
* @param args - Arguments containing item_id
|
|
218
|
+
* @returns MCP tool response with detailed item information
|
|
219
|
+
*/
|
|
220
|
+
private getItemDetails;
|
|
221
|
+
/**
|
|
222
|
+
* Get detailed information about a specific item using its app item ID.
|
|
223
|
+
*
|
|
224
|
+
* @private
|
|
225
|
+
* @param args - Arguments containing app_item_id
|
|
226
|
+
* @returns MCP tool response with detailed item information
|
|
227
|
+
*/
|
|
228
|
+
private getItemByAppItemId;
|
|
229
|
+
/**
|
|
230
|
+
* Update an item using its app item ID.
|
|
231
|
+
*
|
|
232
|
+
* @private
|
|
233
|
+
* @param args - Arguments containing app_item_id and update data
|
|
234
|
+
* @returns MCP tool response with update confirmation
|
|
235
|
+
*/
|
|
236
|
+
private updateItemByAppItemId;
|
|
237
|
+
/**
|
|
238
|
+
* Delete an item using its app item ID.
|
|
239
|
+
*
|
|
240
|
+
* @private
|
|
241
|
+
* @param args - Arguments containing app_item_id
|
|
242
|
+
* @returns MCP tool response with delete confirmation
|
|
243
|
+
*/
|
|
244
|
+
private deleteItemByAppItemId;
|
|
245
|
+
/**
|
|
246
|
+
* List Podio tasks with optional filtering.
|
|
247
|
+
*
|
|
248
|
+
* @private
|
|
249
|
+
* @param args - Filter arguments
|
|
250
|
+
* @returns MCP tool response with formatted list of tasks
|
|
251
|
+
*/
|
|
252
|
+
private listTasks;
|
|
253
|
+
/**
|
|
254
|
+
* Create a new task in Podio.
|
|
255
|
+
*
|
|
256
|
+
* @private
|
|
257
|
+
* @param args - Task data
|
|
258
|
+
* @returns MCP tool response with created task information
|
|
259
|
+
*/
|
|
260
|
+
private createTask;
|
|
261
|
+
/**
|
|
262
|
+
* Create a new task attached to a specific Podio item.
|
|
263
|
+
*
|
|
264
|
+
* @private
|
|
265
|
+
* @param args - Task data with item_id
|
|
266
|
+
* @returns MCP tool response with created task information
|
|
267
|
+
*/
|
|
268
|
+
private createTaskForItem;
|
|
269
|
+
/**
|
|
270
|
+
* Update an existing task in Podio.
|
|
271
|
+
*
|
|
272
|
+
* @private
|
|
273
|
+
* @param args - Task update data
|
|
274
|
+
* @returns MCP tool response with update confirmation
|
|
275
|
+
*/
|
|
276
|
+
private updateTask;
|
|
277
|
+
/**
|
|
278
|
+
* Delete a task from Podio.
|
|
279
|
+
*
|
|
280
|
+
* @private
|
|
281
|
+
* @param args - Arguments containing task_id
|
|
282
|
+
* @returns MCP tool response with deletion confirmation
|
|
283
|
+
*/
|
|
284
|
+
private deleteTask;
|
|
285
|
+
/**
|
|
286
|
+
* Get detailed information about a specific task.
|
|
287
|
+
*
|
|
288
|
+
* @private
|
|
289
|
+
* @param args - Arguments containing task_id
|
|
290
|
+
* @returns MCP tool response with detailed task information
|
|
291
|
+
*/
|
|
292
|
+
private getTaskDetails;
|
|
293
|
+
/**
|
|
294
|
+
* List all available projects.
|
|
295
|
+
*
|
|
296
|
+
* @private
|
|
297
|
+
* @param args - Arguments with optional refresh_cache
|
|
298
|
+
* @returns MCP tool response with formatted list of projects
|
|
299
|
+
*/
|
|
300
|
+
private listProjects;
|
|
301
|
+
/**
|
|
302
|
+
* List all available epics.
|
|
303
|
+
*
|
|
304
|
+
* @private
|
|
305
|
+
* @param args - Arguments with optional refresh_cache
|
|
306
|
+
* @returns MCP tool response with formatted list of epics
|
|
307
|
+
*/
|
|
308
|
+
private listEpics;
|
|
309
|
+
/**
|
|
310
|
+
* Suggest appropriate project and epic based on item details using sophisticated AI-powered matching.
|
|
311
|
+
*
|
|
312
|
+
* This function implements a comprehensive suggestion system that analyzes input text against
|
|
313
|
+
* cached projects and epics using multiple matching strategies and weighted scoring algorithms.
|
|
314
|
+
*
|
|
315
|
+
* ## Matching Algorithm
|
|
316
|
+
*
|
|
317
|
+
* The suggestion system uses a hierarchical matching approach with weighted scoring:
|
|
318
|
+
*
|
|
319
|
+
* ### Scoring Weights
|
|
320
|
+
* - **Title matching**: 1.0x (full weight)
|
|
321
|
+
* - **Description matching**: 0.5x (reduced weight as descriptions are less precise)
|
|
322
|
+
* - **Label matching**: 0.3x (minimal weight as labels are often generic)
|
|
323
|
+
*
|
|
324
|
+
* ### Matching Hierarchy
|
|
325
|
+
* 1. **Exact match**: Perfect string match (score: 1.0)
|
|
326
|
+
* 2. **Prefix match**: Input matches start of target (score: 0.9)
|
|
327
|
+
* 3. **Contains match**: Target contains input anywhere (score: 0.7)
|
|
328
|
+
* 4. **Fuzzy match**: Levenshtein distance-based similarity (score: 0.0-0.6)
|
|
329
|
+
*
|
|
330
|
+
* ### Levenshtein Distance Fuzzy Matching
|
|
331
|
+
* When exact/prefix/contains matching fails, the system uses Levenshtein distance
|
|
332
|
+
* to calculate string similarity: `1 - (editDistance / maxStringLength)`
|
|
333
|
+
* This enables matching of typos, abbreviations, and related terms.
|
|
334
|
+
*
|
|
335
|
+
* ## Configuration Parameters
|
|
336
|
+
* - **minSimilarityScore**: 0.3 (filters out weak matches)
|
|
337
|
+
* - **maxSuggestions**: 10 (limits results for performance)
|
|
338
|
+
* - **Cache TTL**: 30 minutes (balances freshness vs performance)
|
|
339
|
+
*
|
|
340
|
+
* ## Cache Behavior
|
|
341
|
+
* - Projects and epics are cached for 30 minutes after first fetch
|
|
342
|
+
* - Cache keys are based on app ID for workspace isolation
|
|
343
|
+
* - Automatic cache refresh on API structure mismatches
|
|
344
|
+
* - Memory-based storage for fast lookups during suggestion scoring
|
|
345
|
+
*
|
|
346
|
+
* @example
|
|
347
|
+
* Input: "API authentication refactor"
|
|
348
|
+
* Matches:
|
|
349
|
+
* - Project: "Authentication System" (0.85 - title similarity)
|
|
350
|
+
* - Epic: "API Improvements" (0.72 - partial title match)
|
|
351
|
+
*
|
|
352
|
+
* @example
|
|
353
|
+
* Input: "database migration task"
|
|
354
|
+
* Matches:
|
|
355
|
+
* - Project: "Database Modernization" (0.68 - fuzzy title match)
|
|
356
|
+
* - Epic: "Data Migration" (0.91 - strong title match)
|
|
357
|
+
*
|
|
358
|
+
* @private
|
|
359
|
+
* @param args - Arguments containing title and optional description
|
|
360
|
+
* @param args.title - The title of the item to suggest projects/epics for (required)
|
|
361
|
+
* @param args.description - Optional description providing additional context for matching
|
|
362
|
+
* @returns MCP tool response with ranked suggestions including:
|
|
363
|
+
* - Matched projects with similarity scores and reasons
|
|
364
|
+
* - Matched epics with similarity scores and reasons
|
|
365
|
+
* - Empty arrays if no matches above similarity threshold found
|
|
366
|
+
* @throws {PodioValidationError} If title parameter is missing or empty
|
|
367
|
+
* @throws {PodioStructureError} If app structure is not loaded
|
|
368
|
+
* @throws {PodioApiError} If project/epic data cannot be fetched from cache or API
|
|
369
|
+
*/
|
|
370
|
+
private suggestProjectEpic;
|
|
371
|
+
/**
|
|
372
|
+
* Inspect the structure of fields in the app.
|
|
373
|
+
*
|
|
374
|
+
* @private
|
|
375
|
+
* @param args - Arguments with optional field_name
|
|
376
|
+
* @returns MCP tool response with field structure information
|
|
377
|
+
*/
|
|
378
|
+
private inspectFieldStructure;
|
|
379
|
+
/**
|
|
380
|
+
* List all members of the current space.
|
|
381
|
+
*
|
|
382
|
+
* @private
|
|
383
|
+
* @param args - Arguments with optional refresh_cache
|
|
384
|
+
* @returns MCP tool response with formatted list of space members
|
|
385
|
+
*/
|
|
386
|
+
private listSpaceMembers;
|
|
387
|
+
/**
|
|
388
|
+
* List Podio notifications with optional filtering.
|
|
389
|
+
*
|
|
390
|
+
* @private
|
|
391
|
+
* @param args - Filter arguments
|
|
392
|
+
* @returns MCP tool response with formatted list of notifications
|
|
393
|
+
*/
|
|
394
|
+
private listNotifications;
|
|
395
|
+
/**
|
|
396
|
+
* Get detailed information about a specific notification.
|
|
397
|
+
*
|
|
398
|
+
* @private
|
|
399
|
+
* @param args - Arguments containing notification_id
|
|
400
|
+
* @returns MCP tool response with detailed notification information
|
|
401
|
+
*/
|
|
402
|
+
private getNotificationDetails;
|
|
403
|
+
/**
|
|
404
|
+
* Get unread notification count.
|
|
405
|
+
*
|
|
406
|
+
* @private
|
|
407
|
+
* @param args - Empty arguments object
|
|
408
|
+
* @returns MCP tool response with unread count information
|
|
409
|
+
*/
|
|
410
|
+
private getUnreadCount;
|
|
411
|
+
/**
|
|
412
|
+
* Get notification settings for the current user.
|
|
413
|
+
*
|
|
414
|
+
* @private
|
|
415
|
+
* @param args - Empty arguments object
|
|
416
|
+
* @returns MCP tool response with notification settings
|
|
417
|
+
*/
|
|
418
|
+
private getNotificationSettings;
|
|
419
|
+
/**
|
|
420
|
+
* Main search tool with scope selection and filtering
|
|
421
|
+
*
|
|
422
|
+
* @private
|
|
423
|
+
* @param args - Search arguments
|
|
424
|
+
* @returns MCP tool response with search results
|
|
425
|
+
*/
|
|
426
|
+
private searchPodio;
|
|
427
|
+
/**
|
|
428
|
+
* Quick search within a specific app
|
|
429
|
+
*
|
|
430
|
+
* @private
|
|
431
|
+
* @param args - Search arguments
|
|
432
|
+
* @returns MCP tool response with search results
|
|
433
|
+
*/
|
|
434
|
+
private searchInApp;
|
|
435
|
+
/**
|
|
436
|
+
* Quick search within a specific space
|
|
437
|
+
*
|
|
438
|
+
* @private
|
|
439
|
+
* @param args - Search arguments
|
|
440
|
+
* @returns MCP tool response with search results
|
|
441
|
+
*/
|
|
442
|
+
private searchInSpace;
|
|
443
|
+
/**
|
|
444
|
+
* Get search history
|
|
445
|
+
*
|
|
446
|
+
* @private
|
|
447
|
+
* @param args - Arguments with optional limit
|
|
448
|
+
* @returns MCP tool response with search history
|
|
449
|
+
*/
|
|
450
|
+
private getSearchHistory;
|
|
451
|
+
/**
|
|
452
|
+
* Clear search history
|
|
453
|
+
*
|
|
454
|
+
* @private
|
|
455
|
+
* @param args - Empty arguments object
|
|
456
|
+
* @returns MCP tool response with success confirmation
|
|
457
|
+
*/
|
|
458
|
+
private clearSearchHistory;
|
|
459
|
+
/**
|
|
460
|
+
* List all comments for a specific item.
|
|
461
|
+
*
|
|
462
|
+
* @private
|
|
463
|
+
* @param args - Arguments containing item_id
|
|
464
|
+
* @returns MCP tool response with list of comments
|
|
465
|
+
*/
|
|
466
|
+
private listItemComments;
|
|
467
|
+
/**
|
|
468
|
+
* Create a new comment on an item.
|
|
469
|
+
*
|
|
470
|
+
* @private
|
|
471
|
+
* @param args - Arguments containing item_id and text
|
|
472
|
+
* @returns MCP tool response with created comment
|
|
473
|
+
*/
|
|
474
|
+
private createItemComment;
|
|
475
|
+
/**
|
|
476
|
+
* Get details of a specific comment.
|
|
477
|
+
*
|
|
478
|
+
* @private
|
|
479
|
+
* @param args - Arguments containing comment_id
|
|
480
|
+
* @returns MCP tool response with comment details
|
|
481
|
+
*/
|
|
482
|
+
private getCommentDetails;
|
|
483
|
+
/**
|
|
484
|
+
* Update an existing comment.
|
|
485
|
+
*
|
|
486
|
+
* @private
|
|
487
|
+
* @param args - Arguments containing comment_id and text
|
|
488
|
+
* @returns MCP tool response with success confirmation
|
|
489
|
+
*/
|
|
490
|
+
private updateComment;
|
|
491
|
+
/**
|
|
492
|
+
* Delete a comment.
|
|
493
|
+
*
|
|
494
|
+
* @private
|
|
495
|
+
* @param args - Arguments containing comment_id
|
|
496
|
+
* @returns MCP tool response with deletion confirmation
|
|
497
|
+
*/
|
|
498
|
+
private deleteComment;
|
|
499
|
+
/**
|
|
500
|
+
* List all activity/revisions for a specific item.
|
|
501
|
+
*
|
|
502
|
+
* @private
|
|
503
|
+
* @param args - Arguments containing item_id
|
|
504
|
+
* @returns MCP tool response with item activity
|
|
505
|
+
*/
|
|
506
|
+
private listItemActivity;
|
|
507
|
+
/**
|
|
508
|
+
* Get details of a specific item revision.
|
|
509
|
+
*
|
|
510
|
+
* @private
|
|
511
|
+
* @param args - Arguments containing item_id and revision_id
|
|
512
|
+
* @returns MCP tool response with revision details
|
|
513
|
+
*/
|
|
514
|
+
private getItemRevision;
|
|
515
|
+
/**
|
|
516
|
+
* Get the difference between two item revisions.
|
|
517
|
+
*
|
|
518
|
+
* @private
|
|
519
|
+
* @param args - Arguments containing item_id, from_revision, and to_revision
|
|
520
|
+
* @returns MCP tool response with revision differences
|
|
521
|
+
*/
|
|
522
|
+
private getItemRevisionDiff;
|
|
523
|
+
/**
|
|
524
|
+
* Execute TypeScript/JavaScript code in a sandboxed Deno environment.
|
|
525
|
+
*
|
|
526
|
+
* This tool provides 60-95% token reduction for complex multi-step operations
|
|
527
|
+
* by processing data in the execution environment instead of passing it
|
|
528
|
+
* through the model context.
|
|
529
|
+
*
|
|
530
|
+
* @private
|
|
531
|
+
* @param args - Arguments containing code, timeout, and optional context
|
|
532
|
+
* @returns Code execution result
|
|
533
|
+
*/
|
|
534
|
+
private executeCode;
|
|
535
|
+
/**
|
|
536
|
+
* List all available functions in the filesystem code execution API.
|
|
537
|
+
*
|
|
538
|
+
* @private
|
|
539
|
+
* @returns List of available functions organized by category
|
|
540
|
+
*/
|
|
541
|
+
private listCodeFunctions;
|
|
542
|
+
/**
|
|
543
|
+
* Run the MCP server.
|
|
544
|
+
*
|
|
545
|
+
* Starts the server and handles graceful shutdown.
|
|
546
|
+
*/
|
|
547
|
+
run(): Promise<void>;
|
|
548
|
+
}
|
|
549
|
+
export { PodioMCPServer };
|
|
550
|
+
//# 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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"}
|