@alkdev/operations

Typed operations registry, call protocol, and adapters (MCP, OpenAPI).

Every API endpoint, agent action, and tool is an operation with a TypeBox schema, access control metadata, and a handler. The registry stores specs and handlers independently. The call protocol provides unified event-based invocation — call and subscribe use the same events, same PendingRequestMap. Adapters generate operations from OpenAPI specs, MCP servers, and filesystem manifests.

Install

npm install @alkdev/operations

Optional peer dependencies (only if you need them):

npm install @alkdev/typemap       # for Zod/Valibot schema adapters
npm install @modelcontextprotocol/sdk  # for MCP client integration

Quick Start

import { Type } from "@alkdev/typebox";
import { OperationRegistry, OperationType } from "@alkdev/operations";

const registry = new OperationRegistry();

registry.register({
  name: "create",
  namespace: "task",
  version: "1.0.0",
  type: OperationType.MUTATION,
  description: "Create a new task",
  inputSchema: Type.Object({
    title: Type.String(),
    priority: Type.Optional(Type.Union([Type.Literal("low"), Type.Literal("high")])),
  }),
  outputSchema: Type.Object({
    id: Type.String(),
    title: Type.String(),
  }),
  accessControl: { requiredScopes: ["task:write"] },
  handler: async (input) => {
    return { id: crypto.randomUUID(), title: input.title };
  },
});

const result = await registry.execute(
  "task.create",
  { title: "Ship it", priority: "high" },
  { identity: { id: "user-1", scopes: ["task:write"] } },
);

console.log(result.data);

Core Concepts

• OperationSpec — serializable descriptor: name, namespace, type, schemas, access control
• OperationHandler — the function that runs when the operation is called
• OperationRegistry — register specs and handlers, execute operations, validate I/O
• PendingRequestMap — event-based call protocol: call(), respond(), emitError(), abort()
• ResponseEnvelope — universal result wrapper with transport metadata (local, http, mcp)
• buildEnv() — generate a nested call surface for inter-operation composition

Entry Points

| Import | Purpose | |--------|---------| | @alkdev/operations | Core: registry, call protocol, envelopes, env, validation, errors, FromSchema | | @alkdev/operations/from-mcp | MCP client integration (requires @modelcontextprotocol/sdk) | | @alkdev/operations/from-openapi | OpenAPI integration | | @alkdev/operations/from-typemap | Zod/Valibot schema adapters (requires @alkdev/typemap) |

Guides

| Guide | Topic | |-------|-------| | Registry | Defining, registering, and executing operations | | Call Protocol | PendingRequestMap, CallHandler, call/subscribe events | | Subscriptions | Real-time streaming with async generators | | Response Envelopes | Universal result wrapper and transport metadata | | Access Control | Scope and resource-based authorization | | Composition | Inter-operation calls with buildEnv | | Error Handling | CallError, infrastructure codes, mapError | | Adapters | MCP, OpenAPI, FromSchema, scanner, typemap | | Validation | Schema validation helpers |

API Reference

For detailed type signatures, see docs/architecture/api-surface.md.

License

MIT OR Apache-2.0