# WorkFlowy MCP Server

A Model Context Protocol (MCP) server that integrates WorkFlowy's outline and task management capabilities with LLM applications.

## MCP Tools Available

| Tool | Description |
|------|-------------|
| `workflowy_create_node` | Create new nodes with name, notes, and layout mode |
| `workflowy_update_node` | Update existing node properties |
| `workflowy_get_node` | Retrieve a specific node by ID |
| `workflowy_list_nodes` | List child nodes of a specific parent |
| `workflowy_delete_node` | Delete a node and its children |
| `workflowy_complete_node` | Mark a node as completed |
| `workflowy_uncomplete_node` | Mark a node as uncompleted |

## ⚠️ Important Limitations

**The WorkFlowy API has significant discovery limitations:**

- ✅ **CAN** list root-level nodes (call `list_nodes` without parent_id)
- ✅ **CAN** navigate down the tree by listing children of discovered nodes
- ❌ **CANNOT** search for nodes by name or content
- ❌ **CANNOT** jump directly to deeply nested nodes
- ❌ **CANNOT** use node IDs from WorkFlowy web URLs (they use different IDs)

**Practical Impact:**

- You must navigate hierarchically from root to find existing nodes
- No text search means manually traversing the tree to find specific content
- Deep nodes require multiple list operations to reach
- The web interface IDs (`workflowy.com/#/abc123`) are NOT compatible with API IDs

## Quick Start

### Prerequisites

- Python 3.10 or higher
- WorkFlowy account with API access
- Claude Desktop or other (local, since it's a python package) MCP-compatible client

### Installation

#### Option 1: Install from PyPI (Recommended)

```bash
# Install the package
pip install workflowy-mcp
```

#### Option 2: Quick Setup Script

```bash
# Download and run the setup script
curl -sSL https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.sh | bash

# Or on Windows:
# irm https://raw.githubusercontent.com/yourusername/workflowy-mcp/main/install.ps1 | iex
```

#### Option 3: Manual Installation from Source

```bash
# Clone the repository (if you want to contribute or modify)
git clone https://github.com/vladzima/workflowy-mcp.git
cd workflowy-mcp
pip install -e .
```

### Configuration

1. **Get your WorkFlowy API key**:

   - From [WorkFlowy](https://beta.workflowy.com/api-key)

1. **Configure client**:
   Edit your client configuration (Claude Desktop example):

   - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

   Add to the `mcpServers` section:

   ```json
   {
     "mcpServers": {
       "workflowy": {
         "command": "python3",
         "args": ["-m", "workflowy_mcp"],
         "env": {
           "WORKFLOWY_API_KEY": "your_actual_api_key_here",
           // Optional settings (uncomment to override defaults):
           // "WORKFLOWY_API_URL": "https://workflowy.com/api/v1",
           // "WORKFLOWY_REQUEST_TIMEOUT": "30",
           // "WORKFLOWY_MAX_RETRIES": "3",
           // "WORKFLOWY_RATE_LIMIT_REQUESTS": "60",
           // "WORKFLOWY_RATE_LIMIT_WINDOW": "60"
         }
       }
     }
   }
   ```

1. **Restart your client** to load the MCP server

## Usage

Once configured, you can use WorkFlowy tools with your agent:

### Working with New Nodes

```
"Create a new WorkFlowy node called 'Project Tasks'"
# Returns: Created node with ID: abc-123-def

"Create a todo item 'Review PR' under parent node abc-123-def"

"Mark the node abc-123-def as completed"

"List all children of node abc-123-def"
```

### Navigating Existing Nodes

Since there's no search, you must navigate from root:

```
"List my root-level WorkFlowy nodes"
# Returns: List of top-level nodes with their IDs

"List children of node abc-123-def"
# Navigate deeper into your outline

"Get details for node abc-123-def"

"Update node abc-123-def with new notes"
```

**Note:** The node IDs from the web interface URLs are NOT compatible with the API.

## Development

### Setup Development Environment

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=workflowy_mcp

# Run linting
ruff check src/
mypy src/
black src/ --check
```

### Project Structure

```
workflowy-mcp/
├── src/
│   └── workflowy_mcp/
│       ├── __init__.py
│       ├── __main__.py          # Entry point
│       ├── server.py            # FastMCP server & tools
│       ├── config.py            # Configuration
│       ├── transport.py         # STDIO transport
│       ├── client/
│       │   ├── api_client.py    # WorkFlowy API client
│       │   ├── rate_limit.py    # Rate limiting
│       │   └── retry.py         # Retry logic
│       ├── models/
│       │   ├── node.py          # Node models
│       │   ├── requests.py      # Request models
│       │   ├── config.py        # Config models
│       │   └── errors.py        # Error models
│       └── middleware/
│           ├── errors.py        # Error handling
│           └── logging.py       # Request logging
├── tests/
│   ├── contract/                # Contract tests
│   ├── integration/              # Integration tests
│   ├── unit/                     # Unit tests
│   └── performance/              # Performance tests
├── pyproject.toml                # Project configuration
├── README.md                     # This file
├── CONTRIBUTING.md               # Contribution guide
├── install.sh                    # Unix/Mac installer
└── install.ps1                   # Windows installer
```

### Running Tests

```bash
# Run all tests
pytest

# Run specific test categories
pytest tests/unit/
pytest tests/contract/
pytest tests/integration/
pytest tests/performance/

# Run with coverage report
pytest --cov=workflowy_mcp --cov-report=html

# Run with verbose output
pytest -xvs
```

## API Reference

### Node Structure

```python
{
    "id": "unique-node-id",
    "name": "Node name",                  # Text content
    "note": "Node notes/description",     # Optional notes
    "layoutMode": "bullets",              # Display mode: bullets, todo, h1, h2, h3
    "completedAt": null,                  # Completion timestamp (null if not completed)
    "children": [],                       # Child nodes array
    "createdAt": 1234567890,              # Unix timestamp
    "modifiedAt": 1234567890               # Unix timestamp
}
```

### Error Handling

All tools return a consistent error format:

```json
{
    "success": false,
    "error": "error_type",
    "message": "Human-readable error message",
    "context": {...}  // Additional error context
}
```

## Performance

- Automatic rate limiting prevents API throttling
- Token bucket algorithm for smooth request distribution
- Adaptive rate limiting based on API responses
- Connection pooling for efficient HTTP requests

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- [Report bugs](https://github.com/vladzima/workflowy-mcp/issues)
- [Request features](https://github.com/vladzima/workflowy-mcp/issues)

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
- Integrates with [WorkFlowy API](https://beta.workflowy.com/api-reference/)
- Compatible with [Claude Desktop](https://claude.ai/desktop) and other MCP clients