@forumviriumhelsinki/podio-mcp 2.3.0 → 2.5.4

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 (157) hide show
  1. package/README.md +178 -405
  2. package/build/api/podio-api-client.d.ts +64 -16
  3. package/build/api/podio-api-client.d.ts.map +1 -1
  4. package/build/api/podio-api-client.js +230 -130
  5. package/build/api/podio-api-client.js.map +1 -1
  6. package/build/cache/app-cache.d.ts +2 -2
  7. package/build/cache/app-cache.d.ts.map +1 -1
  8. package/build/cache/app-cache.js +4 -3
  9. package/build/cache/app-cache.js.map +1 -1
  10. package/build/cache/base-cache-manager.d.ts +2 -2
  11. package/build/cache/base-cache-manager.d.ts.map +1 -1
  12. package/build/cache/base-cache-manager.js +4 -1
  13. package/build/cache/base-cache-manager.js.map +1 -1
  14. package/build/cache/cache-manager.d.ts +7 -7
  15. package/build/cache/cache-manager.d.ts.map +1 -1
  16. package/build/cache/cache-manager.js +3 -3
  17. package/build/cache/cache-manager.js.map +1 -1
  18. package/build/cache/migration-helper.d.ts +1 -1
  19. package/build/cache/migration-helper.d.ts.map +1 -1
  20. package/build/cache/migration-helper.js +3 -2
  21. package/build/cache/migration-helper.js.map +1 -1
  22. package/build/cache/project-epic-cache.d.ts +5 -1
  23. package/build/cache/project-epic-cache.d.ts.map +1 -1
  24. package/build/cache/project-epic-cache.js +2 -2
  25. package/build/cache/project-epic-cache.js.map +1 -1
  26. package/build/cache/space-members-cache.d.ts +5 -0
  27. package/build/cache/space-members-cache.d.ts.map +1 -1
  28. package/build/cache/space-members-cache.js +70 -32
  29. package/build/cache/space-members-cache.js.map +1 -1
  30. package/build/cache/storage-adapters.d.ts +3 -3
  31. package/build/cache/storage-adapters.d.ts.map +1 -1
  32. package/build/cache/storage-adapters.js +8 -7
  33. package/build/cache/storage-adapters.js.map +1 -1
  34. package/build/config/build-defaults.d.ts +19 -0
  35. package/build/config/build-defaults.d.ts.map +1 -0
  36. package/build/config/build-defaults.js +19 -0
  37. package/build/config/build-defaults.js.map +1 -0
  38. package/build/errors/api-errors.d.ts +3 -3
  39. package/build/errors/api-errors.d.ts.map +1 -1
  40. package/build/errors/api-errors.js +60 -12
  41. package/build/errors/api-errors.js.map +1 -1
  42. package/build/errors/auth-errors.js +1 -1
  43. package/build/errors/auth-errors.js.map +1 -1
  44. package/build/errors/base.d.ts +8 -2
  45. package/build/errors/base.d.ts.map +1 -1
  46. package/build/errors/base.js.map +1 -1
  47. package/build/errors/config-errors.d.ts +1 -1
  48. package/build/errors/config-errors.d.ts.map +1 -1
  49. package/build/errors/config-errors.js.map +1 -1
  50. package/build/errors/index.d.ts +14 -14
  51. package/build/errors/index.d.ts.map +1 -1
  52. package/build/errors/index.js +15 -15
  53. package/build/errors/index.js.map +1 -1
  54. package/build/errors/structure-errors.d.ts +2 -2
  55. package/build/errors/structure-errors.d.ts.map +1 -1
  56. package/build/errors/structure-errors.js.map +1 -1
  57. package/build/errors/validation-errors.d.ts +4 -4
  58. package/build/errors/validation-errors.d.ts.map +1 -1
  59. package/build/errors/validation-errors.js.map +1 -1
  60. package/build/fields/field-mapper.d.ts +26 -6
  61. package/build/fields/field-mapper.d.ts.map +1 -1
  62. package/build/fields/field-mapper.js +44 -21
  63. package/build/fields/field-mapper.js.map +1 -1
  64. package/build/index.d.ts +18 -5
  65. package/build/index.d.ts.map +1 -1
  66. package/build/index.js +220 -131
  67. package/build/index.js.map +1 -1
  68. package/build/oauth-helper.d.ts +87 -6
  69. package/build/oauth-helper.d.ts.map +1 -1
  70. package/build/oauth-helper.js +288 -84
  71. package/build/oauth-helper.js.map +1 -1
  72. package/build/services/app-structure-service.d.ts +1 -1
  73. package/build/services/app-structure-service.d.ts.map +1 -1
  74. package/build/services/app-structure-service.js.map +1 -1
  75. package/build/services/code-execution-service.d.ts +5 -5
  76. package/build/services/code-execution-service.d.ts.map +1 -1
  77. package/build/services/code-execution-service.js +65 -40
  78. package/build/services/code-execution-service.js.map +1 -1
  79. package/build/services/comment-service.d.ts +3 -3
  80. package/build/services/comment-service.d.ts.map +1 -1
  81. package/build/services/comment-service.js +4 -4
  82. package/build/services/comment-service.js.map +1 -1
  83. package/build/services/item-service.d.ts +43 -2
  84. package/build/services/item-service.d.ts.map +1 -1
  85. package/build/services/item-service.js +139 -145
  86. package/build/services/item-service.js.map +1 -1
  87. package/build/services/notification-service.d.ts +1 -2
  88. package/build/services/notification-service.d.ts.map +1 -1
  89. package/build/services/notification-service.js +5 -7
  90. package/build/services/notification-service.js.map +1 -1
  91. package/build/services/project-epic-service.d.ts +51 -2
  92. package/build/services/project-epic-service.d.ts.map +1 -1
  93. package/build/services/project-epic-service.js +172 -86
  94. package/build/services/project-epic-service.js.map +1 -1
  95. package/build/services/response-formatter.d.ts +52 -41
  96. package/build/services/response-formatter.d.ts.map +1 -1
  97. package/build/services/response-formatter.js +92 -91
  98. package/build/services/response-formatter.js.map +1 -1
  99. package/build/services/search-service.d.ts +15 -8
  100. package/build/services/search-service.d.ts.map +1 -1
  101. package/build/services/search-service.js +51 -56
  102. package/build/services/search-service.js.map +1 -1
  103. package/build/services/task-service.js +1 -1
  104. package/build/services/task-service.js.map +1 -1
  105. package/build/tools/tool-definitions.d.ts +2 -2
  106. package/build/tools/tool-definitions.d.ts.map +1 -1
  107. package/build/tools/tool-definitions.js +49 -27
  108. package/build/tools/tool-definitions.js.map +1 -1
  109. package/build/types/api-types.d.ts +9 -0
  110. package/build/types/api-types.d.ts.map +1 -1
  111. package/build/types/notification-types.d.ts +1 -1
  112. package/build/types/notification-types.d.ts.map +1 -1
  113. package/build/types/podio-types.d.ts +42 -9
  114. package/build/types/podio-types.d.ts.map +1 -1
  115. package/build/utils/debug.d.ts +4 -4
  116. package/build/utils/debug.d.ts.map +1 -1
  117. package/build/utils/debug.js +4 -2
  118. package/build/utils/debug.js.map +1 -1
  119. package/examples/claude-config-example.json +13 -5
  120. package/package.json +29 -14
  121. package/scripts/generate-claude-config.js +17 -11
  122. package/build/__tests__/integration/setup.integration.d.ts +0 -104
  123. package/build/__tests__/integration/setup.integration.d.ts.map +0 -1
  124. package/build/__tests__/integration/setup.integration.js +0 -233
  125. package/build/__tests__/integration/setup.integration.js.map +0 -1
  126. package/build/__tests__/mock-data/items-mock-data.d.ts +0 -168
  127. package/build/__tests__/mock-data/items-mock-data.d.ts.map +0 -1
  128. package/build/__tests__/mock-data/items-mock-data.js +0 -370
  129. package/build/__tests__/mock-data/items-mock-data.js.map +0 -1
  130. package/build/__tests__/mock-data/notification-mock-data.d.ts +0 -55
  131. package/build/__tests__/mock-data/notification-mock-data.d.ts.map +0 -1
  132. package/build/__tests__/mock-data/notification-mock-data.js +0 -190
  133. package/build/__tests__/mock-data/notification-mock-data.js.map +0 -1
  134. package/build/__tests__/mock-data/project-epic-mock-data.d.ts +0 -45
  135. package/build/__tests__/mock-data/project-epic-mock-data.d.ts.map +0 -1
  136. package/build/__tests__/mock-data/project-epic-mock-data.js +0 -85
  137. package/build/__tests__/mock-data/project-epic-mock-data.js.map +0 -1
  138. package/build/__tests__/mock-data/tasks-mock-data.d.ts +0 -27
  139. package/build/__tests__/mock-data/tasks-mock-data.d.ts.map +0 -1
  140. package/build/__tests__/mock-data/tasks-mock-data.js +0 -104
  141. package/build/__tests__/mock-data/tasks-mock-data.js.map +0 -1
  142. package/build/__tests__/mock-data/utility-mock-data.d.ts +0 -19
  143. package/build/__tests__/mock-data/utility-mock-data.d.ts.map +0 -1
  144. package/build/__tests__/mock-data/utility-mock-data.js +0 -165
  145. package/build/__tests__/mock-data/utility-mock-data.js.map +0 -1
  146. package/build/__tests__/setup.d.ts +0 -8
  147. package/build/__tests__/setup.d.ts.map +0 -1
  148. package/build/__tests__/setup.js +0 -31
  149. package/build/__tests__/setup.js.map +0 -1
  150. package/build/__tests__/utils/test-helpers.d.ts +0 -110
  151. package/build/__tests__/utils/test-helpers.d.ts.map +0 -1
  152. package/build/__tests__/utils/test-helpers.js +0 -222
  153. package/build/__tests__/utils/test-helpers.js.map +0 -1
  154. package/build/cache/cache-test.d.ts +0 -9
  155. package/build/cache/cache-test.d.ts.map +0 -1
  156. package/build/cache/cache-test.js +0 -169
  157. package/build/cache/cache-test.js.map +0 -1
