MCP server for LogSeq

Instructions

Implementation Reference

• src/mcp_logseq/tools.py:271-355 (handler)

  UpdatePageToolHandler class: the core handler implementation for the 'update_page' tool. Includes schema definition and run_tool logic that validates inputs, calls the LogSeq API, and formats the response.

  class UpdatePageToolHandler(ToolHandler):
      def __init__(self):
          super().__init__("update_page")
  
      def get_tool_description(self):
          return Tool(
              name=self.name,
              description="Update a page in LogSeq with new content and/or properties.",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "page_name": {
                          "type": "string",
                          "description": "Name of the page to update"
                      },
                      "content": {
                          "type": "string",
                          "description": "New content to append to the page (optional)"
                      },
                      "properties": {
                          "type": "object",
                          "description": "Page properties to update (optional)",
                          "additionalProperties": True
                      }
                  },
                  "required": ["page_name"]
              }
          )
  
      def run_tool(self, args: dict) -> list[TextContent]:
          if "page_name" not in args:
              raise RuntimeError("page_name argument required")
  
          page_name = args["page_name"]
          content = args.get("content")
          properties = args.get("properties")
          
          # Validate that at least one update is provided
          if not content and not properties:
              return [TextContent(
                  type="text",
                  text="❌ Error: Either 'content' or 'properties' must be provided for update"
              )]
  
          try:
              api = logseq.LogSeq(api_key=api_key)
              result = api.update_page(page_name, content=content, properties=properties)
              
              # Build detailed success message
              success_msg = f"✅ Successfully updated page '{page_name}'"
              
              # Show what was updated
              updates = result.get("updates", [])
              update_details = []
              
              for update_type, update_result in updates:
                  if update_type == "properties":
                      update_details.append("📝 Properties updated")
                  elif update_type == "properties_fallback":
                      update_details.append("📝 Properties updated (via fallback method)")
                  elif update_type == "content":
                      update_details.append("📄 Content appended")
              
              if update_details:
                  success_msg += f"\n{chr(10).join(update_details)}"
              
              success_msg += f"\n🔄 Page '{page_name}' has been updated in LogSeq"
              
              return [TextContent(
                  type="text",
                  text=success_msg
              )]
          except ValueError as e:
              # Handle validation errors (page not found) gracefully
              return [TextContent(
                  type="text", 
                  text=f"❌ Error: {str(e)}"
              )]
          except Exception as e:
              logger.error(f"Failed to update page: {str(e)}")
              return [TextContent(
                  type="text",
                  text=f"❌ Failed to update page '{page_name}': {str(e)}"
              )]

• src/mcp_logseq/server.py:79-79 (registration)

  Registration of the UpdatePageToolHandler in the MCP server using add_tool_handler.

  add_tool_handler(tools.UpdatePageToolHandler())

• src/mcp_logseq/logseq.py:219-298 (helper)

  LogSeq.update_page method: the underlying API helper called by the tool handler to perform the actual LogSeq API calls for updating page content and properties, including fallback logic.

  def update_page(self, page_name: str, content: str = None, properties: dict = None) -> Any:
      """Update a LogSeq page with new content and/or properties."""
      url = self.get_base_url()
      logger.info(f"Updating page '{page_name}'")
      
      try:
          # Pre-update validation: verify page exists
          existing_pages = self.list_pages()
          page_names = [p.get("originalName") or p.get("name") for p in existing_pages if p.get("originalName") or p.get("name")]
          
          if page_name not in page_names:
              raise ValueError(f"Page '{page_name}' does not exist")
          
          results = []
          
          # Update properties if provided
          if properties:
              logger.debug(f"Updating properties for page '{page_name}': {properties}")
              try:
                  response = requests.post(
                      url,
                      headers=self._get_headers(),
                      json={
                          "method": "logseq.Editor.updatePage",
                          "args": [page_name, properties]
                      },
                      verify=self.verify_ssl,
                      timeout=self.timeout
                  )
                  response.raise_for_status()
                  prop_result = response.json()
                  results.append(("properties", prop_result))
              except Exception as e:
                  logger.warning(f"Failed to update properties with updatePage, trying setPageProperties: {str(e)}")
                  # Fallback to setPageProperties
                  response = requests.post(
                      url,
                      headers=self._get_headers(),
                      json={
                          "method": "logseq.Editor.setPageProperties",
                          "args": [page_name, properties]
                      },
                      verify=self.verify_ssl,
                      timeout=self.timeout
                  )
                  response.raise_for_status()
                  prop_result = response.json()
                  results.append(("properties_fallback", prop_result))
          
          # Update content if provided
          if content is not None:
              logger.debug(f"Updating content for page '{page_name}'")
              # Strategy: Get existing blocks and update them, or add new content
              # For now, we'll use appendBlockInPage to add new content
              # TODO: In future, implement block-level updates for more sophisticated content management
              
              response = requests.post(
                  url,
                  headers=self._get_headers(),
                  json={
                      "method": "logseq.Editor.appendBlockInPage",
                      "args": [page_name, content]
                  },
                  verify=self.verify_ssl,
                  timeout=self.timeout
              )
              response.raise_for_status()
              content_result = response.json()
              results.append(("content", content_result))
          
          logger.info(f"Successfully updated page '{page_name}'")
          return {"updates": results, "page": page_name}
  
      except ValueError:
          # Re-raise validation errors as-is
          raise
      except Exception as e:
          logger.error(f"Error updating page '{page_name}': {str(e)}")
          raise

• src/mcp_logseq/tools.py:276-298 (schema)

  Input schema definition for the 'update_page' tool, defining parameters: page_name (required), content (optional), properties (optional).

  return Tool(
      name=self.name,
      description="Update a page in LogSeq with new content and/or properties.",
      inputSchema={
          "type": "object",
          "properties": {
              "page_name": {
                  "type": "string",
                  "description": "Name of the page to update"
              },
              "content": {
                  "type": "string",
                  "description": "New content to append to the page (optional)"
              },
              "properties": {
                  "type": "object",
                  "description": "Page properties to update (optional)",
                  "additionalProperties": True
              }
          },
          "required": ["page_name"]
      }
  )