Memos MCP Server

Instructions

Implementation Reference

• server.py:132-190 (handler)

  The async handler function implementing the create_memo tool logic, which validates input, sends a POST request to the Memos API to create a memo, and returns formatted JSON response.

  async def create_memo(
      content: str,
      visibility: str = "PRIVATE"
  ) -> str:
      """
      Create a new memo.
      
      Args:
          content: The content of the memo (supports Markdown)
          visibility: Visibility level - PUBLIC, PROTECTED, or PRIVATE (default: PRIVATE)
      
      Returns:
          JSON string containing the created memo details
      """
      # Validate visibility
      valid_visibilities = ["PUBLIC", "PROTECTED", "PRIVATE"]
      visibility = visibility.upper()
      if visibility not in valid_visibilities:
          return f"Error: visibility must be one of {', '.join(valid_visibilities)}"
      
      # Build request payload
      payload = {
          "content": content,
          "visibility": visibility
      }
      
      try:
          async with httpx.AsyncClient() as client:
              response = await client.post(
                  f"{MEMOS_BASE_URL}/api/v1/memos",
                  json=payload,
                  headers=get_headers(),
                  timeout=30.0
              )
              response.raise_for_status()
              memo = response.json()
              
              # Format the response
              result = {
                  "success": True,
                  "memo": {
                      "name": memo.get("name"),
                      "uid": memo.get("uid"),
                      "creator": memo.get("creator"),
                      "content": memo.get("content"),
                      "visibility": memo.get("visibility"),
                      "pinned": memo.get("pinned", False),
                      "createTime": memo.get("createTime"),
                      "updateTime": memo.get("updateTime"),
                      "displayTime": memo.get("displayTime"),
                  }
              }
              
              return str(result)
              
      except httpx.HTTPError as e:
          return f"Error creating memo: {str(e)}"
      except Exception as e:
          return f"Unexpected error: {str(e)}"

• server.py:131-131 (registration)

  The @mcp.tool() decorator registers the create_memo function as an MCP tool, using its signature for schema inference.

  @mcp.tool()

• server.py:132-145 (schema)

  Function signature with type annotations defining input schema (content: str, visibility: str='PRIVATE') and output str, plus descriptive docstring.

  async def create_memo(
      content: str,
      visibility: str = "PRIVATE"
  ) -> str:
      """
      Create a new memo.
      
      Args:
          content: The content of the memo (supports Markdown)
          visibility: Visibility level - PUBLIC, PROTECTED, or PRIVATE (default: PRIVATE)
      
      Returns:
          JSON string containing the created memo details
      """

• server.py:21-28 (handler)

  Helper function used by create_memo to generate authentication headers for API requests.

  def get_headers() -> dict:
      """Get headers for API requests including authentication"""
      headers = {
          "Content-Type": "application/json",
      }
      if MEMOS_API_TOKEN:
          headers["Authorization"] = f"Bearer {MEMOS_API_TOKEN}"
      return headers