Skip to content
Back to search

keryx

Keryx: The Fullstack TypeScript Framework for MCP and APIs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/actionhero--keryx/badge.svg)](/listings/actionhero--keryx)

HTML

<a href="/listings/actionhero--keryx"><img src="/api/listings/actionhero--keryx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Create a new project:

bunx keryx new my-app
cd my-app
cp .env.example .env
bun install
bun dev

Requires Bun, PostgreSQL, and Redis. See the [Getting Started guide](https://keryxjs.com/guide/) for full setup instructions (including running without Postgres or Redis for quick prototypes).

Developing the framework itself

If you're contributing to Keryx, clone the monorepo instead:

git clone https://github.com/actionhero/keryx.git
cd keryx
bun install
cp example/backend/.env.example example/backend/.env
cp example/frontend/.env.example example/frontend/.env
bun dev

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 276 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Keryx
  2. <p align="center"><strong>The fullstack TypeScript framework for MCP and APIs.</strong></p>
  3. <p align="center">
  4. <img src="https://raw.githubusercontent.com/actionhero/keryx/main/docs/public/images/horn.svg" alt="Keryx" width="200" />
  5. </p>
  6. [![Test](https://github.com/actionhero/keryx/actions/workflows/test.yaml/badge.svg)](https://github.com/actionhero/keryx/actions/workflows/test.yaml)
  7. ## What is this Project?
  8. The big idea behind Keryx: **write your controller once, and it works everywhere.** A single action class handles HTTP requests, WebSocket messages, CLI commands, background tasks, and MCP tool calls — same inputs, same Zod validation, same middleware, same response. You write the logic once; the only thing that changes is how the request arrived and how the response gets delivered.
  9. That last transport — MCP — is the reason I built this now. Every action is automatically an MCP tool, so AI agents authenticate with built-in OAuth 2.1, get typed errors, and call the exact same validated endpoints your HTTP clients do. There's no second MCP server to maintain and no schemas to keep in sync… you expose your app to agents by writing the app.
  10. And it's a real backend, not a toy. You get Drizzle ORM with auto-migrations, background tasks with fan-out on Resque, streaming responses (SSE, chunked binary, and the same stream over WebSocket and MCP), OpenAPI generation, pagination and caching helpers, database transactions, and a companion Vite + React frontend that reads your actions with end-to-end type safety — no code generation. It's all on [Bun](https://bun.sh), so TypeScript runs natively and startup is fast.
  11. ### One Action, Every Transport
  12. Here's what that looks like in practice. This is one action:
  13. ```ts
  14. export class UserCreate implements Action {
  15. name = "user:create";
  16. description = "Create a new user";
  17. inputs = z.object({
  18. name: z.string().min(3),
  19. email: z.string().email(),
  20. password: secret(z.string().min(8)),
  21. });
  22. web = { route: "/user", method: HTTP_METHOD.PUT };
  23. task = { queue: "default" };
  24. async run(params: ActionParams<UserCreate>) {
  25. const user = await createUser(params);
  26. return { user: serializeUser(user) };
  27. }
  28. }
  29. ```
  30. That one class gives you:
  31. **HTTP** — `PUT /api/user` with JSON body, query params, or form data:
  32. ```bash
  33. curl -X PUT http://localhost:8080/api/user \
  34. -H "Content-Type: application/json" \
  35. -d '{"name":"Evan","email":"evan@example.com","password":"secret123"}'
  36. ```
  37. **WebSocket** — send a JSON message over an open connection:
  38. ```json
  39. { "messageType": "action", "action": "user:create",
  40. "params": { "name": "Evan", "email": "evan@example.com", "password": "secret123" } }
  41. ```
  42. **CLI** — flags are generated from the Zod schema automatically:
  43. ```bash
  44. ./keryx.ts "user:create" --name Evan --email evan@example.com --password secret123 -q | jq
  45. ```
  46. **Background Task** — enqueued to a Resque worker via Redis:
  47. ```ts
  48. await api.actions.enqueue("user:create", { name: "Evan", email: "evan@example.com", password: "secret123" });
  49. ```
  50. **MCP** — exposed as a tool for AI agents automatically:
  51. ```json
  52. {
  53. "mcpServers": {
  54. "my-app": {
  55. "url": "http://localhost:8080/mcp"
  56. }
  57. }
  58. }
  59. ```
  60. Same validation, same middleware chain, same `run()` method, same response shape. The only thing that changes is how the request arrives and how the response is delivered.
  61. That's it. The agent can now discover all your actions as tools, authenticate via OAuth, and call them with full type validation.
  62. ### Key Components
  63. - **MCP-native** — every action is an MCP tool with OAuth 2.1 auth, typed errors, and per-session isolation
  64. - **Transport-agnostic Actions** — HTTP, WebSocket, CLI, background tasks, and MCP from one class
  65. - **Zod input validation** — type-safe params with automatic error responses and OpenAPI generation
  66. - **Built-in background tasks** via [node-resque](https://github.com/actionhero/node-resque), with a [fan-out pattern](#fan-out-tasks) for parallel job processing
  67. - **Strongly-typed frontend integration** — `ActionResponse<MyAction>` gives the frontend type-safe API responses, no code generation needed
  68. - **Drizzle ORM** with auto-migrations (replacing the old `ah-sequelize-plugin`)
  69. - **Companion Vite + React frontend** as a separate application (replacing `ah-next-plugin`)
  70. - **Streaming responses** — SSE and chunked binary streaming via `StreamingResponse`, with per-transport behavior (HTTP, WebSocket, MCP)
  71. - **Pagination helpers** — `paginationInputs()` Zod mixin + `paginate()` utility for standardized paginated responses
  72. - **Database transactions** — `withTransaction()` and `TransactionMiddleware` for automatic commit/rollback across action execution
  73. - **Redis caching patterns** — cache-aside and response-level cache middleware using the built-in ioredis connection
  74. ### Why Bun?
  75. TypeScript is still the best language for web APIs. But Node.js has stalled — Bun is moving faster and includes everything we need out of the box:
  76. - Native TypeScript — no compilation step
  77. - Built-in test runner
  78. - Module resolution that just works
  79. - Fast startup and an excellent packager
  80. - `fetch` included natively — great for testing
  81. ## Project Structure
  82. - **root** — a slim `package.json` wrapping the workspaces. `bun install` and `bun dev` work here, but you need to `cd` into each workspace for tests.
  83. - **packages/keryx** — the framework package (publishable)
  84. - **example/backend** — the example backend application
  85. - **example/frontend** — the example Vite + React frontend
  86. - **docs** — the [documentation site](https://keryxjs.com)
  87. ## Quick Start
  88. Create a new project:
  89. ```bash
  90. bunx keryx new my-app
  91. cd my-app
  92. cp .env.example .env
  93. bun install
  94. bun dev
  95. ```
  96. Requires Bun, PostgreSQL, and Redis. See the [Getting Started guide](https://keryxjs.com/guide/) for full setup instructions (including running without Postgres or Redis for quick prototypes).
  97. ### Developing the framework itself
  98. If you're contributing to Keryx, clone the monorepo instead:
  99. ```bash
  100. git clone https://github.com/actionhero/keryx.git
  101. cd keryx
  102. bun install
  103. cp example/backend/.env.example example/backend/.env
  104. cp example/frontend/.env.example example/frontend/.env
  105. bun dev
  106. ```
  107. ## Production Builds
  108. ```bash
  109. bun compile
  110. # set NODE_ENV=production in .env
  111. bun start
  112. ```
  113. ## Databases and Migrations
  114. We use [Drizzle](https://orm.drizzle.team) as the ORM. Migrations are derived from schemas — edit your schema files in `schema/*.ts`, then generate and apply:
  115. ```bash
  116. cd example/backend && bun run migrations
  117. # restart the server — pending migrations auto-apply
  118. ```
  119. ## Actions, CLI Commands, and Tasks
  120. Unlike the original ActionHero, we've removed the distinction between actions, CLI commands, and tasks. They're all the same thing now. You can run any action from the CLI, schedule any action as a background task, call any action via HTTP or WebSocket, and expose any action as an MCP tool for AI agents. Same input validation, same responses, same middleware.
  121. ### Web Actions
  122. Add a `web` property to expose an action as an HTTP endpoint. Routes support `:param` path parameters and RegExp patterns — the route lives on the action itself, no separate `routes.ts` file:
  123. ```ts
  124. web = { route: "/user/:id", method: HTTP_METHOD.GET };
  125. ```
  126. ### WebSocket Actions
  127. Enabled by default. Clients send JSON messages with `{ messageType: "action", action: "user:create", params: { ... } }`. The server validates params through the same Zod schema and sends the response back over the socket. WebSocket connections also support channel subscriptions for real-time PubSub.
  128. ### CLI Actions
  129. Enabled by default. Every action is registered as a CLI command via [Commander](https://github.com/tj/commander.js). The Zod schema generates `--flags` and `--help` text automatically:
  130. ```bash
  131. ./keryx.ts "user:create" --name evan --email "evantahler@gmail.com" --password password -q | jq
  132. ```
  133. The `-q` flag suppresses logs so you get clean JSON. Use `--help` on any action to see its params.
  134. ### Task Actions
  135. Add a `task` property to schedule an action as a background job. A `queue` is required, and `frequency` is optional for recurring execution:
  136. ```ts
  137. task = { queue: "default", frequency: 1000 * 60 * 60 }; // every hour
  138. ```
  139. ### MCP Actions
  140. When the MCP server is enabled (`MCP_SERVER_ENABLED=true`), every action is automatically registered as an [MCP](https://modelcontextprotocol.io) tool. AI agents and LLM clients (Claude Desktop, VS Code, etc.) can discover and call your actions through the standard Model Context Protocol. Actions can also be exposed as MCP **resources** (URI-addressed data) and **prompts** (named templates) via `mcp.resource` and `mcp.prompt`.
  141. Action names are converted to valid MCP tool names by replacing `:` with `-` (e.g., `user:create` becomes `user-create`). The action's Zod schema is converted to JSON Schema for tool and prompt parameter definitions.
  142. To exclude an action from MCP tools:
  143. ```ts
  144. mcp = { tool: false };
  145. ```
  146. To expose an action as an MCP resource or prompt:
  147. ```ts
  148. // Resource — clients fetch this by URI
  149. mcp = { tool: false, resource: { uri: "myapp://status", mimeType: "application/json" } };
  150. // Prompt — clients invoke this as a named template
  151. mcp = { tool: false, prompt: { title: "Greeting" } };
  152. ```
  153. OAuth 2.1 with PKCE is used for authentication — MCP clients go through a browser-based login flow, and subsequent tool calls carry a Bearer token tied to the authenticated user's session.
  154. ### Fan-Out Tasks
  155. A parent task can distribute work across many child jobs using `api.actions.fanOut()` for parallel processing. Results are collected automatically in Redis. See the [Tasks guide](https://keryxjs.com/guide/tasks) for full API and examples.
  156. ### Streaming Responses
  157. Actions can stream data by returning a `StreamingResponse`. The framework handles SSE, chunked binary, and cross-transport behavior automatically:
  158. ```ts
  159. async run(params: { prompt: string }) {
  160. const sse = StreamingResponse.sse();
  161. (async () => {
  162. try {
  163. for await (const token of callLLM(params.prompt)) {
  164. sse.send(token, { event: "token" });
  165. }
  166. sse.close();
  167. } catch (e) {
  168. sse.sendError(String(e));
  169. }
  170. })();
  171. return sse;
  172. }
  173. ```
  174. Over HTTP this is native SSE; over WebSocket each chunk becomes an incremental message; over MCP chunks are forwarded as logging messages. See the [Streaming guide](https://keryxjs.com/guide/streaming) for full details.
  175. ## A Note on ActionHero
  176. If you've used [ActionHero](https://www.actionherojs.com), Keryx will feel familiar — it's the spiritual successor. I built ActionHero years ago to take the best ideas from Rails and Node.js and shove them together, and I still believe in those ideas… but the framework needed a fresh start on Bun, Zod, and Drizzle, with first-class MCP support instead of something bolted on later. Keryx is that restart.
  177. If you're coming from ActionHero, the biggest changes are: unified controllers (actions = tasks = CLI commands = MCP tools), separate frontend and backend applications, Drizzle ORM in place of Sequelize, and MCP as a first-class transport. See the full [migration guide](https://keryxjs.com/guide/from-actionhero) for details.
  178. ## Production Deployment
  179. Each application has its own `Dockerfile`, and a `docker-compose.yml` runs them together. You probably won't use this exact setup in production, but it shows how the pieces fit together.
  180. **Run `keryx build` at image build time.** It pre-generates the OpenAPI response schemas into `.cache/swagger-schemas.json` so the server doesn't have to derive them from your action return types on every boot:
  181. ```dockerfile
  182. COPY . .
  183. RUN cd backend && bun keryx.ts build
  184. CMD ["bun", "keryx.ts", "start"]
  185. ```
  186. See the [deployment guide](https://keryxjs.com/guide/deployment#build-step) for details.
  187. ## Documentation
  188. Full docs at [keryxjs.com](https://keryxjs.com), including:
  189. - [Getting Started](https://keryxjs.com/guide/)
  190. - [Actions Guide](https://keryxjs.com/guide/actions)
  191. - [Streaming](https://keryxjs.com/guide/streaming)
  192. - [Caching](https://keryxjs.com/guide/caching)
  193. - [API Reference](https://keryxjs.com/reference/actions)
  194. <p align="center">
  195. <img src="https://raw.githubusercontent.com/actionhero/keryx/main/docs/public/images/lion-standing.svg" alt="Keryx lion" width="120" />
  196. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.