@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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Forum Virium Helsinki
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,491 @@
1
+ # Podio MCP Server
2
+
3
+ A Model Context Protocol (MCP) server that integrates Podio with Claude Desktop, allowing you to manage Podio items and tasks directly through natural language conversations with Claude.
4
+
5
+ ## Features
6
+
7
+ - **🔐 Seamless Authentication**: Automatic OAuth2 flow with token storage and refresh
8
+ - **⚡ Intelligent Caching**: Persistent app structure caching for lightning-fast operations
9
+ - **📋 Item Management**: Create, read, update, and delete Podio items
10
+ - **✅ Task Management**: List and manage Podio tasks with full CRUD operations
11
+ - **📬 Notification Management**: Read and filter Podio notifications with detailed views
12
+ - **🎯 Smart Project/Epic Suggestions**: AI-powered matching for project and epic assignments with cache optimization
13
+ - **🔍 Smart Filtering**: Filter items by status, responsible person, and more
14
+ - **🏗️ Dynamic App Structure**: Automatically discovers your app's fields and configuration with persistent caching
15
+ - **🔄 Cross-App References**: Handles complex app relationships and field configurations
16
+ - **🛠️ Cache Management**: Full suite of tools for managing cached app structures
17
+ - **🔧 Auto-Recovery**: Automatic cache refresh when API structure mismatches are detected
18
+ - **💬 Natural Language Interface**: Use conversational commands instead of API syntax
19
+ - **🔄 Auto-refresh**: Handles token expiration automatically
20
+
21
+ ## Documentation
22
+
23
+ 📚 **Complete Documentation** is available online:
24
+
25
+ - **[📖 Live Documentation](https://forumviriumhelsinki.github.io/podio-mcp/)** - Complete API reference and guides
26
+ - **[🚀 Setup Guide](docs/setup-guide.md)** - Detailed installation and configuration
27
+ - **[💡 Usage Examples](docs/usage-examples.md)** - Real-world usage patterns and examples
28
+ - **[🔔 Notifications Guide](docs/NOTIFICATIONS.md)** - Comprehensive notification management
29
+ - **[🏗️ API Documentation](docs/API_DOCUMENTATION.md)** - Architecture and API details
30
+ - **[🧪 Cache Integration Example](docs/cache-integration-example.md)** - Advanced caching strategies
31
+
32
+ > 💡 **Tip**: The live documentation is automatically updated with each release and includes interactive examples!
33
+
34
+ ## Quick Start
35
+
36
+ ### 1. Prerequisites
37
+
38
+ - Bun runtime (or Node.js 18 or higher)
39
+ - Claude Desktop application
40
+ - Podio account with API access
41
+
42
+ ### 2. Installation
43
+
44
+ #### Option 1: Direct bunx Install (Recommended)
45
+
46
+ Install directly from npm using bunx:
47
+
48
+ ```bash
49
+ # Install from npm (no build required)
50
+ bunx @forumviriumhelsinki/podio-mcp
51
+ ```
52
+
53
+ This will automatically download the latest version and make the server available for configuration.
54
+
55
+ > **Note**: You can use either `bunx @forumviriumhelsinki/podio-mcp` (full package name) or `bunx podio-mcp` (bin name) - both work identically. This documentation uses the full package name for clarity.
56
+
57
+ #### Option 2: Local Development Setup
58
+
59
+ For development or customization:
60
+
61
+ ```bash
62
+ # Clone the repository
63
+ git clone https://github.com/ForumViriumHelsinki/podio-mcp.git
64
+ cd podio-mcp
65
+
66
+ # Install dependencies
67
+ bun install
68
+
69
+ # Build the project
70
+ bun run build
71
+ ```
72
+
73
+ ### 3. Configure Claude Desktop
74
+
75
+ #### Option 1: Use bunx with Configuration Generator (Recommended)
76
+
77
+ For local development, you can use the configuration generator to automatically set up Claude Desktop:
78
+
79
+ ```bash
80
+ # From local clone
81
+ bun run configure
82
+ ```
83
+
84
+ > **Note**: When using the published npm package, the configure script is available at `node_modules/@forumviriumhelsinki/podio-mcp/scripts/generate-claude-config.js`, but it's designed for local development workflows. For bunx users, manual configuration (Option 2 below) is recommended.
85
+
86
+ This script will:
87
+
88
+ - Detect your Node.js installation path
89
+ - Find the correct path to the compiled index.js
90
+ - Generate a properly formatted configuration for Claude Desktop
91
+ - Provide step-by-step instructions for installation
92
+
93
+ #### Option 2: Manual Configuration
94
+
95
+ Edit your Claude Desktop configuration file:
96
+
97
+ **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
98
+ **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
99
+
100
+ **For bunx installation:**
101
+
102
+ ```json
103
+ {
104
+ "mcpServers": {
105
+ "podio": {
106
+ "command": "bunx",
107
+ "args": ["@forumviriumhelsinki/podio-mcp"],
108
+ "env": {
109
+ "PODIO_CLIENT_ID": "your_client_id_here",
110
+ "PODIO_CLIENT_SECRET": "your_client_secret_here",
111
+ "PODIO_REDIRECT_URI": "http://localhost:8080/callback"
112
+ }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ **For local development:**
119
+
120
+ Use the configuration generator for easy setup:
121
+
122
+ ```bash
123
+ # From local clone
124
+ bun run configure
125
+ ```
126
+
127
+ This script will generate the proper configuration with correct paths for your system.
128
+
129
+ ### 4. Get Podio API Credentials
130
+
131
+ 1. Go to [Podio Developers](https://developers.podio.com/api-key)
132
+ 2. Create a new API key
133
+ 3. Configure redirect URIs:
134
+ - Primary: `http://localhost:8080/callback`
135
+ - For automatic fallback support, also add these as valid redirect URIs in your Podio app:
136
+ - `http://localhost:8090/callback`
137
+ - `http://localhost:8100/callback`
138
+ - `http://localhost:8888/callback`
139
+ - `http://localhost:9090/callback`
140
+ - The server will automatically try these ports in order if port 8080 is in use
141
+ - Alternatively, you can configure a single custom port and ensure it's available
142
+ 4. Note your Client ID and Client Secret
143
+
144
+ ### 5. Understanding App Coordinates
145
+
146
+ When using the server, you'll need to provide app coordinates (org_label, space_label, app_label) in your tool calls.
147
+
148
+ Navigate to your Podio app in the browser to find these coordinates. The URL will look like:
149
+
150
+ ```
151
+ https://podio.com/your-org-label/your-space-label/apps/your-app-label
152
+ ```
153
+
154
+ You'll use these three labels when calling tools that need app coordinates.
155
+
156
+ ### 6. Start Using
157
+
158
+ 1. Restart Claude Desktop
159
+ 2. Start a conversation and try: `Load app structure for org/space/app`
160
+ 3. Then try: `Show me all items from org/space/app`
161
+
162
+ Note: Replace `org/space/app` with your actual Podio app coordinates.
163
+
164
+ ## Available Commands
165
+
166
+ ### Setup Commands
167
+
168
+ | Command | Description |
169
+ | ------------------------------------------------ | --------------------------------------------------- |
170
+ | `Load app structure for org/space/app` | Initialize the app structure (cached automatically) |
171
+
172
+ ### Cache Management
173
+
174
+ | Command | Description |
175
+ | --------------------------------------- | --------------------------------- |
176
+ | `Show cached apps` | View all cached app structures |
177
+ | `Cache app structure for org/space/app` | Manually cache a specific app |
178
+ | `Refresh cache for app 12345` | Force refresh specific cached app |
179
+ | `Refresh all cached apps` | Force refresh all cached apps |
180
+ | `Clear cache for app 12345` | Remove specific app from cache |
181
+ | `Clear all cached apps` | Clear entire app cache |
182
+
183
+ ### Item Management
184
+
185
+ | Command | Description |
186
+ | ------------------------------------------- | ----------------------------- |
187
+ | `Show me all Podio items` | List all items |
188
+ | `Show items with status "In Progress"` | Filter by status |
189
+ | `Show items assigned to John` | Filter by responsible person |
190
+ | `Create a new item titled "Task name"` | Create a new item |
191
+ | `Update item 12345 to set status to "Done"` | Update an item |
192
+ | `Delete item 12345` | Delete an item |
193
+ | `Show details for item 12345` | Get detailed item information |
194
+
195
+ ### Task Management
196
+
197
+ | Command | Description |
198
+ | ---------------------------------- | ------------------------------------- |
199
+ | `Show me my Podio tasks` | List your tasks |
200
+ | `Show completed tasks` | Filter tasks by status |
201
+ | `List active tasks assigned to me` | Filter active tasks |
202
+ | `Create a task "Review document"` | Create a new task |
203
+ | `Create task for item 12345` | Create task attached to specific item |
204
+ | `Update task 67890 to completed` | Update task status |
205
+ | `Delete task 67890` | Delete a task |
206
+
207
+ ### Project/Epic Management
208
+
209
+ | Command | Description |
210
+ | --------------------------------------------- | ----------------------------------------- |
211
+ | `List all projects` | Show available projects (cache-optimized) |
212
+ | `List all epics` | Show available epics (cache-optimized) |
213
+ | `Suggest project and epic for "API refactor"` | Get AI-powered suggestions for assignment |
214
+ | `Inspect field structure` | Debug app field configuration |
215
+ | `List space members` | Show team members for assignments |
216
+
217
+ ## Example Workflow
218
+
219
+ ```
220
+ 1. "Load app structure for myorg/development/tickets"
221
+ ✅ App structure loaded successfully (from cache)!
222
+
223
+ 2. "Show cached apps"
224
+ 📦 App Cache Status: 3 apps cached
225
+
226
+ 3. "Show me all items from myorg/development/tickets with status 'To Do'"
227
+ 📋 Found 5 items with status 'To Do'...
228
+
229
+ 4. "Create a new item in myorg/development/tickets titled 'Review pull request' with status 'In Progress'"
230
+ ✅ Item created successfully! ID: 12345
231
+
232
+ 5. "Update item 12345 to add description 'Review the authentication changes'"
233
+ ✅ Item updated successfully!
234
+
235
+ 6. "Mark item 12345 as completed"
236
+ ✅ Item updated successfully!
237
+ ```
238
+
239
+ ## Architecture
240
+
241
+ ### MCP Server (`src/index.ts`)
242
+
243
+ - Handles tool registration and execution
244
+ - Manages Podio API communication
245
+ - Processes natural language commands into API calls
246
+
247
+ ### OAuth Helper (`src/oauth-helper.ts`)
248
+
249
+ - Manages OAuth2 authentication flow
250
+ - Handles token storage and refresh
251
+ - Provides browser-based authorization
252
+
253
+ ### Typed Error System (`src/errors/`)
254
+
255
+ The server includes a comprehensive typed error system that replaces generic `Error` usage with specific, structured error classes:
256
+
257
+ - **PodioError**: Base class with error codes, HTTP status info, and contextual metadata
258
+ - **PodioApiError**: API request failures, network issues, and HTTP errors
259
+ - **PodioAuthError**: OAuth authentication failures and token management issues
260
+ - **PodioConfigError**: Configuration problems and missing environment variables
261
+ - **PodioCacheError**: Cache operation failures and corruption detection
262
+ - **PodioValidationError**: Data validation failures and parameter validation
263
+ - **PodioStructureError**: App structure issues and field configuration problems
264
+
265
+ #### Error Handling Examples
266
+
267
+ ```typescript
268
+ import {
269
+ PodioApiError,
270
+ PodioAuthError,
271
+ isPodioApiError,
272
+ PodioErrorFactory
273
+ } from './errors/index.js';
274
+
275
+ // Creating specific errors
276
+ throw PodioApiError.fromResponse(response, 'Custom message');
277
+ throw PodioAuthError.notInitialized(['PODIO_CLIENT_ID']);
278
+ throw PodioErrorFactory.structureNotLoaded('item creation');
279
+
280
+ // Error handling with type guards
281
+ try {
282
+ await podioOperation();
283
+ } catch (error) {
284
+ if (isPodioApiError(error)) {
285
+ console.log(`API Error: ${error.code}, Status: ${error.context.statusCode}`);
286
+ } else if (error instanceof PodioAuthError) {
287
+ console.log(`Auth Error: ${error.code}`);
288
+ }
289
+ }
290
+ ```
291
+
292
+ #### Error Codes
293
+
294
+ All errors include standardized error codes for programmatic handling:
295
+
296
+ - **1000-1999**: API Errors (request failed, timeout, network error)
297
+ - **2000-2999**: Authentication Errors (invalid credentials, token expired, OAuth failed)
298
+ - **3000-3999**: Configuration Errors (missing required, invalid value, incomplete OAuth)
299
+ - **4000-4999**: Cache Errors (read/write failed, invalidation failed, corrupted)
300
+ - **5000-5999**: Validation Errors (required field, invalid type, out of range)
301
+ - **6000-6999**: Structure Errors (not loaded, app not found, field not found)
302
+
303
+ ### Tool Categories
304
+
305
+ 1. **App Structure Tools**: Load and cache app configuration
306
+ 2. **Item Management Tools**: CRUD operations for Podio items
307
+ 3. **Task Management Tools**: Full CRUD operations for Podio tasks
308
+ 4. **Project/Epic Management**: Smart discovery and AI-powered suggestions
309
+ 5. **Utility Tools**: Field inspection, member listing, and error handling
310
+
311
+ ## Advanced Configuration
312
+
313
+ ### Custom Field Mappings
314
+
315
+ If your Podio app uses different field names, modify the field detection logic in the server:
316
+
317
+ ```typescript
318
+ // Example: Change "Status" to "Current Status"
319
+ const statusField = this.appStructure.fields.find(
320
+ (f) => f.label.toLowerCase() === "current status" && f.type === "category",
321
+ );
322
+ ```
323
+
324
+ ### Adding New Tools
325
+
326
+ Extend the server by adding new tools:
327
+
328
+ 1. Add tool definition in `ListToolsRequestSchema`
329
+ 2. Add handler case in `CallToolRequestSchema`
330
+ 3. Implement the tool method
331
+
332
+
333
+ ### Environment Variables
334
+
335
+ | Variable | Description | Required | Notes |
336
+ | --------------------------- | ----------------------------- | -------- | ---------------------------- |
337
+ | `PODIO_CLIENT_ID` | Your Podio API Client ID | ✅ | |
338
+ | `PODIO_CLIENT_SECRET` | Your Podio API Client Secret | ✅ | |
339
+ | `PODIO_REDIRECT_URI` | OAuth redirect URI | ✅ | |
340
+ | `PODIO_DEBUG` | Enable debug logging | ❌ | Set to `true` for verbose output |
341
+ | `PODIO_ITEM_FETCH_LIMIT` | Max items to fetch per request | ❌ | Default: 100, Max: 500 |
342
+
343
+ **Note**: App coordinates (org_label, space_label, app_label) are provided explicitly in tool calls rather than through environment variables, making the server generic for any Podio app.
344
+
345
+ ## Token Storage
346
+
347
+ Tokens are automatically stored in:
348
+
349
+ - **macOS/Linux:** `~/.config/podio-mcp/token.json`
350
+ - **Windows:** `%USERPROFILE%/.config/podio-mcp/token.json`
351
+
352
+ The server handles token refresh automatically when needed.
353
+
354
+ ## Troubleshooting
355
+
356
+ ### Common Issues
357
+
358
+ **"spawn node ENOENT"**
359
+
360
+ - This error means Claude Desktop cannot find the Node.js executable
361
+
362
+ **Fixing "spawn node ENOENT" error:**
363
+
364
+ **For bunx users:**
365
+ Use the bunx configuration approach which avoids path issues entirely:
366
+
367
+ ```json
368
+ {
369
+ "mcpServers": {
370
+ "podio": {
371
+ "command": "bunx",
372
+ "args": ["@forumviriumhelsinki/podio-mcp"],
373
+ "env": {
374
+ /* your environment variables */
375
+ }
376
+ }
377
+ }
378
+ }
379
+ ```
380
+
381
+ **For local development:**
382
+
383
+ 1. Run our configuration generator:
384
+
385
+ ```bash
386
+ bun run configure
387
+ ```
388
+
389
+ 2. Copy the generated configuration
390
+
391
+ 3. Open your Claude Desktop configuration file:
392
+
393
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
394
+ - **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
395
+
396
+ 4. Replace the contents with the generated configuration
397
+
398
+ 5. Restart Claude Desktop
399
+
400
+ 6. Test by asking Claude: "Load app structure for org/space/app" (using your actual coordinates)
401
+
402
+ **"OAuth helper not initialized"**
403
+
404
+ - Make sure authentication environment variables (PODIO_CLIENT_ID, PODIO_CLIENT_SECRET, PODIO_REDIRECT_URI) are set in your Claude configuration
405
+ - Check that you've entered your Podio client ID and secret correctly
406
+ - Try running the server directly with `bun run start` to see detailed error messages
407
+
408
+ **"Port already in use" or OAuth callback server errors**
409
+
410
+ - The server automatically tries alternative ports (8080, 8090, 8100, 8888, 9090) if port 8080 is in use
411
+ - **Important**: For fallback ports to work with OAuth, you must add all fallback redirect URIs to your Podio app settings
412
+ - If you haven't configured all fallback URIs, the OAuth flow will fail when using an alternative port
413
+ - Solutions:
414
+ 1. Add all fallback redirect URIs to your Podio app (recommended for development)
415
+ 2. Stop the service using port 8080 to use the primary port
416
+ 3. Configure a custom redirect URI with a different port that's always available
417
+ - Clear error messages will indicate which port is being used during OAuth flow
418
+
419
+ **"App structure not loaded"**
420
+
421
+ - Provide explicit app coordinates (org_label, space_label, app_label) in your tool calls
422
+ - Example: `Load app structure for myorg/myspace/myapp`
423
+
424
+ **"Failed to fetch app"**
425
+
426
+ - Verify your org/space/app coordinates are correct (check your Podio app URL)
427
+ - Ensure you have access to the specified app
428
+
429
+ **"Authentication failed"**
430
+
431
+ - Check your Client ID and Client Secret
432
+ - Verify the redirect URI matches your Podio API key settings
433
+
434
+ ### Project/Epic Configuration Issues
435
+
436
+ **"Project field not found or not properly configured"**
437
+
438
+ - Your app may not have properly configured project/epic fields
439
+ - Use `Inspect field structure` to see available fields
440
+ - The server will automatically discover project/epic apps from any app reference fields
441
+
442
+ **"Failed to fetch projects/epics"**
443
+
444
+ - Check that project/epic apps exist and are accessible
445
+ - Verify app permissions - you need at least "reference" and "view" rights
446
+ - Use `List all projects` or `List all epics` to test connectivity
447
+ - Check the logs for specific error messages
448
+
449
+ **Project/Epic suggestions not working**
450
+
451
+ - Ensure project and epic data is loaded: run `List all projects` and `List all epics` first
452
+ - The suggestion algorithm requires project/epic titles and descriptions for matching
453
+ - Empty project/epic apps will result in "No strong matches found"
454
+ - Use `Suggest project and epic for "your task description"` with descriptive text
455
+
456
+ ### Debug Mode
457
+
458
+ Run the server directly to see detailed error messages:
459
+
460
+ ```bash
461
+ node build/index.js
462
+ ```
463
+
464
+ ### Logs
465
+
466
+ The server outputs status information to stderr, which you can view in Claude Desktop's logs.
467
+
468
+ ## Contributing
469
+
470
+ 1. Fork the repository
471
+ 2. Create a feature branch
472
+ 3. Make your changes
473
+ 4. Add tests if applicable
474
+ 5. Submit a pull request
475
+
476
+ ## License
477
+
478
+ MIT License - see LICENSE file for details.
479
+
480
+ ## Support
481
+
482
+ For issues and questions:
483
+
484
+ 1. Check the troubleshooting section
485
+ 2. Review the example usage document
486
+ 3. Open an issue on the repository
487
+
488
+ ## Related Projects
489
+
490
+ - [Podio TUI](https://github.com/your-repo/podio-tui) - Terminal UI for Podio (the inspiration for this project)
491
+ - [Model Context Protocol](https://github.com/modelcontextprotocol/sdk) - The MCP SDK documentation
@@ -0,0 +1,104 @@
1
+ /**
2
+ * Integration test setup and utilities
3
+ *
4
+ * Provides common setup, teardown, and helper functions for integration tests.
5
+ * Handles environment configuration, test data management, and cleanup.
6
+ */
7
+ import { PodioOAuthHelper } from '../../oauth-helper';
8
+ import { PodioApiClient } from '../../api/podio-api-client';
9
+ import { CacheManager } from '../../cache/cache-manager';
10
+ /**
11
+ * Test configuration
12
+ */
13
+ export declare const TEST_CONFIG: {
14
+ workspace: {
15
+ org_label: string;
16
+ space_label: string;
17
+ app_label: string;
18
+ };
19
+ testItemId: number;
20
+ testUserId: number;
21
+ testSpaceId: number;
22
+ testAppId: number;
23
+ timeouts: {
24
+ indexing: number;
25
+ api: number;
26
+ retry: number;
27
+ };
28
+ limits: {
29
+ maxItems: number;
30
+ maxRetries: number;
31
+ };
32
+ };
33
+ /**
34
+ * Integration test context
35
+ */
36
+ export interface IntegrationTestContext {
37
+ oauthHelper: PodioOAuthHelper;
38
+ apiClient: PodioApiClient;
39
+ cacheManager: CacheManager;
40
+ cleanup: CleanupManager;
41
+ }
42
+ /**
43
+ * Cleanup manager to track and clean up test resources
44
+ */
45
+ export declare class CleanupManager {
46
+ private apiClient;
47
+ private items;
48
+ private tasks;
49
+ private comments;
50
+ constructor(apiClient: PodioApiClient);
51
+ trackItem(itemId: number): void;
52
+ trackTask(taskId: number): void;
53
+ trackComment(commentId: number): void;
54
+ cleanup(): Promise<void>;
55
+ }
56
+ /**
57
+ * Setup integration test context
58
+ */
59
+ export declare function setupIntegrationTests(): IntegrationTestContext;
60
+ /**
61
+ * Wait for async operations like search indexing
62
+ */
63
+ export declare function waitForIndexing(ms?: number): Promise<void>;
64
+ /**
65
+ * Retry an async operation with exponential backoff
66
+ */
67
+ export declare function retryOperation<T>(operation: () => Promise<T>, maxRetries?: number, delay?: number): Promise<T>;
68
+ /**
69
+ * Check if integration tests should be skipped
70
+ */
71
+ export declare function shouldSkipIntegrationTests(): boolean;
72
+ /**
73
+ * Generate unique test data
74
+ */
75
+ export declare function generateTestData(prefix?: string): {
76
+ title: string;
77
+ description: string;
78
+ timestamp: string;
79
+ };
80
+ /**
81
+ * Mock API responses for testing error conditions
82
+ */
83
+ export declare function mockApiError(apiClient: PodioApiClient, method: 'get' | 'post' | 'put' | 'delete', statusCode: number, errorMessage?: string): jest.SpyInstance;
84
+ /**
85
+ * Verify API call was made with expected parameters
86
+ */
87
+ export declare function verifyApiCall(spy: jest.SpyInstance, expectedEndpoint: string, expectedBody?: any): void;
88
+ /**
89
+ * Global setup for all integration tests
90
+ */
91
+ export declare function globalSetup(): Promise<void>;
92
+ /**
93
+ * Global teardown for all integration tests
94
+ */
95
+ export declare function globalTeardown(): Promise<void>;
96
+ declare global {
97
+ namespace jest {
98
+ interface Matchers<R> {
99
+ toBeValidPodioId(): R;
100
+ toBeWithinDateRange(start: Date, end: Date): R;
101
+ }
102
+ }
103
+ }
104
+ //# sourceMappingURL=setup.integration.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"setup.integration.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/setup.integration.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAMzD;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;CA0BvB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,SAAS,EAAE,cAAc,CAAC;IAC1B,YAAY,EAAE,YAAY,CAAC;IAC3B,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,cAAc;IAKb,OAAO,CAAC,SAAS;IAJ7B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAgB;gBAEZ,SAAS,EAAE,cAAc;IAE7C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAmC/B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,sBAAsB,CA2B9D;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,EAAE,GAAE,MAAsC,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/F;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,GAAE,MAAsC,EAClD,KAAK,GAAE,MAAmC,GACzC,OAAO,CAAC,CAAC,CAAC,CAeZ;AAED;;GAEG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,MAAe,GAAG;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CASA;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,EACzC,UAAU,EAAE,MAAM,EAClB,YAAY,GAAE,MAAuB,GACpC,IAAI,CAAC,WAAW,CASlB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,IAAI,CAAC,WAAW,EACrB,gBAAgB,EAAE,MAAM,EACxB,YAAY,CAAC,EAAE,GAAG,GACjB,IAAI,CAaN;AAED;;GAEG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAYjD;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAGpD;AA+BD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,IAAI,CAAC;QACb,UAAU,QAAQ,CAAC,CAAC;YAClB,gBAAgB,IAAI,CAAC,CAAC;YACtB,mBAAmB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,CAAC,CAAC;SAChD;KACF;CACF"}