@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.
Files changed (197) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +491 -0
  3. package/build/__tests__/integration/setup.integration.d.ts +104 -0
  4. package/build/__tests__/integration/setup.integration.d.ts.map +1 -0
  5. package/build/__tests__/integration/setup.integration.js +233 -0
  6. package/build/__tests__/integration/setup.integration.js.map +1 -0
  7. package/build/__tests__/mock-data/items-mock-data.d.ts +168 -0
  8. package/build/__tests__/mock-data/items-mock-data.d.ts.map +1 -0
  9. package/build/__tests__/mock-data/items-mock-data.js +370 -0
  10. package/build/__tests__/mock-data/items-mock-data.js.map +1 -0
  11. package/build/__tests__/mock-data/notification-mock-data.d.ts +55 -0
  12. package/build/__tests__/mock-data/notification-mock-data.d.ts.map +1 -0
  13. package/build/__tests__/mock-data/notification-mock-data.js +190 -0
  14. package/build/__tests__/mock-data/notification-mock-data.js.map +1 -0
  15. package/build/__tests__/mock-data/project-epic-mock-data.d.ts +45 -0
  16. package/build/__tests__/mock-data/project-epic-mock-data.d.ts.map +1 -0
  17. package/build/__tests__/mock-data/project-epic-mock-data.js +85 -0
  18. package/build/__tests__/mock-data/project-epic-mock-data.js.map +1 -0
  19. package/build/__tests__/mock-data/tasks-mock-data.d.ts +27 -0
  20. package/build/__tests__/mock-data/tasks-mock-data.d.ts.map +1 -0
  21. package/build/__tests__/mock-data/tasks-mock-data.js +104 -0
  22. package/build/__tests__/mock-data/tasks-mock-data.js.map +1 -0
  23. package/build/__tests__/mock-data/utility-mock-data.d.ts +19 -0
  24. package/build/__tests__/mock-data/utility-mock-data.d.ts.map +1 -0
  25. package/build/__tests__/mock-data/utility-mock-data.js +165 -0
  26. package/build/__tests__/mock-data/utility-mock-data.js.map +1 -0
  27. package/build/__tests__/setup.d.ts +8 -0
  28. package/build/__tests__/setup.d.ts.map +1 -0
  29. package/build/__tests__/setup.js +31 -0
  30. package/build/__tests__/setup.js.map +1 -0
  31. package/build/__tests__/utils/test-helpers.d.ts +110 -0
  32. package/build/__tests__/utils/test-helpers.d.ts.map +1 -0
  33. package/build/__tests__/utils/test-helpers.js +222 -0
  34. package/build/__tests__/utils/test-helpers.js.map +1 -0
  35. package/build/api/podio-api-client.d.ts +364 -0
  36. package/build/api/podio-api-client.d.ts.map +1 -0
  37. package/build/api/podio-api-client.js +696 -0
  38. package/build/api/podio-api-client.js.map +1 -0
  39. package/build/cache/app-cache.d.ts +77 -0
  40. package/build/cache/app-cache.d.ts.map +1 -0
  41. package/build/cache/app-cache.js +230 -0
  42. package/build/cache/app-cache.js.map +1 -0
  43. package/build/cache/base-cache-manager.d.ts +149 -0
  44. package/build/cache/base-cache-manager.d.ts.map +1 -0
  45. package/build/cache/base-cache-manager.js +312 -0
  46. package/build/cache/base-cache-manager.js.map +1 -0
  47. package/build/cache/cache-manager.d.ts +230 -0
  48. package/build/cache/cache-manager.d.ts.map +1 -0
  49. package/build/cache/cache-manager.js +362 -0
  50. package/build/cache/cache-manager.js.map +1 -0
  51. package/build/cache/cache-test.d.ts +9 -0
  52. package/build/cache/cache-test.d.ts.map +1 -0
  53. package/build/cache/cache-test.js +169 -0
  54. package/build/cache/cache-test.js.map +1 -0
  55. package/build/cache/index.d.ts +18 -0
  56. package/build/cache/index.d.ts.map +1 -0
  57. package/build/cache/index.js +20 -0
  58. package/build/cache/index.js.map +1 -0
  59. package/build/cache/migration-helper.d.ts +44 -0
  60. package/build/cache/migration-helper.d.ts.map +1 -0
  61. package/build/cache/migration-helper.js +235 -0
  62. package/build/cache/migration-helper.js.map +1 -0
  63. package/build/cache/project-epic-cache.d.ts +108 -0
  64. package/build/cache/project-epic-cache.d.ts.map +1 -0
  65. package/build/cache/project-epic-cache.js +278 -0
  66. package/build/cache/project-epic-cache.js.map +1 -0
  67. package/build/cache/space-members-cache.d.ts +99 -0
  68. package/build/cache/space-members-cache.d.ts.map +1 -0
  69. package/build/cache/space-members-cache.js +305 -0
  70. package/build/cache/space-members-cache.js.map +1 -0
  71. package/build/cache/storage-adapters.d.ts +100 -0
  72. package/build/cache/storage-adapters.d.ts.map +1 -0
  73. package/build/cache/storage-adapters.js +297 -0
  74. package/build/cache/storage-adapters.js.map +1 -0
  75. package/build/errors/api-errors.d.ts +52 -0
  76. package/build/errors/api-errors.d.ts.map +1 -0
  77. package/build/errors/api-errors.js +86 -0
  78. package/build/errors/api-errors.js.map +1 -0
  79. package/build/errors/auth-errors.d.ts +67 -0
  80. package/build/errors/auth-errors.d.ts.map +1 -0
  81. package/build/errors/auth-errors.js +114 -0
  82. package/build/errors/auth-errors.js.map +1 -0
  83. package/build/errors/base.d.ts +102 -0
  84. package/build/errors/base.d.ts.map +1 -0
  85. package/build/errors/base.js +131 -0
  86. package/build/errors/base.js.map +1 -0
  87. package/build/errors/cache-errors.d.ts +53 -0
  88. package/build/errors/cache-errors.d.ts.map +1 -0
  89. package/build/errors/cache-errors.js +83 -0
  90. package/build/errors/cache-errors.js.map +1 -0
  91. package/build/errors/config-errors.d.ts +58 -0
  92. package/build/errors/config-errors.d.ts.map +1 -0
  93. package/build/errors/config-errors.js +96 -0
  94. package/build/errors/config-errors.js.map +1 -0
  95. package/build/errors/index.d.ts +101 -0
  96. package/build/errors/index.d.ts.map +1 -0
  97. package/build/errors/index.js +135 -0
  98. package/build/errors/index.js.map +1 -0
  99. package/build/errors/structure-errors.d.ts +89 -0
  100. package/build/errors/structure-errors.d.ts.map +1 -0
  101. package/build/errors/structure-errors.js +182 -0
  102. package/build/errors/structure-errors.js.map +1 -0
  103. package/build/errors/validation-errors.d.ts +81 -0
  104. package/build/errors/validation-errors.d.ts.map +1 -0
  105. package/build/errors/validation-errors.js +169 -0
  106. package/build/errors/validation-errors.js.map +1 -0
  107. package/build/fields/field-mapper.d.ts +245 -0
  108. package/build/fields/field-mapper.d.ts.map +1 -0
  109. package/build/fields/field-mapper.js +404 -0
  110. package/build/fields/field-mapper.js.map +1 -0
  111. package/build/index.d.ts +550 -0
  112. package/build/index.d.ts.map +1 -0
  113. package/build/index.js +1527 -0
  114. package/build/index.js.map +1 -0
  115. package/build/oauth-helper.d.ts +189 -0
  116. package/build/oauth-helper.d.ts.map +1 -0
  117. package/build/oauth-helper.js +422 -0
  118. package/build/oauth-helper.js.map +1 -0
  119. package/build/services/app-structure-service.d.ts +49 -0
  120. package/build/services/app-structure-service.d.ts.map +1 -0
  121. package/build/services/app-structure-service.js +122 -0
  122. package/build/services/app-structure-service.js.map +1 -0
  123. package/build/services/code-execution-service.d.ts +88 -0
  124. package/build/services/code-execution-service.d.ts.map +1 -0
  125. package/build/services/code-execution-service.js +342 -0
  126. package/build/services/code-execution-service.js.map +1 -0
  127. package/build/services/comment-service.d.ts +66 -0
  128. package/build/services/comment-service.d.ts.map +1 -0
  129. package/build/services/comment-service.js +139 -0
  130. package/build/services/comment-service.js.map +1 -0
  131. package/build/services/index.d.ts +16 -0
  132. package/build/services/index.d.ts.map +1 -0
  133. package/build/services/index.js +15 -0
  134. package/build/services/index.js.map +1 -0
  135. package/build/services/item-service.d.ts +104 -0
  136. package/build/services/item-service.d.ts.map +1 -0
  137. package/build/services/item-service.js +368 -0
  138. package/build/services/item-service.js.map +1 -0
  139. package/build/services/notification-service.d.ts +125 -0
  140. package/build/services/notification-service.d.ts.map +1 -0
  141. package/build/services/notification-service.js +321 -0
  142. package/build/services/notification-service.js.map +1 -0
  143. package/build/services/project-epic-service.d.ts +73 -0
  144. package/build/services/project-epic-service.d.ts.map +1 -0
  145. package/build/services/project-epic-service.js +248 -0
  146. package/build/services/project-epic-service.js.map +1 -0
  147. package/build/services/response-formatter.d.ts +190 -0
  148. package/build/services/response-formatter.d.ts.map +1 -0
  149. package/build/services/response-formatter.js +1221 -0
  150. package/build/services/response-formatter.js.map +1 -0
  151. package/build/services/search-service.d.ts +103 -0
  152. package/build/services/search-service.d.ts.map +1 -0
  153. package/build/services/search-service.js +273 -0
  154. package/build/services/search-service.js.map +1 -0
  155. package/build/services/task-service.d.ts +70 -0
  156. package/build/services/task-service.d.ts.map +1 -0
  157. package/build/services/task-service.js +156 -0
  158. package/build/services/task-service.js.map +1 -0
  159. package/build/tools/index.d.ts +8 -0
  160. package/build/tools/index.d.ts.map +1 -0
  161. package/build/tools/index.js +8 -0
  162. package/build/tools/index.js.map +1 -0
  163. package/build/tools/tool-definitions.d.ts +89 -0
  164. package/build/tools/tool-definitions.d.ts.map +1 -0
  165. package/build/tools/tool-definitions.js +1167 -0
  166. package/build/tools/tool-definitions.js.map +1 -0
  167. package/build/types/api-types.d.ts +106 -0
  168. package/build/types/api-types.d.ts.map +1 -0
  169. package/build/types/api-types.js +11 -0
  170. package/build/types/api-types.js.map +1 -0
  171. package/build/types/cache-types.d.ts +52 -0
  172. package/build/types/cache-types.d.ts.map +1 -0
  173. package/build/types/cache-types.js +12 -0
  174. package/build/types/cache-types.js.map +1 -0
  175. package/build/types/index.d.ts +31 -0
  176. package/build/types/index.d.ts.map +1 -0
  177. package/build/types/index.js +25 -0
  178. package/build/types/index.js.map +1 -0
  179. package/build/types/notification-types.d.ts +154 -0
  180. package/build/types/notification-types.d.ts.map +1 -0
  181. package/build/types/notification-types.js +7 -0
  182. package/build/types/notification-types.js.map +1 -0
  183. package/build/types/podio-types.d.ts +250 -0
  184. package/build/types/podio-types.d.ts.map +1 -0
  185. package/build/types/podio-types.js +11 -0
  186. package/build/types/podio-types.js.map +1 -0
  187. package/build/types/search-types.d.ts +188 -0
  188. package/build/types/search-types.d.ts.map +1 -0
  189. package/build/types/search-types.js +43 -0
  190. package/build/types/search-types.js.map +1 -0
  191. package/build/utils/debug.d.ts +58 -0
  192. package/build/utils/debug.d.ts.map +1 -0
  193. package/build/utils/debug.js +147 -0
  194. package/build/utils/debug.js.map +1 -0
  195. package/examples/claude-config-example.json +13 -0
  196. package/package.json +87 -0
  197. package/scripts/generate-claude-config.js +107 -0
@@ -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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"}