package/build/index.js CHANGED
@@ -5,9 +5,13 @@
5
5
  * This server provides natural language management of Podio items and tasks through Claude conversations.
6
6
  * It implements the MCP protocol to expose Podio operations as tools that can be called by AI assistants.
7
7
  *
8
- * @version 0.2.0 - Refactored with modular architecture
9
8
  * @author Podio MCP Team
10
9
  */
10
+ import { createRequire } from 'node:module';
11
+ import { realpathSync } from 'node:fs';
12
+ import { fileURLToPath } from 'node:url';
13
+ const require = createRequire(import.meta.url);
14
+ const pkg = require('../package.json');
11
15
  import { Server } from '@modelcontextprotocol/sdk/server/index.js';
12
16
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
13
17
  import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
@@ -16,8 +20,11 @@ import { PodioOAuthHelper } from './oauth-helper.js';
16
20
  import { PodioApiClient } from './api/podio-api-client.js';
17
21
  import { CacheManager } from './cache/cache-manager.js';
18
22
  import { toolDefinitions } from './tools/tool-definitions.js';
23
+ import { performClearAppCache, buildClearAppCacheMessage, } from './handlers/clear-app-cache.js';
19
24
  // Service layer
20
25
  import { ResponseFormatter, ItemService, TaskService, ProjectEpicService, AppStructureService, NotificationService, SearchService, CommentService, CodeExecutionService, } from './services/index.js';
26
+ // Build-time defaults (injected by CI, empty in dev)
27
+ import { BUILD_DEFAULTS } from './config/build-defaults.js';
21
28
  import { PodioErrorCode, PodioConfigError, PodioStructureError, PodioValidationError, isPodioError, PodioErrorFactory, } from './errors/index.js';
22
29
  /**
23
30
  * Refactored MCP server class that coordinates modular components.
@@ -64,17 +71,18 @@ class PodioMCPServer {
64
71
  * Sets up the MCP server with modular components and initializes
65
72
  * OAuth authentication and API client if credentials are available.
66
73
  *
67
- * Required environment variables:
68
- * - PODIO_CLIENT_ID: Your Podio app's client ID
69
- * - PODIO_CLIENT_SECRET: Your Podio app's client secret
70
- * - PODIO_REDIRECT_URI: OAuth redirect URI (typically http://localhost:8080/callback)
74
+ * Environment variables (runtime env vars override build-time defaults):
75
+ * - PODIO_CLIENT_ID: Your Podio app's client ID (baked into published package)
76
+ * - PODIO_REDIRECT_URI: OAuth redirect URI (defaults to http://localhost:8080/callback)
77
+ * - PODIO_CLIENT_SECRET: Your Podio app's client secret (omit for implicit OAuth flow)
71
78
  *
72
79
  * @constructor
73
80
  */
