Skip to content

Spider-Gazelle#

A fast, type-safe web framework for Crystal. You write ordinary, documented methods; Spider-Gazelle turns them into HTTP routes, validated parameters, an OpenAPI description and MCP tools for AI agents, all from that one source.

One method, four jobs#

class Rooms < AC::Base
  base "/rooms"

  # Books a meeting room
  @[AC::Route::POST("/:id/bookings", body: :booking, status_code: HTTP::Status::CREATED)]
  def book(
    @[AC::Param::Info(description: "the room to book", example: "lvl3-boardroom")]
    id : String,
    booking : Booking,
  ) : Booking
    Room.find!(id).book(booking)
  end
end

From that method you get:

What you get Driven by
HTTP route POST /rooms/:id/bookings, returning 201 Created the route annotation
Validation id and the JSON body are parsed and type checked before your code runs. Bad input gets a 4xx with a helpful error argument types
OpenAPI an operation with a summary, a described path parameter, and request and response schemas the doc comment, Param::Info and types
MCP tool rooms_book, which an AI agent can call with the same validation and the same filters all of the above

Why this matters

Hand-written API docs and agent tool definitions drift from the code, and drifted docs are worse than none. Spider-Gazelle derives them from the code itself. Rename a parameter, change a type or update a comment, and the OpenAPI document and MCP tools update with it. There's one source of truth to review and test, and no second copy to forget.

Highlights#

  • Type-safe routing. Parameters arrive as method arguments, already converted to Int32, UUID, Time, enums or your own types. There's no params["id"] boilerplate.
  • Self documenting. OpenAPI 3 is generated from your comments and types. Generate API clients in any language from it.
  • AI ready. A built-in MCP server exposes your API to Claude, VS Code, Cursor and other agents. It includes progressive tool discovery, prompts, and OAuth sign-in.
  • Content negotiation. Request bodies are parsed by Content-Type and responses rendered by Accept. JSON is the default; add YAML, XML or your own formats.
  • Fast. It's compiled Crystal, with LuckyRouter route matching and optional multi-core execution contexts.
  • Simple to test. The spec helper drives your app in-process, with no server to start.
  • You're in control. There's no hidden magic in your project: you own the entry point, the CLI, the configuration and the server lifecycle.

Choose your path#

Built by#

Place Technology, a team in Sydney and Brisbane, Australia. Spider-Gazelle powers the PlaceOS smart building platform. The framework is developed on GitHub.

Example apps#