ArchiveBox API

Instructions

Implementation Reference

• archivebox_api/archivebox_mcp.py:270-329 (handler)

  The primary MCP tool handler for 'get_snapshot'. This function is decorated with @mcp.tool, defining both the registration and the execution logic. It creates an ArchiveBox API client and calls its get_snapshot method to retrieve the snapshot data.

  @mcp.tool(
      exclude_args=[
          "archivebox_url",
          "username",
          "password",
          "token",
          "api_key",
          "verify",
      ],
      tags={"core"},
  )
  def get_snapshot(
      snapshot_id: str = Field(
          description="The ID or abid of the snapshot",
      ),
      with_archiveresults: bool = Field(
          True, description="Whether to include archiveresults"
      ),
      archivebox_url: str = Field(
          default=os.environ.get("ARCHIVEBOX_URL", None),
          description="The URL of the ArchiveBox instance",
      ),
      username: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_USERNAME", None),
          description="Username for authentication",
      ),
      password: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_PASSWORD", None),
          description="Password for authentication",
      ),
      token: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_TOKEN", None),
          description="Bearer token for authentication",
      ),
      api_key: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_API_KEY", None),
          description="API key for authentication",
      ),
      verify: Optional[bool] = Field(
          default=to_boolean(os.environ.get("ARCHIVEBOX_VERIFY", "True")),
          description="Whether to verify SSL certificates",
      ),
  ) -> dict:
      """
      Get a specific Snapshot by abid or id.
      """
      client = Api(
          url=archivebox_url,
          username=username,
          password=password,
          token=token,
          api_key=api_key,
          verify=verify,
      )
      response = client.get_snapshot(
          snapshot_id=snapshot_id,
          with_archiveresults=with_archiveresults,
      )
      return response.json()

• archivebox_api/archivebox_mcp.py:282-311 (schema)

  Pydantic Field definitions for the input schema of the get_snapshot tool, including descriptions and defaults.

  snapshot_id: str = Field(
      description="The ID or abid of the snapshot",
  ),
  with_archiveresults: bool = Field(
      True, description="Whether to include archiveresults"
  ),
  archivebox_url: str = Field(
      default=os.environ.get("ARCHIVEBOX_URL", None),
      description="The URL of the ArchiveBox instance",
  ),
  username: Optional[str] = Field(
      default=os.environ.get("ARCHIVEBOX_USERNAME", None),
      description="Username for authentication",
  ),
  password: Optional[str] = Field(
      default=os.environ.get("ARCHIVEBOX_PASSWORD", None),
      description="Password for authentication",
  ),
  token: Optional[str] = Field(
      default=os.environ.get("ARCHIVEBOX_TOKEN", None),
      description="Bearer token for authentication",
  ),
  api_key: Optional[str] = Field(
      default=os.environ.get("ARCHIVEBOX_API_KEY", None),
      description="API key for authentication",
  ),
  verify: Optional[bool] = Field(
      default=to_boolean(os.environ.get("ARCHIVEBOX_VERIFY", "True")),
      description="Whether to verify SSL certificates",
  ),

• archivebox_api/archivebox_api.py:219-246 (helper)

  Helper method in the Api class that performs the actual HTTP GET request to the ArchiveBox API endpoint /api/v1/core/snapshot/{snapshot_id} to fetch the snapshot data.

  @require_auth
  def get_snapshot(
      self, snapshot_id: str, with_archiveresults: bool = True
  ) -> requests.Response:
      """
      Get a specific Snapshot by abid or id
  
      Args:
          snapshot_id: The ID or abid of the snapshot.
          with_archiveresults: Whether to include archiveresults (default: True).
  
      Returns:
          Response: The response object from the GET request.
  
      Raises:
          ParameterError: If the provided parameters are invalid.
      """
      try:
          response = self._session.get(
              url=f"{self.url}/api/v1/core/snapshot/{snapshot_id}",
              params={"with_archiveresults": with_archiveresults},
              headers=self.headers,
              verify=self.verify,
          )
      except ValidationError as e:
          raise ParameterError(f"Invalid parameters: {e.errors()}")
      return response

• archivebox_api/archivebox_mcp.py:24-37 (helper)

  Utility helper function used to convert string environment variables to boolean for the 'verify' parameter.

  def to_boolean(string: Union[str, bool] = None) -> bool:
      if isinstance(string, bool):
          return string
      if not string:
          return False
      normalized = str(string).strip().lower()
      true_values = {"t", "true", "y", "yes", "1"}
      false_values = {"f", "false", "n", "no", "0"}
      if normalized in true_values:
          return True
      elif normalized in false_values:
          return False
      else:
          raise ValueError(f"Cannot convert '{string}' to boolean")

• archivebox_api/archivebox_mcp.py:270-279 (registration)

  The @mcp.tool decorator registers the get_snapshot function as an MCP tool, excluding certain auth args from the tool schema and tagging it as 'core'.

  @mcp.tool(
      exclude_args=[
          "archivebox_url",
          "username",
          "password",
          "token",
          "api_key",
          "verify",
      ],
      tags={"core"},