goldziher/spikard

Install · Why spikard · Quick example · MCP server · Docs

---

[!IMPORTANT] spikard is experimental and pre-1.0. APIs change between releases, and not every binding is at the same level of maturity. It is not yet recommended for production.

That is also the invitation: this is the point where feedback actually shapes the design. If you try it and something is wrong, awkward, or missing, please open an issue. If you want to help, good first issues are scoped to be finishable in an evening, and CONTRIBUTING.md explains the generated-bindings workflow.

Why spikard

Installation

Each binding ships through its native package manager.

Quick example

Python

from spikard import Spikard
from msgspec import Struct

class User(Struct):
    id: int
    name: str

app = Spikard()

@app.get("/users/{id:int}")
async def get_user(id: int) -> User:
    return User(id=id, name="Alice")

if __name__ == "__main__":
    app.run(port=8000)

TypeScript

import { Spikard } from "@spikard/node";

const app = new Spikard();

app.get("/users/{id:int}", async (id: number) => {
  return { id, name: "Alice" };
});

app.run({ port: 8000 });

MCP server

The CLI ships an MCP server so a coding agent can scaffold and generate spikard projects directly. It is enabled by default (spikard-cli feature mcp) and speaks stdio out of the box; streamable HTTP is available via the mcp-http feature.

{
  "mcpServers": {
    "spikard": {
      "command": "spikard",
      "args": ["mcp"]
    }
  }
}

Thirteen tools are exposed, covering project init, codegen from every supported spec format, the SQL→HTTP pipeline, AsyncAPI fixture and test-app generation, schema validation, and a feature summary. See the MCP documentation for the full tool list and worked flows.

SQL to HTTP

Annotate a SQL query and spikard emits the route, an OpenAPI 3.1 fragment, and a typed handler stub that calls into the generated query function:

-- @name GetUser
-- @returns :one
-- @http GET /users/{id}
-- @http_auth bearer:jwt
SELECT id, name, email FROM users WHERE id = $1;

Query parsing and type inference come from scythe; spikard reads scythe’s analyzed-query IR and overlays the HTTP vocabulary on top. scythe stays library-agnostic and owns no HTTP concepts. See the SQL codegen guide.

Architecture

All bindings call a shared Rust core through thin language-native layers:

Development

task setup     # Install dependencies
task build     # Build Rust core (debug)
task test      # Run Rust tests
task test:all  # Run all tests (Rust + bindings)
task e2e:all   # Generate + build + run e2e tests
task format    # Format all code

Run task --list for the full task catalog.

License

MIT License — see LICENSE for details.