Emkoord

Registry-based JSON-RPC server that automatically exposes your emkore use cases as type-safe APIs.

Key Features

• Zero Configuration - Automatically exposes use cases from your registry
• Auto-Discovery - Methods appear automatically from your registry
• Self-Documenting - Built-in OpenRPC 1.3.0 API documentation
• Real-time Ready - Optional WebSocket support for live updates
• AI-Friendly - Optional MCP protocol for LLM tool integration
• Security Features - Available rate limiting, audit logging, and security headers middleware
• TLS / HTTP/2 - Optional HTTPS with automatic HTTP/2 negotiation via ALPN
• Type-Safe - Full TypeScript support from entity to response

Installation

bun add @emkodev/emkoord

Quick Start

import { createServer } from "@emkodev/emkoord";
import { registry } from "./your-use-cases";

// Create and start the server
createServer({ registry, port: 8000 }).start();

Your server now automatically exposes:

• All your use cases as JSON-RPC methods
• OpenRPC documentation at /rpc (via rpc.discover)
• Health checks at /health
• WebSocket support at /ws (if enabled)
• Static file serving from / (if enabled)

Detailed Usage

import { createServer } from "@emkodev/emkoord";
import type { UseCaseRegistryEntry } from "@emkore";

// Your use case registry
const registry: UseCaseRegistryEntry[] = [
  // ... your use cases
];

const server = createServer({
  port: 8000,
  cors: {
    origin: ["http://localhost:3000"],
    credentials: true,
  },
  registry,
});

server.start();

Service Discovery

The server automatically provides service discovery endpoints for API introspection:

rpc.discover

OpenRPC community standard for JSON-RPC 2.0 service discovery:

curl -X POST http://localhost:8000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "rpc.discover",
    "id": 1
  }'

system.describe

Legacy JSON-RPC 1.1 introspection standard (alias to rpc.discover):

curl -X POST http://localhost:8000/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "system.describe",
    "id": 1
  }'

Both methods return an OpenRPC 1.3.0 document describing all available methods:

{
  "jsonrpc": "2.0",
  "result": {
    "openrpc": "1.3.0",
    "info": {
      "title": "@emkodev/emkoord",
      "version": "1.0.0-beta.22",
      "description": "JSON-RPC server adapter for emkore use cases"
    },
    "methods": [
      {
        "name": "createProduct",
        "description": "Create a new product",
        "params": ["..."],
        "result": {}
      }
    ]
  },
  "id": 1
}

The OpenRPC document is automatically generated from your use case registry's apiDefinition fields.

How It Works

1. Define your business logic using emkore use cases
2. Create a registry of your use cases
3. Start the server with your registry
4. APIs are exposed with OpenRPC documentation

The server automatically:

• Converts snake_case use cases to camelCase RPC methods
• Generates OpenRPC documentation from your type definitions
• Handles all JSON-RPC 2.0 protocol requirements
• Manages errors, batching, and notifications
• Provides CORS, authentication, and security features

Advanced Features

WebSocket Support (Optional)

Enable real-time updates for your applications:

const server = createServer({
  registry,
  websocket: { enabled: true }, // Enable WebSocket support
});

// Broadcast from your use cases:
import { broadcast } from "@emkodev/emkoord";

broadcast("order:123", { type: "order.updated", data: order }, tenantId);

WebSocket Features:

• Topic-based subscriptions with wildcards (order:*)
• Automatic tenant isolation for multi-tenant security
• Zero overhead when disabled (default)
• Native implementation with no external dependencies

Tenant Isolation: All WebSocket communications are automatically scoped to the authenticated user's tenant for complete data isolation.

Full WebSocket Documentation

MCP Support (Optional)

Enable Model Context Protocol for AI tool integration:

const server = createServer({
  registry,
  mcp: { enabled: true }, // Enable Model Context Protocol
});

MCP Features:

• Automatic tool generation from your use cases
• Claude Code and future spec support (2024-11-05 & 2025-11-25)
• Built-in prompt templates for common operations
• Full capability negotiation and security

Full MCP Documentation

HTTP API (Optional)

Expose use cases as plain HTTP endpoints alongside JSON-RPC:

const server = createServer({
  registry,
  httpApi: { enabled: true },
});

Convention: POST /api/{resource}/{action} with JSON body as use case input.

Emroute SSR Integration (Optional)

Serve SSR pages alongside your JSON-RPC API using @emkodev/emroute:

const server = createServer({
  registry,
  emroute: { enabled: true },
});

Emroute Features:

• File-based routing with .page.md, .page.html, .page.ts files
• SSR HTML at /html/* and SSR Markdown at /md/*
• SPA fallback with configurable modes (leaf, root, none, only)
• Widgets call interactors in-process via context.rpc — zero HTTP overhead
• Auto-discovery of routes and widgets from conventional directories

Full Emroute Integration Guide

TLS / HTTP/2 (Optional)

Enable HTTPS with automatic HTTP/2 negotiation:

import { readFileSync } from "node:fs";

const cert = readFileSync("./certs/cert.pem", "utf-8");
const key = readFileSync("./certs/key.pem", "utf-8");

const server = createServer({
  registry,
  tls: { cert, key }, // HTTP/2 negotiated automatically via ALPN
});

When TLS is configured, Bun.serve() automatically negotiates HTTP/2 with clients that support it. No additional dependencies or configuration needed. Without TLS, the server runs plain HTTP/1.1.

Static File Serving (Optional)

Serve static assets alongside your JSON-RPC API:

const server = createServer({
  registry,
  staticFiles: {
    enabled: true,
    serveDirOptions: {
      fsRoot: "assets",
      quiet: true,
      showDirListing: false,
    },
  },
});

Static files are served as fallback after all API routes. CORS headers are automatically applied.

Note: For full SSR capabilities with pages and widgets, use the Emroute SSR Integration option instead of static file serving.

Security Features

The server includes security middleware that can be integrated:

• Rate Limiting - Configurable per-client and per-method limits
• Request Validation - Size limits and input sanitization
• Audit Logging - Complete request/response logging
• Security Headers - CSP, HSTS, X-Frame-Options, etc.
• CORS Configuration - Fine-grained origin control
• MCP Security - Output sanitization and confused deputy protection

Security Documentation

Architecture

The server follows these principles:

• Thin adapter layer - Minimal code between JSON-RPC and emkore use cases
• Registry-driven - All methods auto-discovered from use case registry
• Zero-configuration - Works out of the box with sensible defaults
• Opt-in features - WebSocket, MCP, HTTP API, emroute have zero overhead when disabled
• Type-safe - Full TypeScript support from entity to response

Development

# Run in development mode
bun run dev

# Type check
bun run check

# Run tests
bun test

Dependencies

• @emkodev/emkore: Core emkore framework with use case interfaces
• @emkodev/json-rpc: JSON-RPC 2.0 implementation
• @emkodev/emroute (optional peer): SSR integration

License

MIT License - see LICENSE file for details.

Project Status

Version 1.0.0-beta.22

Current features:

• Full JSON-RPC 2.0 compliance
• HTTP API adapter
• TLS / HTTP/2 support
• WebSocket support for real-time updates
• MCP protocol for AI tool integration
• Emroute SSR integration (HTML + Markdown + SPA)
• Multi-tenant architecture with tenant isolation

Built by emko.dev