Mnemosyne MCP

Instructions

Implementation Reference

• src/neem/mcp/tools/hocuspocus.py:364-433 (handler)

  The @server.tool decorator registers the create_folder tool and provides the async handler function that executes the tool logic: authenticates, validates inputs, connects to workspace, uses WorkspaceWriter.upsert_folder in a transaction, and returns updated workspace snapshot.

  @server.tool(
      name="create_folder",
      title="Create Folder",
      description=(
          "Create a new folder in the workspace. "
          "Use parent_id to nest inside another folder (null for root level). "
          "The section parameter determines which sidebar section the folder appears in."
      ),
  )
  async def create_folder_tool(
      graph_id: str,
      folder_id: str,
      label: str,
      parent_id: Optional[str] = None,
      order: Optional[float] = None,
      section: str = "documents",
      context: Context | None = None,
  ) -> dict:
      """Create a new folder in the workspace via Y.js."""
      auth = MCPAuthContext.from_context(context)
      auth.require_auth()
  
      if not graph_id or not graph_id.strip():
          raise ValueError("graph_id is required and cannot be empty")
      if not folder_id or not folder_id.strip():
          raise ValueError("folder_id is required and cannot be empty")
      if not label or not label.strip():
          raise ValueError("label is required and cannot be empty")
      if section not in ("documents", "artifacts"):
          raise ValueError("section must be 'documents' or 'artifacts'")
  
      try:
          await hp_client.connect_workspace(graph_id.strip())
  
          # Create folder via Y.js transact
          await hp_client.transact_workspace(
              graph_id.strip(),
              lambda doc: WorkspaceWriter(doc).upsert_folder(
                  folder_id.strip(),
                  label.strip(),  # 'label' param → 'name' in Y.js
                  parent_id=parent_id.strip() if parent_id else None,
                  section=section,
                  order=order,
              ),
          )
  
          # Return workspace snapshot for confirmation
          snapshot = hp_client.get_workspace_snapshot(graph_id.strip())
  
          result = {
              "success": True,
              "folder_id": folder_id.strip(),
              "graph_id": graph_id.strip(),
              "label": label.strip(),
              "parent_id": parent_id.strip() if parent_id else None,
              "section": section,
              "workspace": snapshot,
          }
          return result
  
      except Exception as e:
          logger.error(
              "Failed to create folder",
              extra_context={
                  "graph_id": graph_id,
                  "folder_id": folder_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to create folder: {e}")

• src/neem/mcp/server/standalone_server.py:317-317 (registration)

  Calls register_hocuspocus_tools which defines and registers the create_folder tool (among others) on the FastMCP server instance.

  register_hocuspocus_tools(mcp_server)