@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.
- package/README.md +178 -405
- package/build/api/podio-api-client.d.ts +64 -16
- package/build/api/podio-api-client.d.ts.map +1 -1
- package/build/api/podio-api-client.js +230 -130
- package/build/api/podio-api-client.js.map +1 -1
- package/build/cache/app-cache.d.ts +2 -2
- package/build/cache/app-cache.d.ts.map +1 -1
- package/build/cache/app-cache.js +4 -3
- package/build/cache/app-cache.js.map +1 -1
- package/build/cache/base-cache-manager.d.ts +2 -2
- package/build/cache/base-cache-manager.d.ts.map +1 -1
- package/build/cache/base-cache-manager.js +4 -1
- package/build/cache/base-cache-manager.js.map +1 -1
- package/build/cache/cache-manager.d.ts +7 -7
- package/build/cache/cache-manager.d.ts.map +1 -1
- package/build/cache/cache-manager.js +3 -3
- package/build/cache/cache-manager.js.map +1 -1
- package/build/cache/migration-helper.d.ts +1 -1
- package/build/cache/migration-helper.d.ts.map +1 -1
- package/build/cache/migration-helper.js +3 -2
- package/build/cache/migration-helper.js.map +1 -1
- package/build/cache/project-epic-cache.d.ts +5 -1
- package/build/cache/project-epic-cache.d.ts.map +1 -1
- package/build/cache/project-epic-cache.js +2 -2
- package/build/cache/project-epic-cache.js.map +1 -1
- package/build/cache/space-members-cache.d.ts +5 -0
- package/build/cache/space-members-cache.d.ts.map +1 -1
- package/build/cache/space-members-cache.js +70 -32
- package/build/cache/space-members-cache.js.map +1 -1
- package/build/cache/storage-adapters.d.ts +3 -3
- package/build/cache/storage-adapters.d.ts.map +1 -1
- package/build/cache/storage-adapters.js +8 -7
- package/build/cache/storage-adapters.js.map +1 -1
- package/build/config/build-defaults.d.ts +19 -0
- package/build/config/build-defaults.d.ts.map +1 -0
- package/build/config/build-defaults.js +19 -0
- package/build/config/build-defaults.js.map +1 -0
- package/build/errors/api-errors.d.ts +3 -3
- package/build/errors/api-errors.d.ts.map +1 -1
- package/build/errors/api-errors.js +60 -12
- package/build/errors/api-errors.js.map +1 -1
- package/build/errors/auth-errors.js +1 -1
- package/build/errors/auth-errors.js.map +1 -1
- package/build/errors/base.d.ts +8 -2
- package/build/errors/base.d.ts.map +1 -1
- package/build/errors/base.js.map +1 -1
- package/build/errors/config-errors.d.ts +1 -1
- package/build/errors/config-errors.d.ts.map +1 -1
- package/build/errors/config-errors.js.map +1 -1
- package/build/errors/index.d.ts +14 -14
- package/build/errors/index.d.ts.map +1 -1
- package/build/errors/index.js +15 -15
- package/build/errors/index.js.map +1 -1
- package/build/errors/structure-errors.d.ts +2 -2
- package/build/errors/structure-errors.d.ts.map +1 -1
- package/build/errors/structure-errors.js.map +1 -1
- package/build/errors/validation-errors.d.ts +4 -4
- package/build/errors/validation-errors.d.ts.map +1 -1
- package/build/errors/validation-errors.js.map +1 -1
- package/build/fields/field-mapper.d.ts +26 -6
- package/build/fields/field-mapper.d.ts.map +1 -1
- package/build/fields/field-mapper.js +44 -21
- package/build/fields/field-mapper.js.map +1 -1
- package/build/index.d.ts +18 -5
- package/build/index.d.ts.map +1 -1
- package/build/index.js +220 -131
- package/build/index.js.map +1 -1
- package/build/oauth-helper.d.ts +87 -6
- package/build/oauth-helper.d.ts.map +1 -1
- package/build/oauth-helper.js +288 -84
- package/build/oauth-helper.js.map +1 -1
- package/build/services/app-structure-service.d.ts +1 -1
- package/build/services/app-structure-service.d.ts.map +1 -1
- package/build/services/app-structure-service.js.map +1 -1
- package/build/services/code-execution-service.d.ts +5 -5
- package/build/services/code-execution-service.d.ts.map +1 -1
- package/build/services/code-execution-service.js +65 -40
- package/build/services/code-execution-service.js.map +1 -1
- package/build/services/comment-service.d.ts +3 -3
- package/build/services/comment-service.d.ts.map +1 -1
- package/build/services/comment-service.js +4 -4
- package/build/services/comment-service.js.map +1 -1
- package/build/services/item-service.d.ts +43 -2
- package/build/services/item-service.d.ts.map +1 -1
- package/build/services/item-service.js +139 -145
- package/build/services/item-service.js.map +1 -1
- package/build/services/notification-service.d.ts +1 -2
- package/build/services/notification-service.d.ts.map +1 -1
- package/build/services/notification-service.js +5 -7
- package/build/services/notification-service.js.map +1 -1
- package/build/services/project-epic-service.d.ts +51 -2
- package/build/services/project-epic-service.d.ts.map +1 -1
- package/build/services/project-epic-service.js +172 -86
- package/build/services/project-epic-service.js.map +1 -1
- package/build/services/response-formatter.d.ts +52 -41
- package/build/services/response-formatter.d.ts.map +1 -1
- package/build/services/response-formatter.js +92 -91
- package/build/services/response-formatter.js.map +1 -1
- package/build/services/search-service.d.ts +15 -8
- package/build/services/search-service.d.ts.map +1 -1
- package/build/services/search-service.js +51 -56
- package/build/services/search-service.js.map +1 -1
- package/build/services/task-service.js +1 -1
- package/build/services/task-service.js.map +1 -1
- package/build/tools/tool-definitions.d.ts +2 -2
- package/build/tools/tool-definitions.d.ts.map +1 -1
- package/build/tools/tool-definitions.js +49 -27
- package/build/tools/tool-definitions.js.map +1 -1
- package/build/types/api-types.d.ts +9 -0
- package/build/types/api-types.d.ts.map +1 -1
- package/build/types/notification-types.d.ts +1 -1
- package/build/types/notification-types.d.ts.map +1 -1
- package/build/types/podio-types.d.ts +42 -9
- package/build/types/podio-types.d.ts.map +1 -1
- package/build/utils/debug.d.ts +4 -4
- package/build/utils/debug.d.ts.map +1 -1
- package/build/utils/debug.js +4 -2
- package/build/utils/debug.js.map +1 -1
- package/examples/claude-config-example.json +13 -5
- package/package.json +29 -14
- package/scripts/generate-claude-config.js +17 -11
- package/build/__tests__/integration/setup.integration.d.ts +0 -104
- package/build/__tests__/integration/setup.integration.d.ts.map +0 -1
- package/build/__tests__/integration/setup.integration.js +0 -233
- package/build/__tests__/integration/setup.integration.js.map +0 -1
- package/build/__tests__/mock-data/items-mock-data.d.ts +0 -168
- package/build/__tests__/mock-data/items-mock-data.d.ts.map +0 -1
- package/build/__tests__/mock-data/items-mock-data.js +0 -370
- package/build/__tests__/mock-data/items-mock-data.js.map +0 -1
- package/build/__tests__/mock-data/notification-mock-data.d.ts +0 -55
- package/build/__tests__/mock-data/notification-mock-data.d.ts.map +0 -1
- package/build/__tests__/mock-data/notification-mock-data.js +0 -190
- package/build/__tests__/mock-data/notification-mock-data.js.map +0 -1
- package/build/__tests__/mock-data/project-epic-mock-data.d.ts +0 -45
- package/build/__tests__/mock-data/project-epic-mock-data.d.ts.map +0 -1
- package/build/__tests__/mock-data/project-epic-mock-data.js +0 -85
- package/build/__tests__/mock-data/project-epic-mock-data.js.map +0 -1
- package/build/__tests__/mock-data/tasks-mock-data.d.ts +0 -27
- package/build/__tests__/mock-data/tasks-mock-data.d.ts.map +0 -1
- package/build/__tests__/mock-data/tasks-mock-data.js +0 -104
- package/build/__tests__/mock-data/tasks-mock-data.js.map +0 -1
- package/build/__tests__/mock-data/utility-mock-data.d.ts +0 -19
- package/build/__tests__/mock-data/utility-mock-data.d.ts.map +0 -1
- package/build/__tests__/mock-data/utility-mock-data.js +0 -165
- package/build/__tests__/mock-data/utility-mock-data.js.map +0 -1
- package/build/__tests__/setup.d.ts +0 -8
- package/build/__tests__/setup.d.ts.map +0 -1
- package/build/__tests__/setup.js +0 -31
- package/build/__tests__/setup.js.map +0 -1
- package/build/__tests__/utils/test-helpers.d.ts +0 -110
- package/build/__tests__/utils/test-helpers.d.ts.map +0 -1
- package/build/__tests__/utils/test-helpers.js +0 -222
- package/build/__tests__/utils/test-helpers.js.map +0 -1
- package/build/cache/cache-test.d.ts +0 -9
- package/build/cache/cache-test.d.ts.map +0 -1
- package/build/cache/cache-test.js +0 -169
- 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
|
-
|
|
3
|
+
[](LICENSE)
|
|
4
|
+
[](https://www.npmjs.com/package/@forumviriumhelsinki/podio-mcp)
|
|
5
|
+
[](https://nodejs.org/)
|
|
6
|
+
[](https://www.typescriptlang.org/)
|
|
4
7
|
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
> **
|
|
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": "
|
|
110
|
-
"
|
|
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
|
-
|
|
85
|
+
Get your API credentials from [Podio Developers](https://developers.podio.com/api-key).
|
|
119
86
|
|
|
120
|
-
|
|
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
|
-
|
|
128
|
-
|
|
129
|
-
### 4. Get Podio API Credentials
|
|
93
|
+
# Query items with filters
|
|
94
|
+
Show me all items with status "In Progress"
|
|
130
95
|
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
99
|
+
# Search across workspace
|
|
100
|
+
Search for items containing "authentication" in myspace
|
|
145
101
|
|
|
146
|
-
|
|
102
|
+
# Manage tasks
|
|
103
|
+
Create a task assigned to alice@example.com due tomorrow
|
|
147
104
|
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
250
|
-
- Handles token storage and refresh
|
|
251
|
-
- Provides browser-based authorization
|
|
142
|
+
### Build & Run
|
|
252
143
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
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
|
-
|
|
268
|
-
|
|
269
|
-
PodioApiError,
|
|
270
|
-
PodioAuthError,
|
|
271
|
-
isPodioApiError,
|
|
272
|
-
PodioErrorFactory
|
|
273
|
-
} from './errors/index.js';
|
|
148
|
+
# Build production bundle
|
|
149
|
+
bun run build
|
|
274
150
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
throw PodioAuthError.notInitialized(['PODIO_CLIENT_ID']);
|
|
278
|
-
throw PodioErrorFactory.structureNotLoaded('item creation');
|
|
151
|
+
# Run the server
|
|
152
|
+
bun run start
|
|
279
153
|
|
|
280
|
-
|
|
281
|
-
|
|
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
|
-
|
|
293
|
-
|
|
294
|
-
All errors include standardized error codes for programmatic handling:
|
|
158
|
+
### Code Quality
|
|
295
159
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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
|
-
|
|
164
|
+
# Auto-fix lint issues
|
|
165
|
+
bun run lint:fix
|
|
312
166
|
|
|
313
|
-
|
|
167
|
+
# Format code
|
|
168
|
+
bun run format
|
|
314
169
|
|
|
315
|
-
|
|
170
|
+
# Check formatting
|
|
171
|
+
bun run format:check
|
|
316
172
|
|
|
317
|
-
|
|
318
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
344
|
-
|
|
345
|
-
|
|
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
|
-
|
|
183
|
+
# Run with coverage report
|
|
184
|
+
bun run test:coverage
|
|
361
185
|
|
|
362
|
-
|
|
186
|
+
# Watch mode for development
|
|
187
|
+
bun run test:watch
|
|
363
188
|
|
|
364
|
-
|
|
365
|
-
|
|
189
|
+
# Unit tests only
|
|
190
|
+
bun run test:unit
|
|
366
191
|
|
|
367
|
-
|
|
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
|
-
|
|
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
|
-
|
|
422
|
-
|
|
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
|
-
|
|
202
|
+
# Watch mode with live reload
|
|
203
|
+
bun run docs:serve
|
|
437
204
|
|
|
438
|
-
|
|
439
|
-
|
|
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
|
-
|
|
208
|
+
# Deploy documentation
|
|
209
|
+
bun run docs:deploy
|
|
210
|
+
```
|
|
443
211
|
|
|
444
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
229
|
+
## Contributing
|
|
459
230
|
|
|
460
|
-
|
|
461
|
-
node build/index.js
|
|
462
|
-
```
|
|
231
|
+
We welcome contributions! Please follow these steps:
|
|
463
232
|
|
|
464
|
-
|
|
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
|
-
|
|
246
|
+
See the [Testing Guide](./.claude/rules/testing.md) for detailed testing practices.
|
|
467
247
|
|
|
468
|
-
##
|
|
248
|
+
## Troubleshooting
|
|
469
249
|
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
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
|
|
258
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
479
259
|
|
|
480
260
|
## Support
|
|
481
261
|
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
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)
|