mcp-event-intelligence
Advanced tools
Durable temporal event intelligence for agent hosts: host-owned MCP event discovery, composite triggers, derived events, and targeted wakeups.
Durable temporal event intelligence for sleeping agents.
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.
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.
Install from npm:
npm install mcp-event-intelligence
Published package: npm · Official MCP Registry
Pass the harness-level MCP registry once — not every MCP one by one:
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.
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:
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:
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.
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:
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:
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.
Providers can expose the experimental Events boundary without reimplementing the generic JSON-RPC glue:
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 the current draft Events extension identifier/settings, events/list, events/poll, common validation and response shapes. The embedding MCP server advertises capabilities.extensions["io.modelcontextprotocol/events"]; the provider owns domain event definitions, authentication, data queries, occurrence IDs and opaque cursor semantics.
This adapter tracks the current experimental MCP Events draft. It is not a claim of finalized MCP Events conformance. The v0.4 compatibility snapshot follows the io.modelcontextprotocol/events extension-negotiation direction in experimental-ext-triggers-events PR #7 and the discovery/poll contract exercised by conformance PR #521 as of 2026-09-25.
An ERPNext-shaped provider factory is also exported:
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.
capabilities.extensions["io.modelcontextprotocol/events"];events/list discovery;(connection, event name, arguments);events/poll with server-directed nextPollMs, nullable cursors and bounded page draining;hasMore batch draining;allOf, anyOf, sequence, count;absence, not, unless, after, until;debounce, threshold, rate, distinct;events/list discovers an EventSource descriptor. A durable EventSubscription is a separate runtime object identified by the host connection, event name and canonical subscription arguments. Each subscription owns its cursor/delivery state independently.
This keeps MCP-side filtering separate from Event Intelligence conditions: arguments are validated against the provider's inputSchema; trigger where predicates are evaluated by EI against delivered payloads. Two triggers may therefore subscribe to the same event name with different arguments without sharing cursors.
Poll, push and webhook are treated only as delivery mechanisms. All three normalize into the same EventOccurrence ingestion path before correlation, temporal reasoning, derived events or wake logic.
arguments validated against each source inputSchema, kept distinct from EI payload predicates;eq, neq, contains, in, exists, gt, gte, lt, lte predicates;(packet, activation);Triggers can emit immutable higher-level events instead of waking an agent:
pr.merged + deploy.succeeded
↓
release.ready@1
+
manager.approved
↓
rollout.allowed@1
↓
runtime wake
Derived events preserve refs-only lineage to their direct parents and flattened root evidence.
Derived event names are versioned contracts such as release.ready@1.
An embedded harness can provide one in-process wake dispatcher that routes by target.runtime, target.kind and target.id; runtime-specific handlers remain available as a lower-level option. A standalone deployment can instead use signed HMAC callbacks. Both paths return a stable runtimeReceiptId.
Runtime delivery is durable: a stable wake ID gets a persisted delivery record, a worker claims it with a lease, transient failures are retried with bounded exponential backoff, expired claims can be recovered after restart, and only an exhausted retry budget enters dead-letter. This prevents two workers sharing an atomic store from intentionally owning the same delivery at the same time. The runtime should still treat the stable wake ID as an idempotency key because no system can make an arbitrary external side effect transactionally exactly-once without cooperation from the receiver.
MCP Events is concerned with the event transport/subscription boundary. Event Intelligence explores the layer above transport:
This project does not propose a replacement for MCP Events and does not claim to be an official MCP extension.
Event Intelligence has one optional AI boundary: semantic correlation.
TYPESAFE_API_KEY enables the bundled TypeSafe Jev evaluator when a trigger explicitly requests semantic correlation.semanticEvaluator instead.The agent/harness is already responsible for natural-language reasoning. It can use trigger_plan / planTrigger() to compile common requests deterministically against discovered source schemas, or submit a canonical trigger definition directly for advanced cases. Deterministic correlation, temporal logic, persistence, derived events and wake delivery require no model API.
The v0.4 acceptance suite verifies:
A separate live regression also verified real GitHub webhook ingress into the MCP EventOccurrence / composite fan-in path.
git clone https://github.com/sarooo17/event-intelligence.git
cd event-intelligence
npm ci
npm run check
export SERVICE_AUTH_TOKEN="$(openssl rand -hex 32)"
npm start
Then:
curl http://127.0.0.1:3000/readyz
The standalone service supports manual/provider-native event ingress. It does not own arbitrary MCP connections; host-owned MCP reuse belongs to the package integration above.
docker build -t mcp-event-intelligence:0.4.0 .
docker run --rm \
-p 3000:3000 \
-v mcp-event-intelligence-data:/data \
-e SERVICE_AUTH_TOKEN="$(openssl rand -hex 32)" \
mcp-event-intelligence:0.4.0
The package also exposes a standard MCP stdio control plane through the official TypeScript SDK v2:
npx mcp-event-intelligence mcp
Read/non-mutating tools are exposed by default, including event_sources_list, trigger_plan, inspection, simulation, wake_hydrate, contracts and runtime status. trigger_create accepts either a raw canonical definition or the same agent-friendly plan shape; EI compiles the latter before applying the normal mutation controls.
Persistent trigger mutations are only registered when the operator explicitly enables MCP_WRITE_ENABLED=true, and each mutation still requires a confirmationId. The MCP server is a control-plane adapter; it is not a gateway through which the host's other MCP servers must be reconnected.
See docs/QUICKSTART.md and docs/MCP-REGISTRY.md.
Standalone/core environment variables:
| Variable | Required | Purpose |
|---|---|---|
SERVICE_AUTH_TOKEN | yes for protected HTTP APIs | bearer token for control-plane endpoints |
DATA_DIR | no | persistent JSONL directory, default ./data |
PORT | no | HTTP port, default 3000 |
ENVIRONMENT_ID | no | environment boundary |
RUNTIME_WAKE_TARGETS_JSON | no | signed standalone runtime callbacks |
GITHUB_WEBHOOK_SECRET | no | verify GitHub webhook ingress |
TYPESAFE_API_KEY | no | bundled TypeSafe Jev semantic evaluator |
WAKE_DELIVERY_MAX_ATTEMPTS | no | maximum wake delivery attempts, default 5 |
WAKE_DELIVERY_LEASE_MS | no | claim lease duration, default 30000 |
WAKE_RETRY_BASE_DELAY_MS | no | first retry delay, default 1000 |
WAKE_RETRY_MAX_DELAY_MS | no | retry backoff cap, default 60000 |
WAKE_RETRY_TICK_MS | no | retry scheduler tick, default 1000 |
Embedded hosts pass one MCP registry adapter. Event Intelligence discovers already-connected clients from that registry; provider MCP connection settings are not duplicated inside EI.
The detailed execution model, clocks, lifecycle, persistence and trust boundaries are documented in docs/ARCHITECTURE.md.
Normal event windows use event occurredAt.
Absence/deadline progression uses Event Intelligence processing time. This separation is explicit and tested.
The implementation does not claim theoretical distributed exactly-once delivery.
It uses stable wake IDs, persisted delivery state, atomic claim leases, bounded retries, runtime receipts and replay handling to provide effectively-once runtime activation in the validated reference scenarios.
A derived event says what became true at a point in history.
v0.3 intentionally does not implement a mutable current-state/facts database.
Read SECURITY.md and docs/SECURITY-MODEL.md.
In embedded mode, the host retains MCP authorization and credentials; Event Intelligence discovers only the client objects exposed through the host-provided MCP registry. Tenant-facing callers should receive only host.scope(scopeId). The reference JSONL store is scope-partitioned and single-process; distributed custom stores must preserve scope isolation and atomic wake claims.
There are two separate MCP boundaries:
io.modelcontextprotocol/events extension, plus provider-native adapters; poll is native in the reference provider adapter, while push/webhook receivers remain host-owned delivery adapters;Registry identity:
io.github.sarooo17/event-intelligence
server.json is validated with the official mcp-publisher validate command in CI. MCP Events itself remains experimental and may change as the Triggers & Events work evolves.
v0.4.x reference implementation / experimental.
The architecture is implemented and exercised end-to-end. Storage is now injectable and scoped, while the bundled JSONL backend remains a single-process reference implementation. Remaining work is primarily production database adapters/HA validation, scale benchmarks and upstream feedback.
See the release-gate example for a composed future-condition flow using durable time, derived events and targeted wake.
See CONTRIBUTING.md.
Contributions are especially useful around host adapters, MCP Events compatibility, temporal semantics, production persistence, security review and reproducible provider integrations.
Apache License 2.0. See LICENSE.
This is an independent open-source project. It is not an official Model Context Protocol specification and is not affiliated with or endorsed by the MCP maintainers.
FAQs
Durable temporal event intelligence for agent hosts: host-owned MCP event discovery, composite triggers, derived events, and targeted wakeups.
The npm package mcp-event-intelligence receives a total of 1,007 weekly downloads. As such, mcp-event-intelligence popularity was classified as popular.
We found that mcp-event-intelligence demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Company News
Socket is joining the OpenJS Security Stewardship Program to fund Node.js vulnerability research, maintainer remediation, and security releases.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.