reshapr: Instructions file for Codex

AGENTS.md

Project Overview

reShapr is the open source runtime that turns existing REST/GraphQL/gRPC APIs AI-Native, without rebuilding them, by transforming them into governed, LLM-friendly MCP (Model Context Protocol) tools. It solves "Context Overload" by filtering and slimming API payloads before they reach LLMs.

Architecture

Three core runtime services communicate via gRPC, plus a web UI and a CLI:

                             ┌─────────────────────────────────────┐
                             │         reShapr Platform            │
                             │                                     │
  ┌──────────┐  MCP/HTTP     │  ┌──────────────────────────────┐   │
  │  AI Agent│──────────────>│  │      Gateway (proxy)         │   │──> REST / GraphQL / gRPC
  │  or LLM  │               │  │      :7777                   │   │    Backend APIs
  └──────────┘               │  └──────────┬───────────────────┘   │
                             │             │ gRPC (EDS + GHS)      │
  ┌──────────┐  REST API     │  ┌──────────▼───────────────────┐   │
  │  CLI /   │──────────────>│  │    Control Plane (ctrl)      │───┼──> PostgreSQL
  │  Web UI  │               │  │    :5555                     │   │
  └──────────┘               │  └──────────────────────────────┘   │
                             └─────────────────────────────────────┘

Each component in more detail:

• Control Plane (control-plane/) — Quarkus service on port 5555. Manages services, expositions, organizations, users, gateways. Uses PostgreSQL + Flyway migrations + Hibernate ORM Panache with multi-tenant DISCRIMINATOR strategy. Hazelcast for caching.
• Proxy/Gateway (proxy/) — Quarkus service on port 7777. Receives MCP requests, discovers expositions via gRPC from the control plane (eds-v1.proto, ghs-v1.proto), proxies calls to backend APIs. Supports REST, GraphQL, gRPC backends.
  • Clustering: multiple gateway instances form an Infinispan cluster via JGroups DNS_PING, replicating session, elicitation, and secret-resolution state so any gateway can handle any request. Controlled by the reshapr.infinispan.stack JVM property (reshapr-local for a single node, reshapr-k8s for a clustered setup).
  • Caching: doesn't round-trip to the control plane on every request. A GatewayRegistry holds raw exposition metadata and artifact content, populated at startup and refreshed on every change event. A WorkCache (Caffeine LRU) holds the parsed form of those artifacts, for example a parsed OpenAPI document, so re-parsing is avoided across calls.
• CLI (cli/) — TypeScript/Node.js CLI (@reshapr/reshapr-cli) built with Commander.js. Manages login, import, service lifecycle, and local Docker-based platform via reshapr run.
• Web UI (web-ui/) — SvelteKit 5 app (@reshapr/reshapr-web-ui, Svelte 5 runes + TailwindCSS 4 + bits-ui) deployed with adapter-node (SSR). Standalone, not a Maven module. Talks to the control-plane admin API server-side via RESHAPR_ADMIN_API_KEY (see web-ui/src/lib/server/proxy.ts, auth.ts). Runs on 5173 in dev (Vite), 3333 in the container.