Skip to Content
Comms PackagesOverview

Comms Packages

The comms platform is built from a set of focused TypeScript packages under the @loop/* namespace. Each package has a single responsibility and well-defined API surface.

Package Index

PackagePurposeREADME
@loop/identityCross-database identity resolverView 
@loop/contractsTyped, versioned event schemasView 
@loop/observabilityStructured logging and OTel tracingView 
@loop/flagsPer-brand kill switches and feature gatesView 
@loop/mcp-commsMCP server for comms toolsView 
@loop/ops-commsOperational schemas and migrationsView 

@loop/identity

Cross-database identity resolver that unifies person records across Supabase, Clerk, BigCommerce, and other data stores. Given any known identifier (email, Clerk user ID, BigCommerce customer ID, Supabase person ID), it resolves the canonical person record.

Key capabilities:

  • Resolve person by any known identifier
  • Merge duplicate records
  • Track identifier provenance
  • Support for soft-deletes and GDPR erasure

@loop/contracts

Typed, versioned event schemas used across the comms platform. This is the source of truth for all event payloads.

Key exports:

  • Zod schemas for each event type (e.g., LeadCapturedV1Schema)
  • TypeScript types inferred from schemas
  • validateEvent(name, payload) — runtime validation helper
  • Event name constants

See Event Catalog for the full list of events.

@loop/observability

Structured logging and OpenTelemetry tracing for all comms platform services.

Key features:

  • Structured JSON logging with correlation IDs
  • OpenTelemetry trace propagation
  • Axiom integration for log shipping and trace storage
  • Request/response logging middleware for Hono

@loop/flags

Per-brand kill switches and feature gates backed by a simple key-value store.

Key capabilities:

  • Boolean flags with brand-level scoping
  • Global flags (apply to all brands)
  • Flag evaluation with default values
  • Audit trail for flag changes
  • Integration with the flags.set MCP tool

@loop/mcp-comms

The MCP server that exposes 59 tools for managing the comms platform. This is the primary interface for AI agents.

Key features:

  • 59 tools across 14 categories
  • RBAC enforcement on every tool call
  • stdio and HTTP/SSE transport support
  • Clerk OAuth authentication
  • draftByDefault safety pattern

See MCP Tool Catalog for the full tool reference.

@loop/ops-comms

Operational schemas and database migrations for the comms platform. Manages the comms PostgreSQL schema.

Key capabilities:

  • Drizzle ORM schema definitions for all comms tables
  • Migration management (generate, apply, rollback)
  • Seed data for development environments
  • Schema validation utilities
@loop/notificationsOverview