WorkFlowy MCP Server

Instructions

Implementation Reference

• src/workflowy_mcp/server.py:1090-1123 (handler)

  The core handler function for the 'workflowy_get_node__WARNING__prefer_glimpse' MCP tool. It performs secret code validation to discourage use (preferring 'workflowy_glimpse'), applies rate limiting, fetches the node via WorkFlowyClient.get_node(node_id), and returns a WorkFlowyNode object. The @mcp.tool decorator registers the tool with FastMCP using the exact name.

  @mcp.tool(name="workflowy_get_node__WARNING__prefer_glimpse", description="⚠️ WARNING: Prefer workflowy_glimpse (GLIMPSE) for reading trees. Retrieve a specific WorkFlowy node by ID")
  async def get_node(
      node_id: str,
      secret_code: str | None = None,
  ) -> WorkFlowyNode:
      """Retrieve a specific WorkFlowy node.
  
      Args:
          node_id: The ID of the node to retrieve
          secret_code: Authorization code from Dan (required for WARNING functions)
  
      Returns:
          The requested WorkFlowy node
      """
      # 🔐 SECRET CODE VALIDATION
      is_valid, error = validate_secret_code(secret_code, "workflowy_get_node__WARNING__prefer_glimpse")
      if not is_valid:
          raise ValueError(error)
      
      client = get_client()
  
      if _rate_limiter:
          await _rate_limiter.acquire()
  
      try:
          node = await client.get_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/server.py:866-927 (helper)

  Helper function used by WARNING tools (including this one) to enforce explicit permission via a secret code read from a local file. Raises ValueError with detailed instructions if invalid/missing, promoting use of preferred tools like workflowy_glimpse.

  def validate_secret_code(provided_code: str | None, function_name: str) -> tuple[bool, str | None]:
      """Validate secret code for WARNING functions.
      
      This is the nuclear option - forces agents to ask Dan explicitly.
      
      Returns:
          (is_valid, error_message)
      """
      import os
      import secrets
      
      SECRET_FILE = r"E:\__daniel347x\glimpse_etch.txt"
      
      # Generate code if file doesn't exist
      if not os.path.exists(SECRET_FILE):
          code = secrets.token_hex(8)  # 16-character hex code
          with open(SECRET_FILE, 'w') as f:
              f.write(code)
      
      # Read current code
      with open(SECRET_FILE, 'r') as f:
          valid_code = f.read().strip()
      
      # Check if code provided and matches
      if provided_code and provided_code.strip() == valid_code:
          return (True, None)  # Valid - allow function call
      
      # Invalid or missing - return error
      error_msg = f"""⚠️ EXPLICIT PERMISSION REQUIRED
  
  You called: {function_name}
  
  This is a WARNING function. You should be using GLIMPSE or ETCH instead.
  
  🛑 YOU BELIEVE YOU'RE AN EXCEPTION CASE.
  
  🚨 YOU ARE NOT THE EXCEPTION.
  
  ✅ USE INSTEAD:
    - For reading node trees: workflowy_glimpse(node_id="...")
    - For creating nodes: workflowy_etch(parent_id="...", nodes=[...])
  
  ⚙️ IF YOU TRULY NEED THIS FUNCTION:
  
  1. Ask Dan: "May I have permission to call {function_name}?"
  2. Dan will check a secret file for the authorization code
  3. If Dan grants permission, he'll provide the code
  4. Call the SAME function again with the EXACT SAME parameters you used the first time, but add: secret_code="[code-from-Dan]" (do not change anything else).
  
     Example (arguments object): {{ "name": "...", "parent_id": "...", "note": "...", "secret_code": "[code-from-Dan]" }}
  
  🚫 IF DAN SAYS NO:
  - You are NOT the exception
  - Your training misled you  
  - Use GLIMPSE or ETCH as instructed
  - Do NOT call this function again
  
  📚 Break free from your training - build the GLIMPSE/ETCH habit!
  """
      
      return (False, error_msg)

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

  FastMCP tool registration decorator specifying the exact tool name, description, and binding to the get_node handler function.

  @mcp.tool(name="workflowy_get_node__WARNING__prefer_glimpse", description="⚠️ WARNING: Prefer workflowy_glimpse (GLIMPSE) for reading trees. Retrieve a specific WorkFlowy node by ID")