Synapse MCP Server

Instructions

Implementation Reference

• src/synapse_mcp/tools.py:44-55 (handler)

  Executes the core logic of the get_entity tool: input validation, retrieves entity operations from context state, and calls get_entity_by_id on the base operations.

  def get_entity(entity_id: str, ctx: Context) -> Dict[str, Any]:
      """Return Synapse entity metadata by ID (projects, folders, files, tables, etc.)."""
      if not validate_synapse_id(entity_id):
          return {"error": f"Invalid Synapse ID: {entity_id}"}
  
      try:
          entity_ops = get_entity_operations(ctx)
          return entity_ops["base"].get_entity_by_id(entity_id)
      except ConnectionAuthError as exc:
          return {"error": f"Authentication required: {exc}", "entity_id": entity_id}
      except Exception as exc:  # pragma: no cover - defensive path
          return {"error": str(exc), "entity_id": entity_id}

• src/synapse_mcp/tools.py:34-43 (registration)

  The @mcp.tool decorator registers the 'get_entity' function as an MCP tool, defining its title, description, and operational hints.

  @mcp.tool(
      title="Fetch Entity",
      description="Return Synapse entity metadata by ID (projects, folders, files, tables, etc.). Only retrieves metadata information - does not download file content.",
      annotations={
          "readOnlyHint": True,
          "idempotentHint": True,
          "destructiveHint": False,
          "openWorldHint": True,
      },
  )

• src/synapse_mcp/entities/base.py:11-24 (helper)

  Implements the low-level retrieval of Synapse entity metadata using the Synapse client, called by the tool handler.

  def get_entity_by_id(self, entity_id: str) -> Dict[str, Any]:
      """Get an entity by ID.
  
      Args:
          entity_id: The Synapse ID of the entity
  
      Returns:
          The entity as a dictionary
      """
      # IMPORTANT: Always keep downloadFile=False to avoid downloading file content
      # when fetching entity metadata. This prevents unnecessary downloads and
      # keeps the operation lightweight for metadata-only operations.
      entity = self.synapse_client.get(entity_id, downloadFile=False)
      return self.format_entity(entity)

• src/synapse_mcp/context_helpers.py:47-65 (helper)

  Factory function that retrieves or lazily initializes per-connection entity operations (including base operations) from the MCP context state.

  def get_entity_operations(ctx: Context) -> Dict[str, Any]:
      """Get entity operations for this connection's synapseclient."""
      synapse_client = get_synapse_client(ctx)
  
      entity_ops = ctx.get_state("entity_ops")
      if entity_ops:
          return entity_ops
  
      entity_ops = {
          "base": BaseEntityOperations(synapse_client),
          "project": ProjectOperations(synapse_client),
          "folder": FolderOperations(synapse_client),
          "file": FileOperations(synapse_client),
          "table": TableOperations(synapse_client),
          "dataset": DatasetOperations(synapse_client),
      }
  
      ctx.set_state("entity_ops", entity_ops)
      return entity_ops