npm package: @forumviriumhelsinki/podio-mcp
Description: Model Context Protocol server for Podio item and task management with AI-powered project/epic suggestions
Author: Lauri Gates
Latest version: 2.3.0

# Podio MCP Server

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.

## Features

- **🔐 Seamless Authentication**: Automatic OAuth2 flow with token storage and refresh
- **⚡ Intelligent Caching**: Persistent app structure caching for lightning-fast operations
- **📋 Item Management**: Create, read, update, and delete Podio items
- **✅ Task Management**: List and manage Podio tasks with full CRUD operations
- **📬 Notification Management**: Read and filter Podio notifications with detailed views
- **🎯 Smart Project/Epic Suggestions**: AI-powered matching for project and epic assignments with cache optimization
- **🔍 Smart Filtering**: Filter items by status, responsible person, and more
- **🏗️ Dynamic App Structure**: Automatically discovers your app's fields and configuration with persistent caching
- **🔄 Cross-App References**: Handles complex app relationships and field configurations
- **🛠️ Cache Management**: Full suite of tools for managing cached app structures
- **🔧 Auto-Recovery**: Automatic cache refresh when API structure mismatches are detected
- **💬 Natural Language Interface**: Use conversational commands instead of API syntax
- **🔄 Auto-refresh**: Handles token expiration automatically

## Documentation

📚 **Complete Documentation** is available online:

