sieve_usage

Instructions

Implementation Reference

• src/sieve_mcp/server.py:139-151 (handler)

  The MCP tool handler definition for sieve_usage. It is decorated with @mcp.tool and calls client.usage() to check account usage.

  @mcp.tool(
      annotations={
          "readOnlyHint": True,
          "destructiveHint": False,
          "openWorldHint": True,
      }
  )
  async def sieve_usage() -> dict:
      """Check your Sieve API usage for the current billing period.
  
      Shows screens used, monthly limit, tier, and organization name.
      """
      return await client.usage()

• src/sieve_mcp/client.py:149-151 (helper)

  The client.usage() function called by sieve_usage. It makes a GET request to the /usage endpoint of the Sieve Public API.

  async def usage() -> dict[str, Any]:
      """Check API usage for the current billing period."""
      return await _request("GET", "/usage")

• src/sieve_mcp/client.py:40-110 (helper)

  The underlying _request() helper that executes the HTTP request and handles errors, used by the usage() function.

  async def _request(
      method: str,
      path: str,
      *,
      json_body: dict[str, Any] | None = None,
      timeout: float = 15.0,
  ) -> dict[str, Any]:
      """Execute an HTTP request and return the JSON response or an error dict."""
      if not SIEVE_API_KEY:
          return {
              "error": "Missing API key",
              "detail": "Set the SIEVE_API_KEY environment variable. "
              "Get your key at https://app.sieve.arceusxventures.com/settings",
          }
  
      url = f"{SIEVE_API_URL.rstrip('/')}{_BASE}{path}"
      start = time.monotonic()
      result: dict[str, Any] = {}
  
      try:
          async with httpx.AsyncClient(timeout=timeout) as client:
              response = await client.request(
                  method, url, headers=_headers(), json=json_body
              )
              response.raise_for_status()
              result = response.json()
              return result  # type: ignore[no-any-return]
  
      except httpx.HTTPStatusError as exc:
          try:
              body = exc.response.json()
          except Exception:
              body = exc.response.text
          result = {
              "error": f"HTTP {exc.response.status_code}",
              "detail": body,
          }
          return result
  
      except httpx.TimeoutException:
          result = {
              "error": "Request timed out",
              "detail": f"The request to {path} timed out after {timeout}s.",
          }
          return result
  
      except httpx.RequestError as exc:
          result = {
              "error": "Connection error",
              "detail": str(exc),
          }
          return result
  
      finally:
          duration_ms = round((time.monotonic() - start) * 1000)
          try:
              if _posthog is not None:
                  _posthog.capture(
                      distinct_id=_anonymous_user_id(),
                      event="mcp_tool_called",
                      properties={
                          "tool": path.split("/")[1] if "/" in path else path,
                          "method": method,
                          "path": path,
                          "duration_ms": duration_ms,
                          "success": "error" not in result,
                          "error": result.get("error"),
                      },
                  )
          except Exception:
              pass  # Never let analytics break the tool

• src/sieve_mcp/server.py:139-145 (registration)

  The @mcp.tool decorator with annotations registers sieve_usage as an MCP tool.

  @mcp.tool(
      annotations={
          "readOnlyHint": True,
          "destructiveHint": False,
          "openWorldHint": True,
      }
  )