Mnemosyne MCP

Instructions

Implementation Reference

• src/neem/mcp/tools/hocuspocus.py:706-772 (handler)

  The @server.tool decorator registers the tool and defines its metadata (name, title, description). The async rename_artifact_tool function is the core handler that authenticates, validates inputs, verifies the artifact exists in the workspace, performs the rename via Y.js WorkspaceWriter.update_artifact in a transaction, fetches updated workspace snapshot, and returns success response with details.

  @server.tool(
      name="rename_artifact",
      title="Rename Artifact",
      description="Rename an artifact's display label.",
  )
  async def rename_artifact_tool(
      graph_id: str,
      artifact_id: str,
      new_label: str,
      context: Context | None = None,
  ) -> dict:
      """Rename an artifact 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 artifact_id or not artifact_id.strip():
          raise ValueError("artifact_id is required and cannot be empty")
      if not new_label or not new_label.strip():
          raise ValueError("new_label is required and cannot be empty")
  
      try:
          await hp_client.connect_workspace(graph_id.strip())
  
          # Verify artifact exists
          channel = hp_client._workspace_channels.get(graph_id.strip())
          if channel is None:
              raise RuntimeError(f"Workspace not connected: {graph_id}")
  
          reader = WorkspaceReader(channel.doc)
          current = reader.get_artifact(artifact_id.strip())
  
          if not current:
              raise RuntimeError(f"Artifact '{artifact_id}' not found in graph '{graph_id}'")
  
          # Update artifact name via Y.js
          await hp_client.transact_workspace(
              graph_id.strip(),
              lambda doc: WorkspaceWriter(doc).update_artifact(
                  artifact_id.strip(),
                  name=new_label.strip(),
              ),
          )
  
          snapshot = hp_client.get_workspace_snapshot(graph_id.strip())
  
          result = {
              "success": True,
              "artifact_id": artifact_id.strip(),
              "graph_id": graph_id.strip(),
              "new_label": new_label.strip(),
              "workspace": snapshot,
          }
          return result
  
      except Exception as e:
          logger.error(
              "Failed to rename artifact",
              extra_context={
                  "graph_id": graph_id,
                  "artifact_id": artifact_id,
                  "error": str(e),
              },
          )
          raise RuntimeError(f"Failed to rename artifact: {e}")

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

  The register_hocuspocus_tools function is called during server creation to register all hocuspocus tools, including rename_artifact, to the FastMCP server instance.

  register_hocuspocus_tools(mcp_server)