event-intelligence

# MCP Event Intelligence

> Durable temporal event intelligence for sleeping agents.

[![CI](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mcp-event-intelligence.svg)](https://www.npmjs.com/package/mcp-event-intelligence)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.3.1-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

MCP Event Intelligence is an experimental event runtime for agents that need to react to **future conditions over multiple event sources** without keeping an LLM or agent loop alive.

The primary integration model is **embedded and host-owned**: the agent host keeps its existing MCP clients, transports, OAuth sessions and provider credentials. Event Intelligence receives a reference to the host's MCP registry, discovers the already-connected clients automatically, and uses only the Events-capable ones.

<p align="center">
  <img src="docs/assets/hero-architecture.svg" alt="MCP Event Intelligence architecture: event sources flow into durable composite and temporal reasoning, derived versioned events, and runtime wakeups." width="100%" />
</p>

An agent can express an intent such as:

> When this PR is merged, the production deploy succeeds, and no error is observed for 10 minutes, wake this task and review the release.

Event Intelligence persists that continuation independently of the model, waits for the world to satisfy it, and wakes the host only when necessary.

## Embed it in an existing agent host

Install from npm:

```bash
npm install mcp-event-intelligence
```

Published package: [npm](https://www.npmjs.com/package/mcp-event-intelligence) · [Official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)

Pass the harness-level MCP registry once — not every MCP one by one:

```js
import {
  createEventIntelligenceHost,
  createMcpRegistryAdapter,
} from 'mcp-event-intelligence/host';

const ei = await createEventIntelligenceHost({
  dataDir: './data',
  mcpRegistry: createMcpRegistryAdapter({
    listConnections: () => host.mcp.listConnections(),
    subscribe: (refresh) => host.mcp.onConnectionsChanged(refresh),
  }),
  wake: async (packet, activation) => {
    const receipt = await host.resume(packet.target, {
      packet,
      activation,
    });
    return { runtimeReceiptId: receipt.id };
  },
});
```

Event Intelligence enumerates the host registry automatically. GitHub, Gmail, private/company MCPs and future connections do not need to be configured again inside EI. Tools-only MCPs remain available to the agent and are ignored by the Events layer; Events-capable MCPs are attached automatically.

### Agent-first trigger flow

Agents no longer need to construct the low-level trigger DSL directly for common cases. Ask EI to compile an agent-friendly plan against the event sources that are actually available:

```js
const plan = await ei.planTrigger({
  events: [{
    id: 'invoice',
    event: 'erpnext.sales_invoice.submitted',
    where: [
      { path: 'grand_total', op: 'gt', value: 10000 },
    ],
  }],
  match: 'all',
  withinMs: 60 * 60 * 1000,
  target: {
    runtime: 'agent',
    kind: 'conversation',
    id: 'chat-42',
  },
  continuation: {
    instruction:
      'Check the submitted invoice for anomalies and report back in this conversation.',
  },
});

await ei.triggerControl.createTrigger({
  definition: plan.definition,
  connectionIds: plan.connectionIds,
  actor,
  owner,
});
```

`planTrigger()` is deterministic. It does not call a model. It resolves event names to live source/server IDs, validates predicate paths against advertised payload schemas, compiles `all` / `any` / `sequence` / `count`, and returns the canonical trigger definition plus the required connection IDs.

The persisted `continuation` answers a separate question from the trigger condition: **what should the agent do after the future condition becomes true?**

The wire wake remains deliberately small and reference-only. Embedded hosts also receive an Activation Envelope as the second wake argument. The same envelope can be reconstructed later:

```js
const activation = ei.hydrateWake(wakeId);
```

The envelope contains the configured continuation, trigger/match state, and matched evidence. Event payloads are labeled as untrusted external signals and are included only according to the trigger's `continuation.contextPolicy`.


### Shared hosts, tenant isolation and storage

One EI host can serve many tenants/workspaces without sharing trigger state. Give each host-owned MCP connection a `scopeId` and give tenant-facing code only the corresponding scoped view:

```js
const tenant = await ei.scope('tenant-acme');

await tenant.triggerControl.createTrigger({
  definition,
  connectionIds: ['acme-erp'],
  actor,
  owner,
});

const acmeConnections = tenant.mcpStatus();
```

The default reference store physically namespaces non-default scopes under separate persistent store partitions. Trigger IDs, match IDs, cursors, event sources, deadlines, derived events and wake delivery state are therefore resolved inside a scope rather than filtered out of a global result after the fact. The root host object is the trusted operator/control-plane capability; tenant code should receive a scoped view.

Storage is injectable:

```js
const ei = await createEventIntelligenceHost({
  store: myEventIntelligenceStore,
  mcpRegistry,
  wake,
});
```

`PersistentEventStore` remains the zero-dependency default. A custom backend can implement `forScope(scopeId)` to return an isolated tenant view. For horizontally scaled workers, its wake-delivery claim/lease operations must be atomic across processes; the bundled JSONL store provides serialized atomicity inside one process and is a reference backend, not a distributed database.


## Add Events to an MCP provider

Providers can expose the experimental Events boundary without reimplementing the generic JSON-RPC glue:

```js
import { createMcpEventsProvider } from 'mcp-event-intelligence/provider';

const events = createMcpEventsProvider({
  events: [
    {
      descriptor: {
        name: 'erpnext.sales_invoice.submitted',
        description: 'A submitted Sales Invoice was observed.',
        delivery: ['poll'],
        inputSchema: { type: 'object' },
        payloadSchema: {
          type: 'object',
          required: ['name', 'company', 'grand_total'],
          properties: {
            name: { type: 'string' },
            company: { type: 'string' },
            grand_total: { type: 'number' },
          },
        },
      },
      poll: async ({ cursor, maxEvents, context }) => {
        return providerRuntime.pollInvoices({ cursor, maxEvents, context });
      },
    },
  ],
});
```

The package owns capability advertisement, `server/discover`, `events/list`, `events/poll`, common validation and response shapes. The provider owns domain event definitions, authentication, data queries, occurrence IDs and opaque cursor semantics.

This adapter remains experimental compatibility work around MCP Events; it is not a claim of finalized MCP Events conformance.


An ERPNext-shaped **provider factory** is also exported:

```js
import {
  createErpNextEventsProvider,
} from 'mcp-event-intelligence/provider/erpnext';

const events = createErpNextEventsProvider({
  pollSalesInvoices: ({ cursor, maxEvents }) =>
    erp.pollSubmittedInvoices({ cursor, maxEvents }),
  pollSalesOrders: ({ cursor, maxEvents }) =>
    erp.pollCreatedSalesOrders({ cursor, maxEvents }),
});
```

This helper owns the MCP Events descriptors, schemas and response validation for
`erpnext.sales_invoice.submitted` and `erpnext.sales_order.created`. It is
**not** a credential-owning ERPNext connector: the host/provider must supply the
actual data-access functions. That separation is intentional so Event
Intelligence never duplicates provider authentication.

The production proof that the abstraction works against a real ERP data layer
lives in `sarooo17/world-capability-mcp`: its ERP Events implementation uses
`createMcpEventsProvider` with authenticated ERPNext/Frappe record queries,
tenant/company filters, opaque replay-safe cursors, pagination/`hasMore`,
timezone normalization and deterministic occurrence IDs. The local factory in
this package should therefore be read as a typed convenience API, not as the
production ERP connector itself.

## What v0.3 implements

### Host-owned event sources

- automatic discovery from the host's existing MCP registry;
- reuse of already-connected MCP clients without duplicate credentials;
- experimental MCP Events capability discovery;
- `events/list` and `events/poll`;
- persistent opaque cursors;
- per-scope source/cursor isolation for shared hosts;
- single-flight polling per connection plus bounded `hasMore` batch draining;
- automatic event-source registration;
- dynamic attach/detach of host MCP clients;
- provider-native compatibility adapters such as GitHub webhooks.

### Composite and temporal triggers

- `allOf`, `anyOf`, `sequence`, `count`;
- deterministic same-value correlation;
- optional semantic correlation;
- `absence`, `not`, `unless`, `after`, `until`;
- `debounce`, `threshold`, `rate`, `distinct`;
- calendar-aware conditions with IANA timezones;
- durable deadlines that continue even when no new provider event arrives.

### Agent-authored continuations

- event-source discovery;
- agent-friendly deterministic trigger planning/compilation;
- `eq`, `neq`, `contains`, `in`, `exists`, `gt`, `gte`, `lt`, `lte` predicates;
- persisted continuation contracts separated from trigger conditions;
- Activation Envelope hydration with matched event evidence;
- embedded wake callbacks receive `(packet, activation)`;
- deterministic val