WorkFlowy MCP Server

WorkFlowy MCP服务器

一种模型上下文协议（MCP）服务器，将WorkFlowy的大纲和任务管理功能与LLM应用程序集成在一起。

MCP工具可用

⚠️ 重要限制

WorkFlowy API具有显著的发现限制：

• ✅ 控制器局域网 列出根级节点（调用 list_nodes 没有parent_id）
• ✅ 控制器局域网 通过列出已发现节点的子节点在树中导航
• ❌ 不能 按名称或内容搜索节点
• ❌ 不能 直接跳转到深度嵌套的节点
• ❌ 不能 使用WorkFlowy web URL中的节点ID（它们使用不同的ID）

实际影响：

• 您必须从根目录分层导航以查找现有节点
• 无文本搜索意味着手动遍历树以查找特定内容
• 深度节点需要多个列表操作才能到达
• web界面ID(workflowy.com/#/abc123)与API ID不兼容

快速开始

先决条件

• Python 3.10或更高版本
• 具有API访问权限的WorkFlowy帐户
• Claude Desktop或其他（本地，因为它是一个python包）MCP兼容客户端

安装

选项1：从PyPI安装（推荐）

# Install the package
pip install workflowy-mcp

选项2：快速设置脚本

# 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

选项3：从源手动安装

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

配置

1. 获取您的WorkFlowy API密钥:

- 自 WorkFlowy

1. 配置客户端:

编辑您的客户端配置（Claude Desktop示例）：

- 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

添加到 mcpServers 章节：

   {
     "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. 重新启动客户端 加载MCP服务器

用法

配置后，您可以将WorkFlowy工具与您的代理一起使用：

使用新节点

"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"

浏览现有节点

由于没有搜索，您必须从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"

注： web界面URL中的节点ID与API不兼容。

发展

设置开发环境

# 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

项目结构

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

运行测试

# 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 参考

节点结构

{
    "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
}

错误处理

所有工具返回一致的错误格式：

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

演出

• 自动速率限制阻止API节流
• 用于平滑请求分配的令牌桶算法
• 基于API响应的自适应速率限制
• 连接池用于高效的HTTP请求

贡献

看 贡献.md 用于开发设置和贡献指南。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 报告错误
• 请求功能

致谢

• 建于 FastMCP 框架
• 与集成 工作流API
• 兼容 克劳德桌面版 以及其他MCP客户端