74
81
  constructor() {
75
82
  this.server = new Server({
76
83
  name: 'podio-mcp',
77
- version: '0.2.0',
84
+ version: pkg.version,
85
+ }, {
78
86
  capabilities: {
79
87
  tools: {},
80
88
  },
@@ -92,11 +100,11 @@ class PodioMCPServer {
92
100
  * @private
93
101
  */
94
102
  initializeAuthAndApi() {
95
- const clientId = process.env.PODIO_CLIENT_ID;
103
+ const clientId = process.env.PODIO_CLIENT_ID || BUILD_DEFAULTS.PODIO_CLIENT_ID;
96
104
  const clientSecret = process.env.PODIO_CLIENT_SECRET;
97
- const redirectUri = process.env.PODIO_REDIRECT_URI;
98
- if (!clientId || !clientSecret || !redirectUri) {
99
- console.error('WARNING: OAuth credentials not found in environment variables. Some functionality may be limited.');
105
+ const redirectUri = process.env.PODIO_REDIRECT_URI || BUILD_DEFAULTS.PODIO_REDIRECT_URI;
106
+ if (!clientId || !redirectUri) {
107
+ console.error('WARNING: PODIO_CLIENT_ID and PODIO_REDIRECT_URI are required (set env vars or use published package with baked defaults). Some functionality may be limited.');
100
108
  return;
101
109
  }
102
110
  try {
@@ -111,7 +119,12 @@ class PodioMCPServer {
111
119
  this.searchService = new SearchService(this.apiClient, this.cacheManager);
112
120
  this.commentService = new CommentService(this.apiClient, this.cacheManager);
113
121
  this.codeExecutionService = new CodeExecutionService(this.apiClient, this.cacheManager);
114
- console.error('✅ OAuth, API client, and services initialized successfully');
122
+ if (!clientSecret) {
123
+ console.error('✅ OAuth initialized with implicit flow (no client secret)');
124
+ }
125
+ else {
126
+ console.error('✅ OAuth, API client, and services initialized successfully');
127
+ }
115
128
  }
116
129
  catch (error) {
117
130
  console.error('❌ Failed to initialize OAuth/API client:', error);
@@ -142,12 +155,14 @@ class PodioMCPServer {
142
155
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
143
156
  }
144
157
  // Validate input schema
145
- const validation = toolDefinitions.validateToolSchema(name, args);
158
+ const toolArgs = args ?? {};
159
+ const validation = toolDefinitions.validateToolSchema(name, toolArgs);
146
160
  if (!validation.valid) {
147
161
  throw new McpError(ErrorCode.InvalidParams, `Invalid parameters for tool ${name}: ${validation.errors.join(', ')}`);
148
162
  }
149
163
  // Route to appropriate handler
150
- return await this.handleToolCall(name, args);
164
+ // biome-ignore lint/suspicious/noExplicitAny: MCP SDK handler expects a specific Zod-inferred type; our ToolResponse matches at runtime
165
+ return (await this.handleToolCall(name, toolArgs));
151
166
  }
152
167
  catch (error) {
153
168
  return this.handleToolError(name, error);
@@ -301,12 +316,57 @@ class PodioMCPServer {
301
316
  !this.notificationService ||
302
317
  !this.searchService ||
303
318
  !this.commentService) {
304
- throw PodioErrorFactory.authNotInitialized([
305
- 'PODIO_CLIENT_ID',
306
- 'PODIO_CLIENT_SECRET',
307
- 'PODIO_REDIRECT_URI',
308
- ]);
319
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID', 'PODIO_REDIRECT_URI']);
320
+ }
321
+ }
322
+ /** Returns the item service, throwing if not initialized. */
323
+ get items() {
324
+ if (!this.itemService) {
325
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
309
326
  }
327
+ return this.itemService;
328
+ }
329
+ /** Returns the task service, throwing if not initialized. */
330
+ get tasks() {
331
+ if (!this.taskService) {
332
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
333
+ }
334
+ return this.taskService;
335
+ }
336
+ /** Returns the app structure service, throwing if not initialized. */
337
+ get appStructures() {
338
+ if (!this.appStructureService) {
339
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
340
+ }
341
+ return this.appStructureService;
342
+ }
343
+ /** Returns the project/epic service, throwing if not initialized. */
344
+ get projectEpics() {
345
+ if (!this.projectEpicService) {
346
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
347
+ }
348
+ return this.projectEpicService;
349
+ }
350
+ /** Returns the notification service, throwing if not initialized. */
351
+ get notifications() {
352
+ if (!this.notificationService) {
353
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
354
+ }
355
+ return this.notificationService;
356
+ }
357
+ /** Returns the search service, throwing if not initialized. */
358
+ get searches() {
359
+ if (!this.searchService) {
360
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
361
+ }
362
+ return this.searchService;
363
+ }
364
+ /** Returns the comment service, throwing if not initialized. */
365
+ get comments() {
366
+ if (!this.commentService) {
367
+ throw PodioErrorFactory.authNotInitialized(['PODIO_CLIENT_ID']);
368
+ }
369
+ return this.commentService;
310
370
  }
311
371
  /**
312
372
  * Get the coordinate key for a given set of coordinates.
@@ -380,29 +440,37 @@ class PodioMCPServer {
380
440
  */
381
441
  async ensureAppStructureLoaded(args = {}) {
382
442
  this.ensureServicesAvailable();
383
- const coordinates = this.appStructureService.resolveAppCoordinates(args);
443
+ const forceRefresh = args.force_refresh;
444
+ const setAsActive = args.set_as_active;
445
+ const coordinates = this.appStructures.resolveAppCoordinates(args);
384
446
  if (!coordinates) {
385
447
  console.error('App coordinates not available - check environment variables or provide as arguments');
386
448
  return null;
387
449
  }
388
450
  const coordinateKey = this.getCoordinateKey(coordinates);
389
451
  // Check if already loaded and not forcing refresh
390
- if (!args.force_refresh && this.loadedApps.has(coordinateKey)) {
452
+ if (!forceRefresh && this.loadedApps.has(coordinateKey)) {
391
453
  // Set as active app if not already set
392
454
  if (!this.activeAppKey) {
393
455
  this.activeAppKey = coordinateKey;
394
456
  }
395
- return this.loadedApps.get(coordinateKey);
457
+ const cached = this.loadedApps.get(coordinateKey);
458
+ if (cached) {
459
+ return cached;
460
+ }
461
+ }
462
+ // Load the app structure (appStructureService is guaranteed non-null by ensureServicesAvailable)
463
+ if (!this.appStructureService) {
464
+ return null;
396
465
  }
397
- // Load the app structure
398
- const result = await this.appStructureService.loadAppStructure(coordinates, args.force_refresh);
466
+ const result = await this.appStructureService.loadAppStructure(coordinates, forceRefresh);
399
467
  // Store in the multi-app map
400
468
  this.loadedApps.set(coordinateKey, {
401
469
  structure: result.structure,
402
470
  fieldMapper: result.fieldMapper,
403
471
  });
404
472
  // Set as active app if this is the first app loaded or explicitly requested
405
- if (!this.activeAppKey || args.set_as_active) {
473
+ if (!this.activeAppKey || setAsActive) {
406
474
  this.activeAppKey = coordinateKey;
407
475
  }
408
476
  return result;
@@ -424,13 +492,13 @@ class PodioMCPServer {
424
492
  if (!loadedApp) {
425
493
  return ResponseFormatter.formatError('App structure could not be loaded. Please provide app coordinates (org_label, space_label, app_label) as arguments in your tool call.');
426
494
  }
427
- const coordinates = this.appStructureService.resolveAppCoordinates(args);
495
+ const coordinates = this.appStructures.resolveAppCoordinates(args);
428
496
  const cachedApp = coordinates
429
497
  ? await this.cacheManager.getAppByCoordinates(coordinates)
430
498
  : null;
431
- return ResponseFormatter.formatAppStructure(loadedApp.structure, coordinates, cachedApp || undefined, loadedApp.fieldMapper || undefined);
499
+ return ResponseFormatter.formatAppStructure(loadedApp.structure, coordinates ?? undefined, (cachedApp ?? undefined), loadedApp.fieldMapper || undefined);
432
500
  }
433
- catch (error) {
501
+ catch (_error) {
434
502
  throw PodioErrorFactory.structureNotLoaded('get app structure');
435
503
  }
436
504
  }
@@ -446,7 +514,7 @@ class PodioMCPServer {
446
514
  }
447
515
  this.ensureServicesAvailable();
448
516
  const coordinates = { org_label, space_label, app_label };
449
- await this.appStructureService.cacheAppStructure(coordinates);
517
+ await this.appStructures.cacheAppStructure(coordinates);
450
518
  return ResponseFormatter.formatSuccess(`Successfully cached app structure for ${app_label}!`);
451
519
  }
452
520
  /**
@@ -456,7 +524,7 @@ class PodioMCPServer {
456
524
  */
457
525
  async listCachedApps() {
458
526
  this.ensureServicesAvailable();
459
- const persistentCachedApps = await this.appStructureService.getAllCachedApps();
527
+ const persistentCachedApps = await this.appStructures.getAllCachedApps();
460
528
  // Add information about loaded apps in memory
461
529
  const loadedAppsInfo = Array.from(this.loadedApps.entries()).map(([key, app]) => ({
462
530
  coordinates: key,
@@ -480,8 +548,8 @@ class PodioMCPServer {
480
548
  */
481
549
  async refreshAppCache(args) {
482
550
  this.ensureServicesAvailable();
483
- const { app_id } = args;
484
- await this.appStructureService.refreshAppCache(app_id);
551
+ const app_id = args.app_id;
552
+ await this.appStructures.refreshAppCache(app_id);
485
553
  const message = app_id ? `Refreshed cache for app ID ${app_id}` : 'Refreshed all app caches';
486
554
  return ResponseFormatter.formatSuccess(message);
487
555
  }
@@ -507,6 +575,9 @@ class PodioMCPServer {
507
575
  }
508
576
  this.activeAppKey = coordinateKey;
509
577
  const app = this.loadedApps.get(coordinateKey);
578
+ if (!app) {
579
+ return ResponseFormatter.formatError(`App ${app_label} could not be retrieved from loaded apps.`);
580
+ }
510
581
  return ResponseFormatter.formatSuccess(`Active app set to: ${app.structure.config?.name || 'Unknown'} (${app_label}) with ${app.structure.fields.length} fields`);
511
582
  }
512
583
  /**
@@ -518,32 +589,16 @@ class PodioMCPServer {
518
589
  */
519
590
  async clearAppCache(args) {
520
591
  this.ensureServicesAvailable();
521
- const { app_id, org_label, space_label, app_label } = args;
522
- // Clear from persistent storage
523
- await this.appStructureService.clearAppCache(app_id);
524
- // Clear from memory if coordinates provided
525
- if (org_label && space_label && app_label) {
526
- const coordinateKey = this.getCoordinateKey({ org_label, space_label, app_label });
527
- if (this.loadedApps.has(coordinateKey)) {
528
- this.loadedApps.delete(coordinateKey);
529
- // Reset active app if it was the one cleared
530
- if (this.activeAppKey === coordinateKey) {
531
- this.activeAppKey =
532
- this.loadedApps.size > 0 ? (this.loadedApps.keys().next().value ?? null) : null;
533
- }
534
- }
535
- }
536
- else if (!app_id) {
537
- // Clear all from memory if no specific app specified
538
- this.loadedApps.clear();
539
- this.activeAppKey = null;
540
- }
541
- const message = app_id
542
- ? `Cleared cache for app ID ${app_id}`
543
- : org_label && space_label && app_label
544
- ? `Cleared cache for ${app_label} in ${space_label}/${org_label}`
545
- : 'Cleared all app caches';
546
- return ResponseFormatter.formatSuccess(message);
592
+ const { app_id, coordinates } = await performClearAppCache({
593
+ appStructures: this.appStructures,
594
+ loadedApps: this.loadedApps,
595
+ getActiveAppKey: () => this.activeAppKey,
596
+ setActiveAppKey: (key) => {
597
+ this.activeAppKey = key;
598
+ },
599
+ getCoordinateKey: (c) => this.getCoordinateKey(c),
600
+ }, args);
601
+ return ResponseFormatter.formatSuccess(buildClearAppCacheMessage(app_id, coordinates));
547
602
  }
548
603
  // =================
549
604
  // ITEM OPERATIONS
@@ -559,8 +614,13 @@ class PodioMCPServer {
559
614
  async listItems(args) {
560
615
  const { status_filter, responsible_filter, limit = 20, org_label, space_label, app_label, } = args;
561
616
  const appContext = await this.getAppContextForOperation(args, 'list items');
562
- const coordinates = this.appStructureService.resolveAppCoordinates(org_label && space_label && app_label ? { org_label, space_label, app_label } : {});
563
- const result = await this.itemService.listItems(appContext.structure.app_id, appContext.fieldMapper, { status_filter, responsible_filter, limit }, coordinates || undefined);
617
+ const coordinates = this.appStructureService?.resolveAppCoordinates(org_label && space_label && app_label
618
+ ? { org_label, space_label, app_label }
619
+ : {});
620
+ if (!this.itemService) {
621
+ return ResponseFormatter.formatError('Item service is not available.');
622
+ }
623
+ const result = await this.itemService.listItems(appContext.structure.app_id, appContext.fieldMapper, { status_filter, responsible_filter, limit }, coordinates ?? undefined);
564
624
  return ResponseFormatter.formatItemsList(result.items, result.filteredItems, appContext.fieldMapper, responsible_filter);
565
625
  }
566
626
  /**
@@ -574,8 +634,13 @@ class PodioMCPServer {
574
634
  async createItem(args) {
575
635
  const { title, description, status, responsible, project, epic, org_label, space_label, app_label, } = args;
576
636
  const appContext = await this.getAppContextForOperation(args, 'create item');
577
- const coordinates = this.appStructureService.resolveAppCoordinates(org_label && space_label && app_label ? { org_label, space_label, app_label } : {});
578
- const newItem = await this.itemService.createItem(appContext.structure.app_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, coordinates || undefined);
637
+ const coordinates = this.appStructureService?.resolveAppCoordinates(org_label && space_label && app_label
638
+ ? { org_label, space_label, app_label }
639
+ : {});
640
+ if (!this.itemService) {
641
+ return ResponseFormatter.formatError('Item service is not available.');
642
+ }
643
+ const newItem = await this.itemService.createItem(appContext.structure.app_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, coordinates ?? undefined);
579
644
  return ResponseFormatter.formatItemCreated(newItem, appContext.fieldMapper);
580
645
  }
581
646
  /**
@@ -591,8 +656,10 @@ class PodioMCPServer {
591
656
  throw PodioValidationError.requiredField('item_id', 'update item');
592
657
  }
593
658
  const appContext = await this.getAppContextForOperation(args, 'update item');
594
- const coordinates = this.appStructureService.resolveAppCoordinates(org_label && space_label && app_label ? { org_label, space_label, app_label } : {});
595
- await this.itemService.updateItem(item_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, appContext.structure.app_id, coordinates || undefined);
659
+ const coordinates = this.appStructures.resolveAppCoordinates(org_label && space_label && app_label
660
+ ? { org_label, space_label, app_label }
661
+ : {});
662
+ await this.items.updateItem(item_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, appContext.structure.app_id, coordinates ?? undefined);
596
663
  return ResponseFormatter.formatSuccess(`Successfully updated item ${item_id}!`);
597
664
  }
598
665
  /**
@@ -604,11 +671,11 @@ class PodioMCPServer {
604
671
  */
605
672
  async deleteItem(args) {
606
673
  this.ensureServicesAvailable();
607
- const { item_id } = args;
674
+ const item_id = args.item_id;
608
675
  if (!item_id) {
609
676
  throw PodioValidationError.requiredField('item_id', 'delete item');
610
677
  }
611
- await this.itemService.deleteItem(item_id);
678
+ await this.items.deleteItem(item_id);
612
679
  return ResponseFormatter.formatSuccess(`Successfully deleted item ${item_id}!`);
613
680
  }
614
681
  /**
@@ -621,14 +688,14 @@ class PodioMCPServer {
621
688
  async getItemDetails(args) {
622
689
  // Don't call ensureAppStructureLoaded here - it should already be loaded
623
690
  this.ensureServicesAvailable();
624
- const { item_id } = args;
691
+ const item_id = args.item_id;
625
692
  if (!item_id) {
626
693
  throw PodioValidationError.requiredField('item_id', 'get item details');
627
694
  }
628
695
  // Use active app for field mapper if available
629
696
  const activeApp = this.getActiveApp();
630
697
  try {
631
- const item = await this.itemService.getItem(item_id);
698
+ const item = await this.items.getItem(item_id);
632
699
  // If we have a field mapper, use it for rich formatting
633
700
  if (activeApp?.fieldMapper) {
634
701
  return ResponseFormatter.formatItemDetails(item, activeApp.fieldMapper);
@@ -651,7 +718,8 @@ class PodioMCPServer {
651
718
  }
652
719
  catch (error) {
653
720
  // Add helpful error message for 404
654
- if (error.status === 404 || error.message?.includes('404')) {
721
+ const errObj = error;
722
+ if (errObj.status === 404 || errObj.message?.includes('404')) {
655
723
  throw new Error(`Item with global ID ${item_id} not found. If this is a ticket/item number, use get_item_by_app_item_id instead.`);
656
724
  }
657
725
  throw error;
@@ -665,12 +733,12 @@ class PodioMCPServer {
665
733
  * @returns MCP tool response with detailed item information
666
734
  */
667
735
  async getItemByAppItemId(args) {
668
- const { app_item_id } = args;
736
+ const app_item_id = args.app_item_id;
669
737
  if (!app_item_id) {
670
738
  throw PodioValidationError.requiredField('app_item_id', 'get item by app item ID');
671
739
  }
672
740
  const appContext = await this.getAppContextForOperation(args, 'get item by app item ID');
673
- const item = await this.itemService.getItemByAppItemId(appContext.structure.app_id, app_item_id);
741
+ const item = await this.items.getItemByAppItemId(appContext.structure.app_id, app_item_id);
674
742
  return ResponseFormatter.formatItemDetails(item, appContext.fieldMapper);
675
743
  }
676
744
  /**
@@ -687,10 +755,12 @@ class PodioMCPServer {
687
755
  }
688
756
  const appContext = await this.getAppContextForOperation(args, 'update item by app item ID');
689
757
  // First get the item to get its global ID
690
- const item = await this.itemService.getItemByAppItemId(appContext.structure.app_id, app_item_id);
758
+ const item = await this.items.getItemByAppItemId(appContext.structure.app_id, app_item_id);
691
759
  // Then update using the global ID
692
- const coordinates = this.appStructureService.resolveAppCoordinates(org_label && space_label && app_label ? { org_label, space_label, app_label } : {});
693
- await this.itemService.updateItem(item.item_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, appContext.structure.app_id, coordinates || undefined);
760
+ const coordinates = this.appStructures.resolveAppCoordinates(org_label && space_label && app_label
761
+ ? { org_label, space_label, app_label }
762
+ : {});
763
+ await this.items.updateItem(item.item_id, appContext.fieldMapper, { title, description, status, responsible, project, epic }, appContext.structure.app_id, coordinates ?? undefined);
694
764
  return {
695
765
  content: [
696
766
  {
@@ -710,15 +780,15 @@ class PodioMCPServer {
710
780
  async deleteItemByAppItemId(args) {
711
781
  // Don't call ensureAppStructureLoaded here - it should already be loaded
712
782
  this.ensureServicesAvailable();
713
- const { app_item_id } = args;
783
+ const app_item_id = args.app_item_id;
714
784
  if (!app_item_id) {
715
785
  throw PodioValidationError.requiredField('app_item_id', 'delete item by app item ID');
716
786
  }
717
787
  const appContext = await this.getAppContextForOperation(args, 'delete item by app item ID');
718
788
  // First get the item to get its global ID
719
- const item = await this.itemService.getItemByAppItemId(appContext.structure.app_id, app_item_id);
789
+ const item = await this.items.getItemByAppItemId(appContext.structure.app_id, app_item_id);
720
790
  // Then delete using the global ID
721
- await this.itemService.deleteItem(item.item_id);
791
+ await this.items.deleteItem(item.item_id);
722
792
  return {
723
793
  content: [
724
794
  {
@@ -740,14 +810,14 @@ class PodioMCPServer {
740
810
  */
741
811
  async listTasks(args) {
742
812
  this.ensureServicesAvailable();
743
- const { assigned_to, status, limit = 20 } = args;
813
+ const { assigned_to, status, limit = 20, } = args;
744
814
  // Get space ID for task filtering (if available)
745
815
  let spaceId;
746
816
  const activeApp = this.getActiveApp();
747
- if (activeApp && activeApp.structure.space_id) {
817
+ if (activeApp?.structure.space_id) {
748
818
  spaceId = activeApp.structure.space_id;
749
819
  }
750
- const tasks = await this.taskService.listTasks({ assigned_to, status, limit }, spaceId);
820
+ const tasks = await this.tasks.listTasks({ assigned_to, status, limit }, spaceId);
751
821
  return ResponseFormatter.formatTasksList(tasks);
752
822
  }
753
823
  /**
@@ -760,8 +830,8 @@ class PodioMCPServer {
760
830
  async createTask(args) {
761
831
  this.ensureServicesAvailable();
762
832
  const { text, description, due_date, assigned_to, ref_type, ref_id } = args;
763
- const newTask = await this.taskService.createTask({
764
- text,
833
+ const newTask = await this.tasks.createTask({
834
+ text: text,
765
835
  description,
766
836
  due_date,
767
837
  assigned_to,
@@ -780,8 +850,8 @@ class PodioMCPServer {
780
850
  async createTaskForItem(args) {
781
851
  this.ensureServicesAvailable();
782
852
  const { item_id, text, description, due_date, assigned_to } = args;
783
- const newTask = await this.taskService.createTaskForItem(item_id, {
784
- text,
853
+ const newTask = await this.tasks.createTaskForItem(item_id, {
854
+ text: text,
785
855
  description,
786
856
  due_date,
787
857
  assigned_to,
@@ -798,7 +868,7 @@ class PodioMCPServer {
798
868
  async updateTask(args) {
799
869
  this.ensureServicesAvailable();
800
870
  const { task_id, text, description, due_date, completed } = args;
801
- const updatedTask = await this.taskService.updateTask(task_id, {
871
+ const updatedTask = await this.tasks.updateTask(task_id, {
802
872
  text,
803
873
  description,
804
874
  due_date,
@@ -815,8 +885,8 @@ class PodioMCPServer {
815
885
  */
816
886
  async deleteTask(args) {
817
887
  this.ensureServicesAvailable();
818
- const { task_id } = args;
819
- await this.taskService.deleteTask(task_id);
888
+ const task_id = args.task_id;
889
+ await this.tasks.deleteTask(task_id);
820
890
  return ResponseFormatter.formatSuccess(`Successfully deleted task ${task_id}!`);
821
891
  }
822
892
  /**
@@ -828,8 +898,8 @@ class PodioMCPServer {
828
898
  */
829
899
  async getTaskDetails(args) {
830
900
  this.ensureServicesAvailable();
831
- const { task_id } = args;
832
- const task = await this.taskService.getTaskDetails(task_id);
901
+ const task_id = args.task_id;
902
+ const task = await this.tasks.getTaskDetails(task_id);
833
903
  return ResponseFormatter.formatTaskDetails(task);
834
904
  }
835
905
  // =================
@@ -845,8 +915,8 @@ class PodioMCPServer {
845
915
  async listProjects(args) {
846
916
  this.ensureServicesAvailable();
847
917
  const appContext = await this.getAppContextForOperation(args, 'list projects');
848
- const { refresh_cache = false } = args;
849
- const projects = await this.projectEpicService.listProjects(appContext.structure.app_id, appContext.fieldMapper, refresh_cache);
918
+ const refresh_cache = args.refresh_cache ?? false;
919
+ const projects = await this.projectEpics.listProjects(appContext.structure.app_id, appContext.fieldMapper, refresh_cache);
850
920
  return ResponseFormatter.formatProjectEpicList(projects, 'Projects');
851
921
  }
852
922
  /**
@@ -859,8 +929,8 @@ class PodioMCPServer {
859
929
  async listEpics(args) {
860
930
  this.ensureServicesAvailable();
861
931
  const appContext = await this.getAppContextForOperation(args, 'list epics');
862
- const { refresh_cache = false } = args;
863
- const epics = await this.projectEpicService.listEpics(appContext.structure.app_id, appContext.fieldMapper, refresh_cache);
932
+ const refresh_cache = args.refresh_cache ?? false;
933
+ const epics = await this.projectEpics.listEpics(appContext.structure.app_id, appContext.fieldMapper, refresh_cache);
864
934
  return ResponseFormatter.formatProjectEpicList(epics, 'Epics');
865
935
  }
866
936
  /**
@@ -926,12 +996,13 @@ class PodioMCPServer {
926
996
  */
927
997
  async suggestProjectEpic(args) {
928
998
  this.ensureServicesAvailable();
929
- const { title, description = '' } = args;
999
+ const title = args.title;
1000
+ const description = args.description ?? '';
930
1001
  if (!title) {
931
1002
  throw PodioValidationError.requiredField('title', 'suggest project epic');
932
1003
  }
933
1004
  const activeApp = this.getActiveApp();
934
- const suggestions = await this.projectEpicService.getSuggestions(title, description, activeApp?.structure.app_id);
1005
+ const suggestions = await this.projectEpics.getSuggestions(title, description, activeApp?.structure.app_id);
935
1006
  return ResponseFormatter.formatProjectEpicSuggestions(title, suggestions.projects, suggestions.epics);
936
1007
  }
937
1008
  // =================
@@ -946,7 +1017,7 @@ class PodioMCPServer {
946
1017
  */
947
1018
  async inspectFieldStructure(args) {
948
1019
  const appContext = await this.getAppContextForOperation(args, 'inspect field structure');
949
- const { field_name } = args;
1020
+ const field_name = args.field_name;
950
1021
  return ResponseFormatter.formatFieldStructure(appContext.structure, appContext.fieldMapper, field_name);
951
1022
  }
952
1023
  /**
@@ -959,7 +1030,7 @@ class PodioMCPServer {
959
1030
  async listSpaceMembers(args) {
960
1031
  await this.ensureAppStructureLoaded();
961
1032
  this.ensureServicesAvailable();
962
- const { refresh_cache = false } = args;
1033
+ const refresh_cache = args.refresh_cache ?? false;
963
1034
  const activeApp = this.getActiveApp();
964
1035
  if (!activeApp || !activeApp.structure.space_id) {
965
1036
  throw PodioStructureError.notLoaded('Space information not available');
@@ -971,7 +1042,7 @@ class PodioMCPServer {
971
1042
  }
972
1043
  else {
973
1044
  // Fetch members from API
974
- members = await this.apiClient.getSpaceMembers(spaceId);
1045
+ members = (await this.apiClient?.getSpaceMembers(spaceId)) ?? [];
975
1046
  await this.cacheManager.setSpaceMembers(spaceId, members);
976
1047
  }
977
1048
  return ResponseFormatter.formatSpaceMembersList(members);
@@ -1001,12 +1072,18 @@ class PodioMCPServer {
1001
1072
  app_id,
1002
1073
  };
1003
1074
  // Remove undefined and null values
1004
- Object.keys(filters).forEach((key) => filters[key] == null && delete filters[key]);
1005
- const response = await this.notificationService.listNotifications(filters);
1075
+ for (const key of Object.keys(filters)) {
1076
+ if (filters[key] == null) {
1077
+ delete filters[key];
1078
+ }
1079
+ }
1080
+ const response = await this.notifications.listNotifications(filters);
1006
1081
  // Filter notifications if specific criteria are requested
1007
1082
  let filteredNotifications = response.notifications;
1008
1083
  if (viewed === false) {
1009
- filteredNotifications = this.notificationService.filterNotifications(response.notifications, { unreadOnly: true });
1084
+ filteredNotifications = this.notifications.filterNotifications(response.notifications, {
1085
+ unreadOnly: true,
1086
+ });
1010
1087
  }
1011
1088
  return ResponseFormatter.formatNotificationsList(response.notifications, filteredNotifications, response.total, viewed === false);
1012
1089
  }
@@ -1019,11 +1096,11 @@ class PodioMCPServer {
1019
1096
  */
1020
1097
  async getNotificationDetails(args) {
1021
1098
  this.ensureServicesAvailable();
1022
- const { notification_id } = args;
1099
+ const notification_id = args.notification_id;
1023
1100
  if (!notification_id) {
1024
1101
  throw PodioValidationError.requiredField('notification_id', 'get notification details');
1025
1102
  }
1026
- const notification = await this.notificationService.getNotification(notification_id);
1103
+ const notification = await this.notifications.getNotification(notification_id);
1027
1104
  return ResponseFormatter.formatNotificationDetails(notification);
1028
1105
  }
1029
1106
  /**
@@ -1033,9 +1110,9 @@ class PodioMCPServer {
1033
1110
  * @param args - Empty arguments object
1034
1111
  * @returns MCP tool response with unread count information
1035
1112
  */
1036
- async getUnreadCount(args) {
1113
+ async getUnreadCount(_args) {
1037
1114
  this.ensureServicesAvailable();
1038
- const count = await this.notificationService.getUnreadCount();
1115
+ const count = await this.notifications.getUnreadCount();
1039
1116
  return ResponseFormatter.formatUnreadCount(count);
1040
1117
  }
1041
1118
  /**
@@ -1045,9 +1122,9 @@ class PodioMCPServer {
1045
1122
  * @param args - Empty arguments object
1046
1123
  * @returns MCP tool response with notification settings
1047
1124
  */
1048
- async getNotificationSettings(args) {
1125
+ async getNotificationSettings(_args) {
1049
1126
  this.ensureServicesAvailable();
1050
- const settings = await this.notificationService.getNotificationSettings();
1127
+ const settings = await this.notifications.getNotificationSettings();
1051
1128
  return ResponseFormatter.formatNotificationSettings(settings);
1052
1129
  }
1053
1130
  // =================
@@ -1099,11 +1176,11 @@ class PodioMCPServer {
1099
1176
  };
1100
1177
  try {
1101
1178
  if (group_results) {
1102
- const groupedResults = await this.searchService.searchWithGrouping(filters, context);
1179
+ const groupedResults = await this.searches.searchWithGrouping(filters, context);
1103
1180
  return ResponseFormatter.formatGroupedSearchResults(groupedResults);
1104
1181
  }
1105
1182
  else {
1106
- const searchResponse = await this.searchService.search(filters, context);
1183
+ const searchResponse = await this.searches.search(filters, context);
1107
1184
  return ResponseFormatter.formatSearchResults(searchResponse);
1108
1185
  }
1109
1186
  }
@@ -1123,7 +1200,7 @@ class PodioMCPServer {
1123
1200
  */
1124
1201
  async searchInApp(args) {
1125
1202
  this.ensureServicesAvailable();
1126
- const { query, app_id, type, limit = 20, offset = 0, fields } = args;
1203
+ const { query, app_id, type, limit = 20, offset = 0, fields, } = args;
1127
1204
  if (!query || query.trim().length === 0) {
1128
1205
  throw PodioValidationError.requiredField('query', 'search in app');
1129
1206
  }
@@ -1143,7 +1220,7 @@ class PodioMCPServer {
1143
1220
  searchFields = fields.split(',').map((f) => f.trim());
1144
1221
  }
1145
1222
  try {
1146
- const searchResponse = await this.searchService.searchInApp(targetAppId, query, {
1223
+ const searchResponse = await this.searches.searchInApp(targetAppId, query, {
1147
1224
  type: searchTypes,
1148
1225
  limit,
1149
1226
  offset,
@@ -1167,7 +1244,7 @@ class PodioMCPServer {
1167
1244
  */
1168
1245
  async searchInSpace(args) {
1169
1246
  this.ensureServicesAvailable();
1170
- const { query, space_id, type, limit = 20, offset = 0, fields } = args;
1247
+ const { query, space_id, type, limit = 20, offset = 0, fields, } = args;
1171
1248
  if (!query || query.trim().length === 0) {
1172
1249
  throw PodioValidationError.requiredField('query', 'search in space');
1173
1250
  }
@@ -1187,7 +1264,7 @@ class PodioMCPServer {
1187
1264
  searchFields = fields.split(',').map((f) => f.trim());
1188
1265
  }
1189
1266
  try {
1190
- const searchResponse = await this.searchService.searchInSpace(targetSpaceId, query, {
1267
+ const searchResponse = await this.searches.searchInSpace(targetSpaceId, query, {
1191
1268
  type: searchTypes,
1192
1269
  limit,
1193
1270
  offset,
@@ -1211,9 +1288,9 @@ class PodioMCPServer {
1211
1288
  */
1212
1289
  async getSearchHistory(args) {
1213
1290
  this.ensureServicesAvailable();
1214
- const { limit = 10 } = args;
1291
+ const limit = args.limit ?? 10;
1215
1292
  try {
1216
- const recentSearches = await this.searchService.getRecentSearches(limit);
1293
+ const recentSearches = await this.searches.getRecentSearches(limit);
1217
1294
  return ResponseFormatter.formatSearchHistory(recentSearches);
1218
1295
  }
1219
1296
  catch (error) {
@@ -1230,10 +1307,10 @@ class PodioMCPServer {
1230
1307
  * @param args - Empty arguments object
1231
1308
  * @returns MCP tool response with success confirmation
1232
1309
  */
1233
- async clearSearchHistory(args) {
1310
+ async clearSearchHistory(_args) {
1234
1311
  this.ensureServicesAvailable();
1235
1312
  try {
1236
- await this.searchService.clearSearchHistory();
1313
+ await this.searches.clearSearchHistory();
1237
1314
  return ResponseFormatter.formatSuccess('Search history cleared successfully!');
1238
1315
  }
1239
1316
  catch (error) {
@@ -1255,11 +1332,11 @@ class PodioMCPServer {
1255
1332
  */
1256
1333
  async listItemComments(args) {
1257
1334
  this.ensureServicesAvailable();
1258
- const { item_id } = args;
1335
+ const item_id = args.item_id;
1259
1336
  if (!item_id) {
1260
1337
  throw PodioValidationError.requiredField('item_id', 'list item comments');
1261
1338
  }
1262
- const comments = await this.commentService.listItemComments(item_id);
1339
+ const comments = await this.comments.listItemComments(item_id);
1263
1340
  return ResponseFormatter.formatItemCommentsList(comments);
1264
1341
  }
1265
1342
  /**
@@ -1278,7 +1355,7 @@ class PodioMCPServer {
1278
1355
  if (!text) {
1279
1356
  throw PodioValidationError.requiredField('text', 'create item comment');
1280
1357
  }
1281
- const comment = await this.commentService.createItemComment(item_id, text);
1358
+ const comment = await this.comments.createItemComment(item_id, text);
1282
1359
  return ResponseFormatter.formatCommentCreated(comment);
1283
1360
  }
1284
1361
  /**
@@ -1290,11 +1367,11 @@ class PodioMCPServer {
1290
1367
  */
1291
1368
  async getCommentDetails(args) {
1292
1369
  this.ensureServicesAvailable();
1293
- const { comment_id } = args;
1370
+ const comment_id = args.comment_id;
1294
1371
  if (!comment_id) {
1295
1372
  throw PodioValidationError.requiredField('comment_id', 'get comment details');
1296
1373
  }
1297
- const comment = await this.commentService.getComment(comment_id);
1374
+ const comment = await this.comments.getComment(comment_id);
1298
1375
  return ResponseFormatter.formatCommentDetails(comment);
1299
1376
  }
1300
1377
  /**
@@ -1313,7 +1390,7 @@ class PodioMCPServer {
1313
1390
  if (!text) {
1314
1391
  throw PodioValidationError.requiredField('text', 'update comment');
1315
1392
  }
1316
- await this.commentService.updateComment(comment_id, text);
1393
+ await this.comments.updateComment(comment_id, text);
1317
1394
  return ResponseFormatter.formatSuccess(`Successfully updated comment ${comment_id}!`);
1318
1395
  }
1319
1396
  /**
@@ -1325,11 +1402,11 @@ class PodioMCPServer {
1325
1402
  */
1326
1403
  async deleteComment(args) {
1327
1404
  this.ensureServicesAvailable();
1328
- const { comment_id } = args;
1405
+ const comment_id = args.comment_id;
1329
1406
  if (!comment_id) {
1330
1407
  throw PodioValidationError.requiredField('comment_id', 'delete comment');
1331
1408
  }
1332
- await this.commentService.deleteComment(comment_id);
1409
+ await this.comments.deleteComment(comment_id);
1333
1410
  return ResponseFormatter.formatSuccess(`Successfully deleted comment ${comment_id}!`);
1334
1411
  }
1335
1412
  /**
@@ -1341,11 +1418,11 @@ class PodioMCPServer {
1341
1418
  */
1342
1419
  async listItemActivity(args) {
1343
1420
  this.ensureServicesAvailable();
1344
- const { item_id } = args;
1421
+ const item_id = args.item_id;
1345
1422
  if (!item_id) {
1346
1423
  throw PodioValidationError.requiredField('item_id', 'list item activity');
1347
1424
  }
1348
- const activity = await this.itemService.getItemActivity(item_id);
1425
+ const activity = await this.items.getItemActivity(item_id);
1349
1426
  return ResponseFormatter.formatItemActivity(activity);
1350
1427
  }
1351
1428
  /**
@@ -1364,7 +1441,7 @@ class PodioMCPServer {
1364
1441
  if (!revision_id) {
1365
1442
  throw PodioValidationError.requiredField('revision_id', 'get item revision');
1366
1443
  }
1367
- const revision = await this.itemService.getItemRevision(item_id, revision_id);
1444
+ const revision = await this.items.getItemRevision(item_id, revision_id);
1368
1445
  return ResponseFormatter.formatItemRevisionDetails(revision);
1369
1446
  }
1370
1447
  /**
@@ -1386,7 +1463,7 @@ class PodioMCPServer {
1386
1463
  if (!to_revision) {
1387
1464
  throw PodioValidationError.requiredField('to_revision', 'get item revision diff');
1388
1465
  }
1389
- const diff = await this.itemService.getItemRevisionDiff(item_id, from_revision, to_revision);
1466
+ const diff = await this.items.getItemRevisionDiff(item_id, from_revision, to_revision);
1390
1467
  return ResponseFormatter.formatItemRevisionDiff(diff);
1391
1468
  }
1392
1469
  // ============================================================================
@@ -1493,11 +1570,23 @@ class PodioMCPServer {
1493
1570
  }
1494
1571
  }
1495
1572
  // Run the server if this file is executed directly
1496
- if (import.meta.url === `file://${process.argv[1]}`) {
1573
+ // Use realpath to handle symlinks (e.g., when run via npx/bunx)
1574
+ const isMainModule = (() => {
1575
+ try {
1576
+ const scriptPath = realpathSync(process.argv[1]);
1577
+ const modulePath = fileURLToPath(import.meta.url);
1578
+ return scriptPath === modulePath;
1579
+ }
1580
+ catch {
1581
+ // Fallback to simple comparison if realpath fails
1582
+ return import.meta.url === `file://${process.argv[1]}`;
1583
+ }
1584
+ })();
1585
+ if (isMainModule) {
1497
1586
  // Handle command line arguments
1498
1587
  if (process.argv.includes('--help') || process.argv.includes('-h')) {
1499
1588
  console.log(`
1500
- Podio MCP Server v0.2.0
1589
+ Podio MCP Server v${pkg.version}
1501
1590
 
1502
1591
  A Model Context Protocol server for integrating Podio with AI assistants.
1503
1592
 
@@ -1507,7 +1596,7 @@ Usage:
1507
1596
 
1508
1597
  Environment Variables:
1509
1598
  PODIO_CLIENT_ID Podio app client ID (required)
1510
- PODIO_CLIENT_SECRET Podio app client secret (required)
1599
+ PODIO_CLIENT_SECRET Podio app client secret (optional; omit for implicit OAuth flow)
1511
1600
  PODIO_REDIRECT_URI OAuth redirect URI (required)
1512
1601
 
1513
1602
  Note: App coordinates (org_label, space_label, app_label) must be provided