@lensmcp/protocol-types

The shared event protocol for LensMCP — Zod schemas and inferred TypeScript types for the events, trace nodes, edges, and resources that flow between producers and consumers.

LensMCP is an observability lens for coding agents. This package is the wire contract that keeps every part of the system in sync: a single set of Zod schemas (and the TypeScript types inferred from them) describing the events emitted by instrumentation, the trace graph (nodes + edges) those events build up, the per-domain attribute shapes, and the MCP resources consumers read.

Because the schemas and types are derived from the same definitions, producers (browser/React, Node/Nest taps, the gateway) and consumers (@lensmcp/core, the MCP server, the dashboard) share one source of truth — emit-side validation and read-side typing never drift apart.

Install

yarn add @lensmcp/protocol-types

Requires Node >=18. zod is a runtime dependency.

Usage

Validate an event on the producer side, and type it on the consumer side, from the same schema:

import {
  BaseEventSchema,
  type BaseEvent,
  type EventSource,
} from '@lensmcp/protocol-types';

// Producer: parse/validate before emitting (throws on bad shape).
const event = BaseEventSchema.parse({
  id: 'evt_01',
  sessionId: 'sess_abc',
  timestamp: Date.now(),
  source: 'react',
  category: 'render',
  severity: 'warning',
  context: { sessionId: 'sess_abc', route: '/dashboard' },
  fingerprint: 'render:Slow:/dashboard',
  title: 'Slow render',
});

// Consumer: the inferred type is the contract.
function handle(e: BaseEvent) {
  const from: EventSource = e.source;
  console.log(from, e.category, e.severity);
}

Use .safeParse() when you want to branch on validity instead of throwing:

const result = BaseEventSchema.safeParse(input);
if (!result.success) {
  // result.error is a ZodError
}

Every schema follows the XxxSchema (value) + Xxx (inferred type) naming convention, so you can import whichever you need.

What's in here

Event (event.ts)

• BaseEventSchema / BaseEvent — the common envelope on every emitted event: id, sessionId, timestamp, source, category, severity, context, fingerprint, title, plus optional message, location, relatedFiles, relatedUrls, and raw.
• EventSourceSchema / EventSource — where the event came from: nx, vite, typescript, eslint, rollup, client-runtime, chrome, react, valtio, nestjs, nextjs, db, redis, queue, memory, visual, perf, security, gateway, external.
• EventCategorySchema / EventCategory — what kind of signal it is: build, lint, typecheck, test, runtime, render, visual, trace, state, network, backend, db, memory, performance, security, deps, cluster.
• SeveritySchema / Severity — debug, info, warning, error, fatal.

Trace context (context.ts)

• TraceContextSchema / TraceContext — the correlation envelope carried on events and nodes: sessionId plus optional browser identifiers (browserContextId, tabId, frameId, route, url), flow identifiers (flowId, originType, originNodeId, causedByNodeId), request identifiers (requestId, traceparent), and hashed actor identifiers (userActionId, userIdHash, tenantIdHash).
• FlowOriginTypeSchema / FlowOriginType — what kicked off a flow (e.g. user-click, user-input, keyboard, route-load, effect, memo-recompute, timer, raf, idle-callback, websocket-message, broadcast-channel, post-message, storage-event, service-worker-message, media-query-change, visibility-change, resize, intersection-observer, mutation-observer, backend-response, hmr-update).

Trace graph — nodes & edges (node.ts, edge.ts)

• TraceNodeSchema / TraceNode — a node in the trace graph: identity (id, parentTraceNodeId, logicalId, instanceId, generation), type, lifecycle, context, timing (startTime, endTime, durationMs), optional location, and an open attributes record.
• TraceNodeTypeSchema / TraceNodeType — the node taxonomy spanning the browser process tree, React UI, user interaction, network/API, backend (Nest app/module/provider, requests, DB/Redis ops, queue jobs, loops, promises), state, visual, memory, and build/dev events.
• LifecycleSchema / Lifecycle — created, active, completed, disposed, errored.
• TraceEdgeSchema / TraceEdge — a directed relationship between nodes: from, to, axis, type, timestamp, optional attributes.
• EdgeAxisSchema / EdgeAxis — the relationship dimension: ownership, caused, async, data, render, state, network, backend, db, visual, performance, memory, lifecycle.

Domain attributes (attributes.ts)

Typed attributes payloads for specific node types, each with its XxxSchema + Xxx pair:

• Render — RenderAttrs, RenderPhase (mount | update), and the discriminated RenderWhy (props / react-state / context / valtio-path / parent-render / hook-dep-changed / force).
• Effects & state — EffectRunAttrs, ValtioUpdateAttrs.
• Backend — ServerRequestAttrs, plus LoopAttrs / LoopPattern (N+1, sequential-await, growing-allocation).
• Memory — MemoryOwnerAttrs, MemoryMutationAttrs, with MemoryContainerKind and MemoryMutationOperation enums.
• Visual — VisualFrameAttrs and VisualViolationAttrs, plus Rect, VisualFrameCause, VisualChangeKind, VisualRuleType, VisualRuleTiming, and VisualViolationSeverity.

Source location (source-location.ts)

• SourceLocationSchema / SourceLocation — file plus optional line, column, symbol, componentName, hookName. Reused across events, nodes, and resources to point back at code.

Resources (resources.ts)

The MCP-facing read models, all built on a shared envelope:

• ResourceEnvelopeSchema / ResourceEnvelope — the header on every resource JSON (schemaVersion, revision, optional $schema and updatedAt).
• URI_SCHEMES / UriScheme — the well-known LensMCP resource URI schemes (each maps 1:1 to a FrontMCP @App package): agent, events, build, lint, typecheck, test, runtime, render, visual, flow, story, trace, graph, bundle, security, perf, deps, memory, browser, react, valtio, nest, next, process.
• AgentCurrentStatusSchema / AgentCurrentStatus (agent://current-status) — rollup status (AgentStatusKind: starting | clean | warning | failing), blocking / warnings items (AgentBlockingItem), suggestedReads, and per-domain checks (AgentChecks).
• AgentSessionSchema / AgentSession (agent://session) — session capabilities: supported resources/tools/jobs/channels, default subscriptions, transports, host info, and project info.

DI tokens (tokens.ts)

Symbol-based dependency-injection tokens for FrontMCP @Provider registrations — SessionToken, EventBusToken, GraphStoreToken, ResourceStoreToken, StorageToken (union type LensmcpToken). The interfaces stay abstract here; packages like @lensmcp/core ship the concrete implementations.

Schema version (schema-version.ts)

• SCHEMA_VERSION (currently 1) and the SchemaVersion literal type — stamped into ResourceEnvelope so consumers can detect protocol drift.

How it fits

producers                         @lensmcp/protocol-types                    consumers
─────────                         ──────────────────────                    ─────────
browser / React tap        ─┐                                          ┌─►  @lensmcp/core
node / NestJS taps         ─┼──►  Zod schemas + inferred types   ──────┼─►  MCP server
gateway                    ─┘     (the wire contract)                  └─►  dashboard

Every @lensmcp instrumentation library and the gateway validate and emit events against these schemas; @lensmcp/core and the MCP server consume them with the matching inferred types. One definition, validated on the way out and typed on the way in — so the protocol can't silently drift between producer and consumer.

Part of LensMCP. Apache-2.0.