STAC MCP Server

Instructions

Implementation Reference

• stac_mcp/tools/get_queryables.py:12-32 (handler)

  The core handler function that executes the get_queryables tool logic: fetches queryables from STACClient and formats as preview text or JSON.

  def handle_get_queryables(
      client: STACClient,
      arguments: dict[str, Any],
  ) -> list[TextContent] | dict[str, Any]:
      collection_id = arguments.get("collection_id")
      data = client.get_queryables(collection_id=collection_id)
      if arguments.get("output_format") == "json":
          return {"type": "queryables", **data}
      props = data.get("queryables", {})
      result_text = "**Queryables**\n\n"
      if not props:
          result_text += data.get("message", "No queryables available") + "\n"
          return [TextContent(type="text", text=result_text)]
      result_text += f"Collection: {collection_id or 'GLOBAL'}\n"
      result_text += f"Count: {len(props)}\n\n"
      for name, spec in list(props.items())[:PREVIEW_LIMIT]:
          typ = spec.get("type", "unknown") if isinstance(spec, dict) else "unknown"
          result_text += f"  - {name}: {typ}\n"
      if len(props) > PREVIEW_LIMIT:
          result_text += f"  ... and {len(props) - PREVIEW_LIMIT} more\n"
      return [TextContent(type="text", text=result_text)]

• stac_mcp/prompts/prompts.py:449-490 (schema)

  JSON schema and prompt definition for the get_queryables tool, specifying input parameters (collection_id optional string).

  @app.prompt(
      name="tool_get_queryables_prompt",
      description="Usage for get_queryables tool",
      meta={
          "schema": {
              "type": "object",
              "properties": {
                  "collection_id": {"type": "string"},
                  "catalog_url": {"type": "string"},
              },
              "required": [],
          },
          "example": {"collection_id": "my-collection"},
      },
  )
  def _prompt_get_queryables() -> PromptMessage:
      schema = {
          "type": "object",
          "properties": {
              "collection_id": {"type": "string"},
              "catalog_url": {"type": "string"},
          },
          "required": [],
      }
      payload = {
          "name": "get_queryables",
          "description": "Fetch STAC API (or collection) queryables.",
          "parameters": schema,
          "example": {"collection_id": "my-collection"},
      }
      human = (
          f"Tool: get_queryables\nDescription: {payload['description']}\n\n"
          "Parameters:\n"
          f"{json.dumps(schema, indent=2)}\n\n"
          "Example:\n"
          f"{json.dumps(payload['example'], indent=2)}"
      )
      return PromptMessage(
          role="user",
          content=TextContent(type="text", text=human),
          _meta={"machine_payload": payload},
      )

• stac_mcp/server.py:145-157 (registration)

  Primary MCP server registration of the get_queryables tool using FastMCP @app.tool decorator, dispatching to execution layer.

  @app.tool
  async def get_queryables(
      collection_id: list[str],
      catalog_url: str | None = None,
  ) -> list[dict[str, Any]]:
      """Get the queryable properties for a specific STAC collection by its ID."""
      return await execution.execute_tool(
          "get_queryables",
          {"collection_id": collection_id},
          catalog_url=catalog_url,
          headers=None,
      )

• stac_mcp/tools/execution.py:56-67 (registration)

  Central tool handler registry dictionary mapping tool name 'get_queryables' to its handler function.

  _TOOL_HANDLERS: dict[str, Handler] = {
      "search_collections": handle_search_collections,
      "get_collection": handle_get_collection,
      "search_items": handle_search_items,
      "get_item": handle_get_item,
      "estimate_data_size": handle_estimate_data_size,
      "get_root": handle_get_root,
      "get_conformance": handle_get_conformance,
      "get_queryables": handle_get_queryables,
      "get_aggregations": handle_get_aggregations,
      "sensor_registry_info": handle_sensor_registry_info,
  }

• stac_mcp/tools/execution.py:25-25 (helper)

  Import of the get_queryables handler into the execution module.

  from stac_mcp.tools.get_queryables import handle_get_queryables