README
¶
HyperServe examples
The examples are grouped by the question they answer. Start with the focused programs; the composition references deliberately combine several concerns.
Start here
These programs run from the repository root with
go run ./examples/<name>:
| Order | Example | What it teaches |
|---|---|---|
| 1 | hello-world | One ordinary net/http handler and application-owned shutdown. |
| 2 | middleware-basics | Global middleware, prefix policy, ordering, and HyperServe's defaults. |
| 3 | binding | Focused typed JSON binding, validation, and manual escape hatches. |
| 4 | configuration | Deterministic defaults and left-to-right configuration precedence. |
| 5 | deferred-init | Health, readiness, and dependency initialization under one lifecycle. |
The JSON API is a larger CRUD application to read after the focused binding example.
Pages and browser applications
These examples use files relative to their own directories. Their READMEs show
the exact cd and go run . command.
| Example | What it shows |
|---|---|
| static-files | An os.Root-confined asset directory beside an API route. |
| htmx-dynamic | Server-rendered templates with HTMX partial updates. |
| htmx-stream | HTMX updates over Server-Sent Events. |
| web-worker-csp | The explicit CSP allowance required by blob-backed Web Workers. |
Authentication and long-lived connections
| Example | What it shows |
|---|---|
| auth | An OpenID Connect verifier adapted to HyperServe's issuer/subject principal. This is a separate Go module; run it from examples/auth. |
| websocket-demo | A server-tracked WebSocket upgrade, bounded echo loop, and embedded browser client. |
MCP
| Example | What it shows |
|---|---|
| mcp-basic | A small MCP server with explicitly enabled demonstration capabilities. |
| mcp-cli | Application-owned flags selecting HTTP or stdio transport. |
| mcp-stdio | MCP over stdio for a process-supervised host. |
| mcp-discovery | Discovery visibility policies. |
| mcp-extensions | Typed application tools, resources, and subscriptions. |
| devops | Opt-in MCP observability resources. |
| mcp-sse | Deprecated routed-SSE compatibility. |
Composition references
| Example | Purpose |
|---|---|
| best-practices | A broad composition reference covering auth, SSE, health, templates, and MCP. |
| complete | A kitchen-sink tour for browsing several APIs in one program. |
These are reference programs, not recommended learning sequences. Run each from its own directory because it uses local templates or static files.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main demonstrates several HyperServe features in one process.
|
Package main demonstrates several HyperServe features in one process. |
|
Example: request binding + validation, three ways.
|
Example: request binding + validation, three ways. |
|
Deferred-init example.
|
Deferred-init example. |
|
Example demonstrating DevOps features: debug logging and MCP resources
|
Example demonstrating DevOps features: debug logging and MCP resources |
|
Command enterprise demonstrates HyperServe's restricted TLS handshake policy.
|
Command enterprise demonstrates HyperServe's restricted TLS handshake policy. |
|
Smallest MCP-enabled HyperServe binary: built-in MCP tools/resources, a custom tool, a custom resource, and a sandboxed file-tool root.
|
Smallest MCP-enabled HyperServe binary: built-in MCP tools/resources, a custom tool, a custom resource, and a sandboxed file-tool root. |
|
Example: Using command-line flags to configure MCP
|
Example: Using command-line flags to configure MCP |
|
Example: typed MCP tools — one tool per verb.
|
Example: typed MCP tools — one tool per verb. |
|
Example: legacy HyperServe routed SSE.
|
Example: legacy HyperServe routed SSE. |
|
Package main demonstrates HyperServe's MCP support as a stdio server for Claude Desktop.
|
Package main demonstrates HyperServe's MCP support as a stdio server for Claude Desktop. |
Click to show internal directories.
Click to hide internal directories.