hyperserve

HyperServe

A Go HTTP framework with built-in MCP (Model Context Protocol) support. The runtime has one transitive dependency: golang.org/x/time. (The go.mod tool directive pulls in golang.org/x/tools for the modernize check gate; those are build-time only and don't ship in your binary.)

The point: a small net/http-shaped server that ships an MCP control plane in the same binary, so AI assistants can introspect and operate the server without an out-of-process bridge.

Quick Start

import (
    "fmt"
    "net/http"

    server "github.com/osauer/hyperserve/pkg/server"
)

func main() {
    srv, _ := server.NewServer()

    srv.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello, World!")
    })

    srv.Run()
}

Install

go get github.com/osauer/hyperserve/pkg/server

What's in the box

• HTTP server built on net/http, with grouping, middleware chain, and graceful shutdown.
• MCP server (HTTP, SSE, stdio transports) with discovery endpoints and namespace support.
• WebSocket implementation (RFC 6455).
• JSON-RPC 2.0 engine reused by MCP.
• Middleware: recovery, request logging, metrics, CORS, security headers, rate limiting, auth.
• Static file serving sandboxed via os.Root.
• Deferred-init lifecycle: serve /healthz immediately while bootstrap work runs in the background.

Scaffold a new service

go install github.com/osauer/hyperserve/cmd/hyperserve-init@latest
hyperserve-init --module github.com/acme/payments
cd payments
go run ./cmd/server

Flags: --name (display name), --out (output directory), --with-mcp=false to opt out of MCP, --local-replace to develop against a local checkout.

MCP

HS_MCP_ENABLED=true
HS_MCP_SERVER_NAME=MyServer
HS_MCP_SERVER_VERSION=1.0.0

Or programmatically:

srv, _ := server.NewServer(
    server.WithMCPSupport("MyServer", "1.0.0"),
    server.WithMCPBuiltinTools(true),
    server.WithMCPBuiltinResources(true),
)

Built-in MCP tools and resources are off by default; you opt in per server.

Middleware

NewServer wires recovery, request logging, and metrics. Apply security stacks per route:

srv, _ := server.NewServer()
srv.AddMiddleware("/api", server.RateLimitMiddleware(srv))
srv.AddMiddlewareStack("/web", server.SecureWeb(srv.Options))

Deferred initialization

Serve /healthz immediately, return 503 for application routes, flip to ready once bootstrap (and any WithOnReady hooks) succeed:

srv, _ := server.NewServer(
    server.WithDeferredInit(func(ctx context.Context, app *server.Server) error {
        return warmCaches(ctx)
    }),
    server.WithOnReady(func(ctx context.Context, app *server.Server) error {
        app.HandleFunc("/api/users", usersHandler)
        return nil
    }),
)

Use WithDeferredInitStopOnFailure(false) to keep the listener up after a bootstrap failure, then call CompleteDeferredInit(ctx, nil) once the issue is resolved.

See examples/deferred-init.

Examples

examples/ covers HTTP, WebSocket, MCP (HTTP/SSE/stdio/discovery/extensions), auth + RBAC, htmx, and static file serving. Each example is a self-contained go run . target.

Documentation

• Architecture
• API specification
• MCP guide
• WebSocket guide
• Scaffolding guide

License

MIT — see LICENSE.