STAC MCP Server

Instructions

Implementation Reference

• stac_mcp/tools/search_collections.py:11-36 (handler)

  The core handler function that executes the search_collections tool logic: searches STAC collections using STACClient, handles JSON/text output formats, and formats results with titles, descriptions, and licenses.

  def handle_search_collections(
      client: STACClient,
      arguments: dict[str, Any],
  ) -> list[TextContent] | dict[str, Any]:
      limit = arguments.get("limit", 10)
      collections = client.search_collections(limit=limit)
      if arguments.get("output_format") == "json":
          return {
              "type": "collection_list",
              "count": len(collections),
              "collections": collections,
          }
      result_text = f"Found {len(collections)} collections:\n\n"
      for collection in collections:
          title = collection.get("title") or collection.get("id", "Untitled collection")
          identifier = collection.get("id", "unknown")
          result_text += f"**{title}** (`{identifier}`)\n"
          description = collection.get("description")
          if description:
              desc = str(description)
              truncated = desc[:MAX_DESC_PREVIEW]
              ellipsis = "..." if len(desc) > MAX_DESC_PREVIEW else ""
              result_text += f"  {truncated}{ellipsis}\n"
          license_value = collection.get("license", "unspecified")
          result_text += f"  License: {license_value}\n\n"
      return [TextContent(type="text", text=result_text)]

• stac_mcp/server.py:37-47 (registration)

  Registers the 'search_collections' tool with FastMCP server using @app.tool decorator, defines input parameters via type hints, and delegates execution to the internal execution module.

  @app.tool
  async def search_collections(
      limit: int | None = 10, catalog_url: str | None = None
  ) -> list[dict[str, Any]]:
      """Return a page of STAC collections."""
      return await execution.execute_tool(
          "search_collections",
          arguments={"limit": limit},
          catalog_url=catalog_url,
          headers=None,
      )

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

  Internal registration mapping the 'search_collections' tool name to its handler function (handle_search_collections) in the tool execution dispatcher.

  _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:27-27 (helper)

  Import of the search_collections handler into the execution module.

  from stac_mcp.tools.search_collections import handle_search_collections