WorkFlowy MCP Server

Instructions

Implementation Reference

• src/workflowy_mcp/server.py:258-281 (handler)

  The handler function decorated with @mcp.tool() that implements the core logic: rate limiting, client retrieval, API call to complete_node, and error handling. Returns the updated node.

  @mcp.tool(name="workflowy_complete_node", description="Mark a WorkFlowy node as completed")
  async def complete_node(node_id: str) -> WorkFlowyNode:
      """Mark a WorkFlowy node as completed.
  
      Args:
          node_id: The ID of the node to complete
  
      Returns:
          The updated WorkFlowy node
      """
      client = get_client()
  
      if _rate_limiter:
          await _rate_limiter.acquire()
  
      try:
          node = await client.complete_node(node_id)
          if _rate_limiter:
              _rate_limiter.on_success()
          return node
      except Exception as e:
          if _rate_limiter and hasattr(e, "__class__") and e.__class__.__name__ == "RateLimitError":
              _rate_limiter.on_rate_limit(getattr(e, "retry_after", None))
          raise

• src/workflowy_mcp/models/node.py:8-137 (schema)

  Pydantic BaseModel defining the structure of WorkFlowyNode, used as the return type for the tool. Includes fields like id, name, note, completedAt, children, with validators and properties for compatibility.

  class WorkFlowyNode(BaseModel):
      """Represents a single node in the WorkFlowy outline hierarchy."""
  
      # API fields (what the API actually returns)
      id: str = Field(..., description="Unique identifier for the node")
      name: str | None = Field(
          None, validation_alias=AliasChoices("name", "nm"), description="Text content of the node"
      )
      note: str | None = Field(
          None,
          validation_alias=AliasChoices("note", "no"),
          description="Note content attached to the node",
      )
      priority: int | None = Field(None, description="Sort order")
      data: dict[str, Any] | None = Field(None, description="Node data including layoutMode")
      createdAt: int | None = Field(
          None,
          validation_alias=AliasChoices("createdAt", "created"),
          description="Creation timestamp (Unix timestamp)",
      )
      modifiedAt: int | None = Field(
          None,
          validation_alias=AliasChoices("modifiedAt", "modified"),
          description="Last modification timestamp",
      )
      completedAt: int | None = Field(
          None, description="Completion timestamp (null if not completed)"
      )
  
      # Nested structure fields
      children: list["WorkFlowyNode"] | None = Field(None, alias="ch", description="Child nodes")
      parent_id: str | None = Field(None, alias="parentId", description="Parent node ID")
  
      # Handle 'cp' field for backward compatibility - we'll compute from completedAt
      completed_flag: bool | None = Field(
          None, alias="cp", description="Completion status (for tests)"
      )
  
      @property
      def layoutMode(self) -> str | None:
          """Extract layoutMode from data field."""
          if self.data and isinstance(self.data, dict):
              return self.data.get("layoutMode")
          return None
  
      # Backward compatibility aliases for tests
      @property
      def nm(self) -> str | None:
          """Backward compatibility for name field."""
          return self.name
  
      @property
      def no(self) -> str | None:
          """Backward compatibility for note field."""
          return self.note
  
      @property
      def cp(self) -> bool:
          """Backward compatibility for completed status."""
          # Use completed_flag if it was set (from tests), otherwise check completedAt
          if self.completed_flag is not None:
              return self.completed_flag
          return self.completedAt is not None
  
      @property
      def ch(self) -> list["WorkFlowyNode"] | None:
          """Backward compatibility for children field."""
          return self.children
  
      @property
      def created(self) -> int:
          """Backward compatibility for created timestamp."""
          return self.createdAt or 0
  
      @property
      def modified(self) -> int:
          """Backward compatibility for modified timestamp."""
          return self.modifiedAt or 0
  
      @field_validator("id")
      @classmethod
      def validate_id(cls, v: str) -> str:
          """Ensure ID is non-empty."""
          if not v or not v.strip():
              raise ValueError("Node ID must be non-empty")
          return v
  
      @field_validator("createdAt", "modifiedAt", "completedAt")
      @classmethod
      def validate_timestamp(cls, v: int | None) -> int | None:
          """Ensure timestamps are positive."""
          if v is not None and v <= 0:
              raise ValueError("Timestamp must be positive")
          return v
  
      def model_dump(self, **kwargs: Any) -> dict[str, Any]:
          """Custom serialization to include backward compatibility fields."""
          data: dict[str, Any] = super().model_dump(**kwargs)
  
          # Add backward compatibility fields for tests
          data["nm"] = self.name
          data["no"] = self.note
          data["cp"] = self.cp
          data["ch"] = self.children
          data["created"] = self.createdAt or 0
          data["modified"] = self.modifiedAt or 0
  
          return data
  
      class Config:
          """Pydantic model configuration."""
  
          populate_by_name = True  # Allow both field names and aliases
          json_schema_extra = {
              "example": {
                  "id": "node-123",
                  "name": "Example Node",
                  "note": "This is a note",
                  "priority": 1,
                  "layoutMode": "bullets",
                  "createdAt": 1704067200,
                  "modifiedAt": 1704067200,
                  "completedAt": None,
                  "children": [],
              }
          }
  
  
  # Enable forward references for recursive model
  WorkFlowyNode.model_rebuild()

• src/workflowy_mcp/server.py:258-258 (registration)

  The @mcp.tool decorator that registers the complete_node function as the MCP tool named 'workflowy_complete_node'.

  @mcp.tool(name="workflowy_complete_node", description="Mark a WorkFlowy node as completed")