@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/README.md CHANGED
@@ -1,491 +1,264 @@
1
1
  # Podio MCP Server
2
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.
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4
+ [![npm package](https://img.shields.io/npm/v/@forumviriumhelsinki/podio-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@forumviriumhelsinki/podio-mcp)
5
+ [![Node.js Version](https://img.shields.io/badge/node-≥24.0.0-brightgreen.svg)](https://nodejs.org/)
6
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
4
7
 
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:
8
+ A Model Context Protocol (MCP) server that integrates Podio with Claude, enabling natural language management of Podio items and tasks. Automate workflows, manage projects, and organize work with conversational AI.
24
9
 
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
10
+ ## Features
31
11
 
32
- > 💡 **Tip**: The live documentation is automatically updated with each release and includes interactive examples!
12
+ - **OAuth2 Authentication** - Secure authentication with automatic token refresh
13
+ - **CRUD Operations** - Create, read, update, and delete Podio items and tasks
14
+ - **Intelligent Caching** - App structure caching with automatic refresh for performance
15
+ - **AI-Powered Suggestions** - Smart project/epic suggestions using fuzzy matching
16
+ - **Multi-Workspace Support** - Works with any Podio workspace using explicit coordinates
17
+ - **Comprehensive Search** - Search items, tasks, files, and conversations across scopes
18
+ - **Notification Management** - Manage and filter Podio notifications
19
+ - **Activity Tracking** - Full comment and revision history for items
20
+ - **Robust Error Handling** - Detailed error messages for debugging
21
+
22
+ ## Tech Stack
23
+
24
+ | Layer | Technology |
25
+ |-------|-----------|
26
+ | **Runtime** | Node.js 24+ / Bun |
27
+ | **Language** | TypeScript 5.9+ |
28
+ | **Protocol** | Model Context Protocol (MCP) v0.4.0 |
29
+ | **Testing** | Jest 30 |
30
+ | **Code Quality** | Biome 2.3+ (linting & formatting) |
31
+ | **Documentation** | TypeDoc |
32
+ | **Package Manager** | npm / Bun |
33
+
34
+ ## Prerequisites
35
+
36
+ - **Node.js** ≥ 24.0.0 or **Bun** ≥ 1.0.0
37
+ - Podio account with API credentials (see [Setup Guide](docs/setup-guide.md))
38
+ - MCP-compatible client (Claude Desktop, Cline, etc.)
33
39
 
34
40
  ## Quick Start
35
41
 
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:
42
+ ### Install
47
43
 
48
44
  ```bash
49
- # Install from npm (no build required)
50
45
  bunx @forumviriumhelsinki/podio-mcp
51
46
  ```
52
47
 
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:
48
+ ### Configure
60
49
 
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
50
+ Add to your MCP client configuration (`.mcp.json` or Claude Desktop config):
68
51
 
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
52
+ ```json
53
+ {
54
+ "mcpServers": {
55
+ "podio-mcp": {
56
+ "command": "bunx",
57
+ "args": ["@forumviriumhelsinki/podio-mcp"],
58
+ "env": {
59
+ "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}",
60
+ "PODIO_CLIENT_SECRET": "${PODIO_CLIENT_SECRET}",
61
+ "PODIO_REDIRECT_URI": "${PODIO_REDIRECT_URI}"
62
+ }
63
+ }
64
+ }
65
+ }
82
66
  ```
83
67
 
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:**
68
+ > **Tip**: `PODIO_CLIENT_SECRET` is optional. Without it, the server uses Podio's implicit OAuth flow, which only requires a Client ID. This simplifies onboarding.
101
69
 
102
70
  ```json
103
71
  {
104
72
  "mcpServers": {
105
- "podio": {
73
+ "podio-mcp": {
106
74
  "command": "bunx",
107
75
  "args": ["@forumviriumhelsinki/podio-mcp"],
108
76
  "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"
77
+ "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}",
78
+ "PODIO_REDIRECT_URI": "${PODIO_REDIRECT_URI}"
112
79
  }
113
80
  }
114
81
  }
115
82
  }
116
83
  ```
117
84
 
118
- **For local development:**
85
+ Get your API credentials from [Podio Developers](https://developers.podio.com/api-key).
119
86
 
120
- Use the configuration generator for easy setup:
87
+ ### Usage Examples
121
88
 
122
- ```bash
123
- # From local clone
124
- bun run configure
125
89
  ```
90
+ # Load an app structure for querying
91
+ Load app structure for myorg/myspace/myapp
126
92
 
127
- This script will generate the proper configuration with correct paths for your system.
128
-
129
- ### 4. Get Podio API Credentials
93
+ # Query items with filters
94
+ Show me all items with status "In Progress"
130
95
 
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
96
+ # Create new items
97
+ Create a new item titled "Review pull request" with description "Urgent PR"
143
98
 
144
- ### 5. Understanding App Coordinates
99
+ # Search across workspace
100
+ Search for items containing "authentication" in myspace
145
101
 
146
- When using the server, you'll need to provide app coordinates (org_label, space_label, app_label) in your tool calls.
102
+ # Manage tasks
103
+ Create a task assigned to alice@example.com due tomorrow
147
104
 
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
105
+ # Get notifications
106
+ Show my unread notifications from the last 7 days
152
107
  ```
153
108
 
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) |
109
+ See [Usage Examples](docs/usage-examples.md) for more detailed workflows.
171
110
 
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
111
+ ## Project Structure
218
112
 
219
113
  ```
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!
114
+ podio-mcp/
115
+ ├── src/
116
+ │ ├── index.ts # Main MCP server
117
+ │ ├── oauth-helper.ts # OAuth2 authentication
118
+ │ ├── api/
119
+ │ │ └── podio-api-client.ts # Podio HTTP client
120
+ │ ├── services/ # Business logic layer
121
+ │ │ ├── items/ # Item CRUD operations
122
+ │ │ ├── tasks/ # Task management
123
+ │ │ ├── comments/ # Comment handling
124
+ │ │ ├── search/ # Search functionality
125
+ │ │ ├── app/ # App structure discovery
126
+ │ │ ├── notifications/ # Notification management
127
+ │ │ └── project-epic/ # Project/epic suggestions
128
+ │ ├── cache/ # Caching layer
129
+ │ ├── errors/ # Custom error types
130
+ │ └── types/ # TypeScript definitions
131
+ ├── __tests__/
132
+ │ ├── unit/ # Unit tests
133
+ │ ├── integration/ # Integration tests
134
+ │ └── fixtures/ # Test data and mocks
135
+ ├── docs/ # Documentation
136
+ ├── scripts/ # Build and configuration scripts
137
+ └── build/ # Compiled output (generated)
237
138
  ```
238
139
 
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`)
140
+ ## Development
248
141
 
249
- - Manages OAuth2 authentication flow
250
- - Handles token storage and refresh
251
- - Provides browser-based authorization
142
+ ### Build & Run
252
143
 
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
144
+ ```bash
145
+ # Development with watch mode
146
+ bun run dev
266
147
 
267
- ```typescript
268
- import {
269
- PodioApiError,
270
- PodioAuthError,
271
- isPodioApiError,
272
- PodioErrorFactory
273
- } from './errors/index.js';
148
+ # Build production bundle
149
+ bun run build
274
150
 
275
- // Creating specific errors
276
- throw PodioApiError.fromResponse(response, 'Custom message');
277
- throw PodioAuthError.notInitialized(['PODIO_CLIENT_ID']);
278
- throw PodioErrorFactory.structureNotLoaded('item creation');
151
+ # Run the server
152
+ bun run start
279
153
 
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
- }
154
+ # Generate configuration
155
+ bun run configure
290
156
  ```
291
157
 
292
- #### Error Codes
293
-
294
- All errors include standardized error codes for programmatic handling:
158
+ ### Code Quality
295
159
 
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
160
+ ```bash
161
+ # Lint with Biome
162
+ bun run lint
310
163
 
311
- ## Advanced Configuration
164
+ # Auto-fix lint issues
165
+ bun run lint:fix
312
166
 
313
- ### Custom Field Mappings
167
+ # Format code
168
+ bun run format
314
169
 
315
- If your Podio app uses different field names, modify the field detection logic in the server:
170
+ # Check formatting
171
+ bun run format:check
316
172
 
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
- );
173
+ # Run all checks (CI mode)
174
+ bun run check
322
175
  ```
323
176
 
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 |
177
+ ### Testing
342
178
 
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"**
179
+ ```bash
180
+ # Run all tests
181
+ bun test
359
182
 
360
- - This error means Claude Desktop cannot find the Node.js executable
183
+ # Run with coverage report
184
+ bun run test:coverage
361
185
 
362
- **Fixing "spawn node ENOENT" error:**
186
+ # Watch mode for development
187
+ bun run test:watch
363
188
 
364
- **For bunx users:**
365
- Use the bunx configuration approach which avoids path issues entirely:
189
+ # Unit tests only
190
+ bun run test:unit
366
191
 
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
- }
192
+ # Integration tests only
193
+ bun run test:integration
379
194
  ```
380
195
 
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"**
196
+ ### Documentation
420
197
 
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
198
+ ```bash
199
+ # Generate TypeDoc API documentation
200
+ bun run docs
435
201
 
436
- **"Project field not found or not properly configured"**
202
+ # Watch mode with live reload
203
+ bun run docs:serve
437
204
 
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
205
+ # Build everything including docs
206
+ bun run docs:build
441
207
 
442
- **"Failed to fetch projects/epics"**
208
+ # Deploy documentation
209
+ bun run docs:deploy
210
+ ```
443
211
 
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
212
+ ## Documentation
448
213
 
449
- **Project/Epic suggestions not working**
214
+ - **[Setup Guide](docs/setup-guide.md)** - Installation, configuration, and troubleshooting
215
+ - **[Usage Examples](docs/usage-examples.md)** - Commands and workflow patterns
216
+ - **[API Documentation](docs/API_DOCUMENTATION.md)** - Architecture and API details
217
+ - **[Notifications Guide](docs/NOTIFICATIONS.md)** - Notification management
218
+ - **[Live Docs](https://forumviriumhelsinki.github.io/podio-mcp/)** - Generated API reference
450
219
 
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
220
+ ## Environment Variables
455
221
 
456
- ### Debug Mode
222
+ | Variable | Description | Required |
223
+ |----------|-------------|----------|
224
+ | `PODIO_CLIENT_ID` | Podio API Client ID | Yes |
225
+ | `PODIO_CLIENT_SECRET` | Podio API Client Secret | No (enables auth code flow) |
226
+ | `PODIO_REDIRECT_URI` | OAuth redirect URI | Yes |
227
+ | `PODIO_DEBUG` | Enable debug logging | No |
457
228
 
458
- Run the server directly to see detailed error messages:
229
+ ## Contributing
459
230
 
460
- ```bash
461
- node build/index.js
462
- ```
231
+ We welcome contributions! Please follow these steps:
463
232
 
464
- ### Logs
233
+ 1. **Fork** the repository
234
+ 2. **Create a feature branch** (`git checkout -b feat/your-feature`)
235
+ 3. **Write tests first** (TDD approach) and implement functionality
236
+ 4. **Run the test suite** (`bun test`) and check coverage
237
+ 5. **Format and lint** your code (`bun run format && bun run lint:fix`)
238
+ 6. **Commit** with [conventional commits](https://www.conventionalcommits.org/):
239
+ - `feat(scope): description` - New features
240
+ - `fix(scope): description` - Bug fixes
241
+ - `docs: description` - Documentation changes
242
+ - `test: description` - Test additions
243
+ - `chore: description` - Maintenance
244
+ 7. **Push** to your fork and **submit a pull request**
465
245
 
466
- The server outputs status information to stderr, which you can view in Claude Desktop's logs.
246
+ See the [Testing Guide](./.claude/rules/testing.md) for detailed testing practices.
467
247
 
468
- ## Contributing
248
+ ## Troubleshooting
469
249
 
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
250
+ Encounter an issue? Check the [Setup Guide Troubleshooting](docs/setup-guide.md#troubleshooting) section or [create an issue](https://github.com/ForumViriumHelsinki/podio-mcp/issues) with:
251
+ - Error message and stack trace
252
+ - Steps to reproduce
253
+ - Environment (Node.js version, OS)
254
+ - MCP client being used
475
255
 
476
256
  ## License
477
257
 
478
- MIT License - see LICENSE file for details.
258
+ MIT License - see [LICENSE](LICENSE) for details.
479
259
 
480
260
  ## Support
481
261
 
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
262
+ - [Troubleshooting Guide](docs/setup-guide.md#troubleshooting)
263
+ - [GitHub Issues](https://github.com/ForumViriumHelsinki/podio-mcp/issues)
264
+ - [Podio API Documentation](https://developers.podio.com/doc)