- **[📖 Live Documentation](https://forumviriumhelsinki.github.io/podio-mcp/)** - Complete API reference and guides
- **[🚀 Setup Guide](docs/setup-guide.md)** - Detailed installation and configuration
- **[💡 Usage Examples](docs/usage-examples.md)** - Real-world usage patterns and examples
- **[🔔 Notifications Guide](docs/NOTIFICATIONS.md)** - Comprehensive notification management
- **[🏗️ API Documentation](docs/API_DOCUMENTATION.md)** - Architecture and API details
- **[🧪 Cache Integration Example](docs/cache-integration-example.md)** - Advanced caching strategies

> 💡 **Tip**: The live documentation is automatically updated with each release and includes interactive examples!

## Quick Start

### 1. Prerequisites

- Bun runtime (or Node.js 18 or higher)
- Claude Desktop application
- Podio account with API access

### 2. Installation

#### Option 1: Direct bunx Install (Recommended)

Install directly from npm using bunx:

```bash
# Install from npm (no build required)
bunx @forumviriumhelsinki/podio-mcp
```

This will automatically download the latest version and make the server available for configuration.

> **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.

#### Option 2: Local Development Setup

For development or customization:

```bash
# Clone the repository
git clone https://github.com/ForumViriumHelsinki/podio-mcp.git
cd podio-mcp

# Install dependencies
bun install

# Build the project
bun run build
```

### 3. Configure Claude Desktop

#### Option 1: Use bunx with Configuration Generator (Recommended)

For local development, you can use the configuration generator to automatically set up Claude Desktop:

```bash
# From local clone
bun run configure
```

> **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.

This script will:

- Detect your Node.js installation path
- Find the correct path to the compiled index.js
- Generate a properly formatted configuration for Claude Desktop
- Provide step-by-step instructions for installation

#### Option 2: Manual Configuration

Edit your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

**For bunx installation:**

```json
{
  "mcpServers": {
    "podio": {
      "command": "bunx",
      "args": ["@forumviriumhelsinki/podio-mcp"],
      "env": {
        "PODIO_CLIENT_ID": "your_client_id_here",
        "PODIO_CLIENT_SECRET": "your_client_secret_here",
        "PODIO_REDIRECT_URI": "http://localhost:8080/callback"
      }
    }
  }
}
```

**For local development:**

Use the configuration generator for easy setup:

```bash
# From local clone
bun run configure
```

This script will generate the proper configuration with correct paths for your system.

### 4. Get Podio API Credentials

1. Go to [Podio Developers](https://developers.podio.com/api-key)
2. Create a new API key
3. Configure redirect URIs:
   - Primary: `http://localhost:8080/callback`
   - For automatic fallback support, also add these as valid redirect URIs in your Podio app:
     - `http://localhost:8090/callback`
     - `http://localhost:8100/callback`
     - `http://localhost:8888/callback`
     - `http://localhost:9090/callback`
   - The server will automatically try these ports in order if port 8080 is in use
   - Alternatively, you can configure a single custom port and ensure it's available
4. Note your Client ID and Client Secret

### 5. Understanding App Coordinates

When using the server, you'll need to provide app coordinates (org_label, space_label, app_label) in your tool calls.

Navigate to your Podio app in the browser to find these coordinates. The URL will look like:

```
https://podio.com/your-org-label/your-space-label/apps/your-app-label
```

You'll use these three labels when calling tools that need app coordinates.

### 6. Start Using

1. Restart Claude Desktop
2. Start a conversation and try: `Load app structure for org/space/app`
3. Then try: `Show me all items from org/space/app`

Note: Replace `org/space/app` with your actual Podio app coordinates.

## Available Commands

### Setup Commands

| Command                                          | Description                                         |
| ------------------------------------------------ | --------------------------------------------------- |
| `Load app structure for org/space/app`           | Initialize the app structure (cached automatically) |

### Cache Management

| Command                                 | Description                       |
| --------------------------------------- | --------------------------------- |
| `Show cached apps`                      | View all cached app structures    |
| `Cache app structure for org/space/app` | Manually cache a specific app     |
| `Refresh cache for app 12345`           | Force refresh specific cached app |
| `Refresh all cached apps`               | Force refresh all cached apps     |
| `Clear cache for app 12345`             | Remove specific app from cache    |
| `Clear all cached apps`                 | Clear entire app cache            |

### Item Management

| Command                                     | Description                   |
| ------------------------------------------- | ----------------------------- |
| `Show me all Podio items`                   | List all items                |
| `Show items with status "In Progress"`      | Filter by status              |
| `Show items assigned to John`               | Filter by responsible person  |
| `Create a new item titled "Task name"`      | Create a new item             |
| `Update item 12345 to set status to "Done"` | Update an item                |
| `Delete item 12345`                         | Delete an item                |
| `Show details for item 12345`               | Get detailed item information |

### Task Management

| Command                            | Description                           |
| ---------------------------------- | ------------------------------------- |
| `Show me my Podio tasks`           | List your tasks                       |
| `Show completed tasks`             | Filter tasks by status                |
| `List active tasks assigned to me` | Filter active tasks                   |
| `Create a task "Review document"`  | Create a new task                     |
| `Create task for item 12345`       | Create task attached to specific item |
| `Update task 67890 to completed`   | Update task status                    |
| `Delete task 67890`                | Delete a task                         |

### Project/Epic Management

| Command                                       | Description                               |
| --------------------------------------------- | ----------------------------------------- |
| `List all projects`                           | Show available projects (cache-optimized) |
| `List all epics`                              | Show available epics (cache-optimized)    |
| `Suggest project and epic for "API refactor"` | Get AI-powered suggestions for assignment |
| `Inspect field structure`                     | Debug app field configuration             |
| `List space members`                          | Show team members for assignments         |

## Example Workflow

```
1. "Load app structure for myorg/development/tickets"
   ✅ App structure loaded successfully (from cache)!

2. "Show cached apps"
   📦 App Cache Status: 3 apps cached

3. "Show me all items from myorg/development/tickets with status 'To Do'"
   📋 Found 5 items with status 'To Do'...

4. "Create a new item in myorg/development/tickets titled 'Review pull request' with status 'In Progress'"
   ✅ Item created successfully! ID: 12345

5. "Update item 12345 to add description 'Review the authentication changes'"
   ✅ Item updated successfully!

6. "Mark item 12345 as completed"
   ✅ Item updated successfully!
```

## Architecture

### MCP Server (`src/index.ts`)

- Handles tool registration and execution
- Manages Podio API communication
- Processes natural language commands into API calls

### OAuth Helper (`src/oauth-helper.ts`)

- Manages OAuth2 authentication flow
- Handles token storage and refresh
- Provides browser-based authorization

### Typed Error System (`src/errors/`)

The server includes a comprehensive typed error system that replaces generic `Error` usage with specific, structured error classes:

- **PodioError**: Base class with error codes, HTTP status info, and contextual metadata
- **PodioApiError**: API request failures, network issues, and HTTP errors
- **PodioAuthError**: OAuth authentication failures and token management issues
- **PodioConfigError**: Configuration problems and missing environment variables
- **PodioCacheError**: Cache operation failures and corruption detection
- **PodioValidationError**: Data validation failures and parameter validation
- **PodioStructureError**: App structure issues and field configuration problems

#### Error Handling Examples

```typescript
import {
  PodioApiError,
  PodioAuthError,
  isPodioApiError,
  PodioErrorFactory
} from './errors/index.js';

// Creating specific errors
throw PodioApiError.fromResponse(response, 'Custom message');
throw PodioAuthError.notInitialized(['PODIO_CLIENT_ID']);
throw PodioErrorFactory.structureNotLoaded('item creation');

// Error handling with type guards
try {
  await podioOperation();
} catch (error) {
  if (isPodioApiError(error)) {
    console.log(`API Error: ${error.code}, Status: ${error.context.statusCode}`);
  } else if (error instanceof PodioAuthError) {
    console.log(`Auth Error: ${error.code}`);
  }
}
```

#### Error Codes

All errors include standardized error codes for programmatic handling:

- **1000-1999**: API Errors (request failed, timeout, network error)
- **2000-2999**: Authentication Errors (invalid credentials, token expired, OAuth failed)
- **3000-3999**: Configuration Errors (missing required, invalid value, incomplete OAuth)
- **4000-4999**: Cache Errors (read/write failed, invalidation failed, corrupted)
- **5000-5999**: Validation Errors (required field, invalid type, out of range)
- **6000-6999**: Structure Errors (not loaded, app not found, field not found)

### Tool Categories

1. **App Structure Tools**: Load and cache app configuration
2. **Item Management Tools**: CRUD operations for Podio items
3. **Task Management Tools**: Full CRUD operations for Podio tasks
4. **Project/Epic Management**: Smart discovery and AI-powered suggestions
5. **Utility Tools**: Field inspection, member listing, and error handling

## Advanced Configuration

### Custom Field Mappings

If your Podio app uses different field names, modify the field detection logic in the server:

```typescript
// Example: Change "Status" to "Current Status"
const statusField = this.appStructure.fields.find(
  (f) => f.label.toLowerCase() === "current status" && f.type === "category",
);
```

### Adding New Tools

Extend the server by adding new tools:

1. Add tool definition in `ListToolsRequestSchema`
2. Add handler case in `CallToolRequestSchema`
3. Implement the tool method


### Environment Variables

| Variable                    | Description                   | Required | Notes                        |
| --------------------------- | ----------------------------- | -------- | ---------------------------- |
| `PODIO_CLIENT_ID`           | Your Podio API Client ID      | ✅       |                              |
| `PODIO_CLIENT_SECRET`       | Your Podio API Client Secret  | ✅       |                              |
| `PODIO_REDIRECT_URI`        | OAuth redirect URI            | ✅       |                              |
| `PODIO_DEBUG`              | Enable debug logging          | ❌       | Set to `true` for verbose output |
| `PODIO_ITEM_FETCH_LIMIT`   | Max items to fetch per request | ❌     | Default: 100, Max: 500       |

**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.

## Token Storage

Tokens are automatically stored in:

- **macOS/Linux:** `~/.config/podio-mcp/token.json`
- **Windows:** `%USERPROFILE%/.config/podio-mcp/token.json`

The server handles token refresh automatically when needed.

## Troubleshooting

### Common Issues

**"spawn node ENOENT"**

- This error means Claude Desktop cannot find the Node.js executable

**Fixing "spawn node ENOENT" error:**

**For bunx users:**
Use the bunx configuration approach which avoids path issues entirely:

```json
{
  "mcpServers": {
    "podio": {
      "command": "bunx",
      "args": ["@forumviriumhelsinki/podio-mcp"],
      "env": {
        /* your environment variables */
      }
    }
  }
}
```

**For local development:**

1. Run our configuration generator:

   ```bash
   bun run configure
   ```

2. Copy the generated configuration

3. Open your Claude Desktop configuration file:

   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

4. Replace the contents with the generated configuration

5. Restart Claude Desktop

6. Test by asking Claude: "Load app structure for org/space/app" (using your actual coordinates)

**"OAuth helper not initialized"**

- Make sure authentication environment variables (PODIO_CLIENT_ID, PODIO_CLIENT_SECRET, PODIO_REDIRECT_URI) are set in your Claude configuration
- Check that you've entered your Podio client ID and secret correctly
- Try running the server directly with `bun run start` to see detailed error messages

**"Port already in use" or OAuth callback server errors**

- The server automatically tries alternative ports (8080, 8090, 8100, 8888, 9090) if port 8080 is in use
- **Important**: For fallback ports to work with OAuth, you must add all fallback redirect URIs to your Podio app settings
- If you haven't configured all fallback URIs, the OAuth flow will fail when using an alternative port
- Solutions:
  1. Add all fallback redirect URIs to your Podio app (recommended for development)
  2. Stop the service using port 8080 to use the primary port
  3. Configure a custom redirect URI with a different port that's always available
- Clear error messages will indicate which port is being used during OAuth flow

**"App structure not loaded"**

- Provide explicit app coordinates (org_label, space_label, app_label) in your tool calls
- Example: `Load app structure for myorg/myspace/myapp`

**"Failed to fetch app"**

- Verify your org/space/app coordinates are correct (check your Podio app URL)
- Ensure you have access to the specified app

**"Authentication failed"**

- Check your Client ID and Client Secret
- Verify the redirect URI matches your Podio API key settings

### Project/Epic Configuration Issues

**"Project field not found or not properly configured"**

- Your app may not have properly configured project/epic fields
- Use `Inspect field structure` to see available fields
- The server will automatically discover project/epic apps from any app reference fields

**"Failed to fetch projects/epics"**

- Check that project/epic apps exist and are accessible
- Verify app permissions - you need at least "reference" and "view" rights
- Use `List all projects` or `List all epics` to test connectivity
- Check the logs for specific error messages

**Project/Epic suggestions not working**

- Ensure project and epic data is loaded: run `List all projects` and `List all epics` first
- The suggestion algorithm requires project/epic titles and descriptions for matching
- Empty project/epic apps will result in "No strong matches found"
- Use `Suggest project and epic for "your task description"` with descriptive text

### Debug Mode

Run the server directly to see detailed error messages:

```bash
node build/index.js
```

### Logs

The server outputs status information to stderr, which you can view in Claude Desktop's logs.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:

1. Check the troubleshooting section
2. Review the example usage document
3. Open an issue on the repository

## Related Projects

- [Podio TUI](https://github.com/your-repo/podio-tui) - Terminal UI for Podio (the inspiration for this project)
- [Model Context Protocol](https://github.com/modelcontextprotocol/sdk) - The MCP SDK documentation