Heddle

One BoundOp. HTTP, OpenAPI, and MCP are hosts.

Docs: https://www.earlyeffect.rocks/heddle/

import heddle.* is a curated facade over heddle.http, heddle.route, heddle.endpoint, heddle.server, heddle.client, and heddle.error. SSE, WebSocket, and Datastar stay in their own packages.

Install

Core (ZIO only):

libraryDependencies += "rocks.earlyeffect" %% "heddle" % "0.11.0"

Optional artifacts, same version: heddle-mcp, heddle-mcp-protocol, heddle-mcp-apps, heddle-oauth, heddle-brotli.

Cross-build: %% is JVM. Use %%% for Scala.js and Scala Native. heddle, heddle-mcp, heddle-mcp-protocol, and heddle-mcp-apps publish on all three. heddle-oauth is JVM and JS. HeddleApp is JVM-only.

Routes

import heddle.*
import zio.*

val routes = Routes(
  Method.GET / "health"            -> Handler.text("ok"),
  Method.GET / "users" / int("id") -> { id =>
    ZIO.succeed(Response.text(id.toString))
  },
)

val app = routes @@ (Middleware.requestId() ++ Middleware.cors() ++ Middleware.debug)

object Hello extends HeddleApp:
  def routes = app

id is the name in int("id"). The parameter name is the capture name.

Promote selected endpoints with Api.job (or .mcp), then Mcp.from(api). Agents hit POST /mcp or a --mcp-stdio process. Swagger is api.openApi.routes("docs"). A browser is an HTTP client of api.routes.

Run the example hub

sbt example/run                      # box office + OP + Swagger at /docs, UI at /preview, MCP at /mcp
sbt "example/run -- --mcp-stdio"     # same Api on stdio

Grok Build against the running process:

[mcp_servers.heddle-example]
url = "http://localhost:8080/mcp"

Modules

Artifact	Depends on	Role
heddle	ZIO, zio-json, neotype	HTTP types, routes, middleware, Server.install (JVM, JS, Native), Schema, Endpoint, OpenAPI
heddle-mcp-protocol	zio-json	MCP wire types and codecs: JSON-RPC messages, requests, tools, results, resources
heddle-mcp	heddle, heddle-mcp-protocol	MCP 2026-07-28 over Api / BoundOp (HTTP/stdio also answer 2025-11-25 initialize)
heddle-mcp-apps	heddle-mcp	MCP Apps: sheds of typed grants, ui:// views, _meta.ui, and the policy a host clamps
heddle-oauth	heddle	JOSE, resource server, OAuth client, OIDC provider
heddle-brotli	heddle	RFC 7932 br encoder / decoder (no JNI)

JVM is JDK 21+. JS is Node. Native is POSIX plus OpenSSL. HeddleApp is JVM-only. Full guide: earlyeffect.rocks/heddle.