# Gortexa

Source: https://gortexa.sheng.page/en/

## Features

### Three protocols, one port
h2c multiplexing on Go's native `http.Server.Protocols`. One port accepts gRPC, HTTP/JSON and MCP.

### Fixed-order interceptor chain
recover → request-id → logger → load-shed → rate-limit → circuit-breaker → auth → validation. Eight stages in a fixed order; a missing stage fails startup.

### One error model
A single mapping table produces the gRPC status, HTTP status and MCP error envelope. Internal causes never leak.

### AI tool calls go through the same chain
MCP `tools/call` dispatches over an in-process loopback, so AI calls pass auth and validation like any other request.

### Batteries included
Layered config, three-state health, slog + OTLP, pgx + sqlc, cache (in-memory by default), NATS/JetStream.

### Importable as a module
`go get` the framework packages directly — kernel/interceptor/mq for plain services, plus the mcp bridge and gortexa.ai.v1 annotations for AI ones. No scaffold required. See [Components](https://gortexa.sheng.page/en/components/).

## Get started

To have a coding agent build a runnable service scaffold from a prompt, use [Quickstart with AI](https://gortexa.sheng.page/en/ai-quickstart/). It pins the release, verifies the toolchain, confirms the scaffold left the startup-refusing placeholder secret in place, and runs HTTP/MCP smoke checks in one shell. For a manual walkthrough, use [Quickstart](https://gortexa.sheng.page/en/quickstart/).

Both paths create a prototype only; see [Deployment](https://gortexa.sheng.page/en/deployment/) for the work required before production.

Or consume the framework as a Go module — `go get` it and import the packages directly, no scaffold required:

```bash
go get github.com/yshengliao/gortexa@latest
```

See [Components](https://gortexa.sheng.page/en/components/) for each package's usage, or [Use as a module](https://gortexa.sheng.page/en/quickstart/#use-as-a-module-no-scaffold) for a minimal app.

After either flow starts the server on :8080, hit each protocol once:

```bash
curl localhost:8080/healthz                                # 200: health check is open
curl -XPOST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'      # MCP: list AI tools defined in proto
curl localhost:8080/v1/resources/x                         # 401: auth is shared across all three
```

## FAQ

### What is Gortexa?

A contract-first, batteries-included gRPC framework for Go: Protobuf is the single source of truth, and one h2c port serves gRPC, HTTP/JSON (grpc-gateway) and MCP, all sharing one interceptor chain, one error model and one auth path.

### Which Go version does it need?

It targets Go 1.27. Any installed Go 1.21+ works as the bootstrap: `GOTOOLCHAIN` auto-downloads go1.27.0.

### How do three protocols share one port?

Go's native `http.Server.Protocols` does the h2c multiplexing; the HTTP gateway and the MCP bridge dial the gRPC server over an in-process loopback, so auth, rate limiting, validation and error mapping are identical across all three.

### Do I need Redis or Kafka?

No. The cache defaults to process-local in-memory (redis is opt-in); messaging uses NATS (core, at-most-once) or JetStream (durable, at-least-once) — there is no Kafka dependency.

### How do AI agents call my API?

Annotate the proto with `gortexa.ai.v1` annotations and the MCP bridge exposes those RPCs as MCP tools; an AI's `tools/call` passes the same auth and validation as any human request. See the [MCP transport](https://gortexa.sheng.page/en/transports/mcp/).

### How does Gortexa differ from connect-go?

Both multiplex protocols on one port, but different ones: connect-go serves Connect, gRPC and gRPC-Web, while Gortexa serves gRPC, HTTP/JSON (grpc-gateway) and MCP. The differentiating axis is AI — Gortexa exposes annotated RPCs as MCP tools through the same interceptor chain. See the full [comparison](https://gortexa.sheng.page/en/comparison/).

### Can I use individual components without the scaffold?

Yes. `go get github.com/yshengliao/gortexa` and import the public packages — `kernel`, `interceptor`, `mq`, `mcp` and the rest — individually. See [Components](https://gortexa.sheng.page/en/components/).