Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
100 lines (69 loc) · 3.59 KB

ARCHITECTURE.md

File metadata and controls

100 lines (69 loc) · 3.59 KB
Raw

Keryx Architecture

Purpose

Keryx is a small, self-hosted gateway that exposes the same tool definitions through three interfaces:

  1. Model Context Protocol (MCP) over stateless Streamable HTTP.
  2. OpenAPI 3.1 and generated REST routes.
  3. Apple Siri Shortcuts generated by the legacy module.

The design goal is one source of truth for tool metadata, input validation, authentication mode, and handler behavior.

Runtime flow

Client
  │
  ├── POST /mcp
  ├── POST /api/tools/<tool>
  └── GET  /openapi.json
          │
          ▼
   Express transport layer
   - request ID
   - security headers
   - CORS and MCP Origin validation
   - rate limiting and JSON limits
   - per-tool authentication
          │
          ▼
      ToolRegistry
   name, description, module,
   auth mode, Zod input, handler
          │
          ▼
   Domain/tool implementation
          │
          ├── local result
          ├── bounded HTTPS upstream request
          └── temporary one-time Shortcut artifact

Main components

src/config/env.ts

Validates all process configuration at startup. Production uses fail-closed rules: HTTPS public URL, strong gateway token, explicit CORS configuration, and HTTPS upstream URLs.

src/core/registry.ts

Defines ToolDefinition, ToolContext, and ToolRegistry. A registry is created per Express app instance, which makes application construction deterministic and test-safe.

src/core/auth.ts

Parses bearer credentials, performs timing-safe gateway-token comparison, and applies the selected auth model:

  • gateway: Keryx validates KERYX_API_TOKEN.
  • forward: Keryx requires a caller bearer and forwards it to the fixed upstream service, which remains the authorization authority.

src/core/openapi.ts

Generates the OpenAPI document from the registry. REST routes and MCP tools use the same Zod schemas, so protocol descriptions cannot silently drift from runtime validation.

src/modules/nextgen/mcp.ts

Builds a stateless MCP server for each request. The Express layer validates the request Origin before the MCP SDK receives the request.

src/modules/nextgen/tools.ts

Contains the built-in next-generation tools. Upstream responses are timeout-bounded, redirect-disabled, content-type checked, and size-limited before JSON parsing.

src/modules/legacy/*

Compiles Apple Shortcuts and stores generated binary files only in memory. Capability URLs are random, short-lived, and single-use.

Adding a tool

A tool should:

  1. Use a stable snake_case name.
  2. Validate every caller-controlled field with Zod.
  3. Choose gateway or forward auth explicitly.
  4. Avoid accepting arbitrary upstream URLs; prefer operator-configured endpoints.
  5. Apply time, response-size, and redirect limits to network calls.
  6. Return JSON-serializable data.
  7. Add tests and update the README/OpenAPI examples.

See docs/ADDING_TOOLS.md.

State and scaling

MCP and REST execution are stateless. The only in-process state is the temporary Shortcut store. Consequently:

  • ordinary tool traffic can be load-balanced without sticky sessions;
  • a generated Shortcut must be downloaded from the same instance unless a shared artifact store is introduced;
  • horizontal scaling should either disable the legacy artifact flow or replace the store through a future storage interface.

Architectural boundaries

Keryx is not an identity provider, policy engine, secret vault, generic forward proxy, or long-term artifact store. Those responsibilities remain with the upstream application and deployment platform.