mcp-event-intelligence 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable public changes are documented here.
 
+## [0.1.1] - 2026-09-20
+
+Provider integration patch.
+
+### Provider-facing MCP Events adapter
+
+- public `mcp-event-intelligence/provider` package export;
+- callback-backed `createMcpEventsProvider()` for stateless provider runtimes;
+- generic experimental Events capability advertisement plus `server/discover`, `events/list`, and `events/poll` dispatch;
+- provider-owned opaque cursors, authentication context, data queries and domain event semantics;
+- fail-closed EventOccurrence and payload-schema validation;
+- lower-level store-backed `ExperimentalMcpEventsServer` remains available through the provider export;
+- packed-artifact smoke coverage for the new subpath.
+
+The Event Intelligence and composite-trigger protocol/schema versions remain `0.1.0` / `v0.1`; this patch adds a package integration surface without changing persisted protocol contracts.
+
 ## [0.1.0] - 2026-09-20
 
 Initial public reference release.

package/README.md

@@ -3,6 +3,8 @@
 > 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.1.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.
@@ -21,12 +23,14 @@ Event Intelligence persists that continuation independently of the model, waits
 
 ## Embed it in an existing agent host
 
-After publication:
+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
@@ -50,6 +54,44 @@ const ei = await createEventIntelligenceHost({
 
 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.
 
+
+## 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.
+
 ## What v0.1 implements
 
 ### Host-owned event sources
@@ -166,7 +208,7 @@ A separate live regression also verified real GitHub webhook ingress into the MC
 
 ```bash
 git clone https://github.com/sarooo17/event-intelligence.git
-cd mcp-event-intelligence
+cd event-intelligence
 npm ci
 npm run check
 

package/bin/mcp-event-intelligence.mjs

@@ -4,7 +4,7 @@ const args = process.argv.slice(2);
 const flags = new Set(args);
 
 if (flags.has('--version') || flags.has('-v')) {
-  console.log('0.1.0');
+  console.log('0.1.1');
   process.exit(0);
 }
 
@@ -39,6 +39,10 @@ Embedded hosts:
   import { createEventIntelligenceHost } from 'mcp-event-intelligence/host'
   Pass the harness MCP registry once; EI discovers Events-capable clients automatically.
 
+Provider runtimes:
+  import { createMcpEventsProvider } from 'mcp-event-intelligence/provider'
+  Keep domain events, auth, data access and opaque cursors provider-owned.
+
 Important:
   stdout is reserved for MCP JSON-RPC in stdio mode.
 `);

package/dist/src/mcpEvents/provider.d.ts

@@ -0,0 +1,48 @@
+import type { EventDescriptor, EventOccurrence, JsonRpcRequest, JsonRpcResponse } from '../protocol/types.js';
+export declare const MCP_EVENTS_CAPABILITY_KEY: "io.modelcontextprotocol.experimental/events";
+export declare const MCP_EVENTS_CAPABILITY: Readonly<{
+    status: "draft";
+    designDate: "2026-02-19";
+    methods: readonly ["events/list", "events/poll"];
+    listChanged: false;
+}>;
+export interface ProviderPollRequest<TContext = unknown> {
+    name: string;
+    arguments: Record<string, unknown>;
+    cursor: string | null;
+    maxAgeMs?: number;
+    maxEvents: number;
+    context?: TContext;
+}
+export interface ProviderPollResult {
+    events: EventOccurrence[];
+    cursor: string;
+    truncated?: boolean;
+    hasMore?: boolean;
+    nextPollMs?: number;
+}
+export interface McpProviderEvent<TContext = unknown> {
+    descriptor: EventDescriptor;
+    poll: (request: ProviderPollRequest<TContext>) => ProviderPollResult | Promise<ProviderPollResult>;
+}
+export interface CreateMcpEventsProviderOptions<TContext = unknown> {
+    events: McpProviderEvent<TContext>[];
+    supportedVersions?: string[];
+    instructions?: string;
+}
+export declare function assertJsonSchemaValue(schemaInput: Record<string, unknown>, value: unknown, path?: string): void;
+export declare class McpEventsProvider<TContext = unknown> {
+    private readonly events;
+    readonly supportedVersions: string[];
+    readonly instructions: string;
+    constructor(options: CreateMcpEventsProviderOptions<TContext>);
+    canHandle(method: string): boolean;
+    listEvents(): EventDescriptor[];
+    handleRequest(request: JsonRpcRequest, context?: TContext): Promise<JsonRpcResponse>;
+    private poll;
+    private ok;
+    private error;
+}
+export declare function createMcpEventsProvider<TContext = unknown>(options: CreateMcpEventsProviderOptions<TContext>): McpEventsProvider<TContext>;
+export { ExperimentalMcpEventsServer, decodeMcpEventCursor, encodeMcpEventCursor, } from './server.js';
+export type { McpEventOccurrenceStore, PersistedMcpOccurrence, PollEventsParams, PollEventsResult, RegisteredMcpEvent, } from './server.js';

package/dist/src/mcpEvents/provider.js

@@ -0,0 +1,296 @@
+import { McpEventOccurrenceSchema, } from '../intelligenceProtocol/schemas.js';
+export const MCP_EVENTS_CAPABILITY_KEY = 'io.modelcontextprotocol.experimental/events';
+export const MCP_EVENTS_CAPABILITY = Object.freeze({
+    status: 'draft',
+    designDate: '2026-02-19',
+    methods: ['events/list', 'events/poll'],
+    listChanged: false,
+});
+const ALLOWED_DELIVERY = new Set(['poll', 'push', 'webhook']);
+function assertRecord(value, message) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        throw new Error(message);
+    }
+    return value;
+}
+function optionalFiniteNumber(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative finite number`);
+    }
+    return value;
+}
+function normalizeDescriptor(input) {
+    const raw = assertRecord(input, 'MCP event descriptor must be an object');
+    const name = String(raw.name ?? '').trim();
+    if (!name)
+        throw new Error('MCP event descriptor requires name');
+    const deliveryRaw = Array.isArray(raw.delivery) ? raw.delivery : ['poll'];
+    const delivery = deliveryRaw.map((entry) => String(entry));
+    if (delivery.length === 0 ||
+        delivery.some((entry) => !ALLOWED_DELIVERY.has(entry))) {
+        throw new Error(`MCP event descriptor ${name} has invalid delivery modes`);
+    }
+    if (!delivery.includes('poll')) {
+        throw new Error(`MCP provider event ${name} must advertise poll delivery in v0.1`);
+    }
+    const inputSchema = raw.inputSchema === undefined
+        ? {}
+        : assertRecord(raw.inputSchema, `MCP event descriptor ${name} inputSchema must be an object`);
+    const payloadSchema = raw.payloadSchema === undefined
+        ? {}
+        : assertRecord(raw.payloadSchema, `MCP event descriptor ${name} payloadSchema must be an object`);
+    return {
+        name,
+        description: String(raw.description ?? ''),
+        delivery: delivery,
+        inputSchema,
+        payloadSchema,
+    };
+}
+function schemaTypes(schema) {
+    if (Array.isArray(schema.type)) {
+        return schema.type.map((entry) => String(entry));
+    }
+    return schema.type === undefined ? [] : [String(schema.type)];
+}
+export function assertJsonSchemaValue(schemaInput, value, path = '$') {
+    const schema = assertRecord(schemaInput, `Invalid JSON Schema at ${path}`);
+    if (Object.prototype.hasOwnProperty.call(schema, 'const') &&
+        !Object.is(schema.const, value)) {
+        throw new Error(`MCP event payload violates schema at ${path}: const mismatch`);
+    }
+    if (Array.isArray(schema.enum) &&
+        !schema.enum.some((entry) => Object.is(entry, value))) {
+        throw new Error(`MCP event payload violates schema at ${path}: value not in enum`);
+    }
+    const types = schemaTypes(schema);
+    if (types.length > 0) {
+        const matches = types.some((type) => {
+            if (type === 'null')
+                return value === null;
+            if (type === 'array')
+                return Array.isArray(value);
+            if (type === 'object') {
+                return value !== null && !Array.isArray(value) && typeof value === 'object';
+            }
+            if (type === 'integer')
+                return Number.isInteger(value);
+            if (type === 'number') {
+                return typeof value === 'number' && Number.isFinite(value);
+            }
+            if (type === 'string')
+                return typeof value === 'string';
+            if (type === 'boolean')
+                return typeof value === 'boolean';
+            return false;
+        });
+        if (!matches) {
+            throw new Error(`MCP event payload violates schema at ${path}: expected ${types.join('|')}`);
+        }
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            throw new Error(`MCP event payload violates schema at ${path}: string too short`);
+        }
+        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+            throw new Error(`MCP event payload violates schema at ${path}: string too long`);
+        }
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        if (typeof schema.minimum === 'number' && value < schema.minimum) {
+            throw new Error(`MCP event payload violates schema at ${path}: below minimum`);
+        }
+        if (typeof schema.maximum === 'number' && value > schema.maximum) {
+            throw new Error(`MCP event payload violates schema at ${path}: above maximum`);
+        }
+    }
+    if (value !== null && !Array.isArray(value) && typeof value === 'object') {
+        const record = value;
+        const required = Array.isArray(schema.required)
+            ? schema.required.map((entry) => String(entry))
+            : [];
+        for (const key of required) {
+            if (!Object.prototype.hasOwnProperty.call(record, key)) {
+                throw new Error(`MCP event payload violates schema at ${path}: missing required property ${key}`);
+            }
+        }
+        const properties = schema.properties &&
+            !Array.isArray(schema.properties) &&
+            typeof schema.properties === 'object'
+            ? schema.properties
+            : {};
+        for (const [key, childSchema] of Object.entries(properties)) {
+            if (Object.prototype.hasOwnProperty.call(record, key) &&
+                childSchema &&
+                !Array.isArray(childSchema) &&
+                typeof childSchema === 'object') {
+                assertJsonSchemaValue(childSchema, record[key], `${path}.${key}`);
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(record)) {
+                if (!Object.prototype.hasOwnProperty.call(properties, key)) {
+                    throw new Error(`MCP event payload violates schema at ${path}: unexpected property ${key}`);
+                }
+            }
+        }
+    }
+    if (Array.isArray(value) &&
+        schema.items &&
+        !Array.isArray(schema.items) &&
+        typeof schema.items === 'object') {
+        value.forEach((entry, index) => assertJsonSchemaValue(schema.items, entry, `${path}[${index}]`));
+    }
+}
+function normalizePollParams(paramsInput) {
+    const params = assertRecord(paramsInput ?? {}, 'events/poll params must be an object');
+    const name = String(params.name ?? '').trim();
+    if (!name)
+        throw new Error('events/poll requires name');
+    const cursor = params.cursor === undefined || params.cursor === null
+        ? null
+        : String(params.cursor);
+    const argumentsValue = params.arguments === undefined
+        ? {}
+        : assertRecord(params.arguments, 'events/poll arguments must be an object');
+    const maxAgeMs = optionalFiniteNumber(params.maxAgeMs, 'maxAgeMs');
+    const maxEventsRaw = params.maxEvents ?? 50;
+    if (typeof maxEventsRaw !== 'number' ||
+        !Number.isInteger(maxEventsRaw) ||
+        maxEventsRaw < 1 ||
+        maxEventsRaw > 500) {
+        throw new Error('maxEvents must be an integer between 1 and 500');
+    }
+    return {
+        name,
+        arguments: argumentsValue,
+        cursor,
+        ...(maxAgeMs === undefined ? {} : { maxAgeMs }),
+        maxEvents: maxEventsRaw,
+    };
+}
+export class McpEventsProvider {
+    events = new Map();
+    supportedVersions;
+    instructions;
+    constructor(options) {
+        if (!options || !Array.isArray(options.events)) {
+            throw new Error('MCP Events provider requires events[]');
+        }
+        for (const input of options.events) {
+            if (!input || typeof input.poll !== 'function') {
+                throw new Error('MCP provider event requires poll()');
+            }
+            const descriptor = normalizeDescriptor(input.descriptor);
+            if (this.events.has(descriptor.name)) {
+                throw new Error(`Duplicate MCP provider event: ${descriptor.name}`);
+            }
+            this.events.set(descriptor.name, {
+                descriptor,
+                poll: input.poll,
+            });
+        }
+        this.supportedVersions =
+            options.supportedVersions?.map(String).filter(Boolean) ?? ['2026-07-28'];
+        this.instructions =
+            options.instructions ??
+                'Experimental MCP Events provider compatibility adapter. Events follow the Triggers & Events design sketch; this is not finalized MCP conformance.';
+    }
+    canHandle(method) {
+        return (method === 'server/discover' ||
+            method === 'events/list' ||
+            method === 'events/poll');
+    }
+    listEvents() {
+        return [...this.events.values()].map(({ descriptor }) => descriptor);
+    }
+    async handleRequest(request, context) {
+        try {
+            switch (request.method) {
+                case 'server/discover':
+                    return this.ok(request.id, {
+                        supportedVersions: this.supportedVersions,
+                        capabilities: {
+                            experimental: {
+                                [MCP_EVENTS_CAPABILITY_KEY]: MCP_EVENTS_CAPABILITY,
+                            },
+                        },
+                        instructions: this.instructions,
+                    });
+                case 'events/list':
+                    return this.ok(request.id, {
+                        events: this.listEvents(),
+                    });
+                case 'events/poll':
+                    return this.ok(request.id, await this.poll(request.params, context));
+                default:
+                    return this.error(request.id, -32601, `Method not found: ${request.method}`);
+            }
+        }
+        catch (error) {
+            return this.error(request.id, -32602, error instanceof Error ? error.message : 'Invalid params');
+        }
+    }
+    async poll(paramsInput, context) {
+        const params = normalizePollParams(paramsInput);
+        const registered = this.events.get(params.name);
+        if (!registered) {
+            throw new Error(`Unknown event: ${params.name}`);
+        }
+        const result = assertRecord(await registered.poll({
+            ...params,
+            context,
+        }), `MCP provider ${params.name} returned invalid poll result`);
+        if (typeof result.cursor !== 'string') {
+            throw new Error(`MCP provider ${params.name} returned poll result without string cursor`);
+        }
+        if (!Array.isArray(result.events)) {
+            throw new Error(`MCP provider ${params.name} returned poll result without events[]`);
+        }
+        if (result.events.length > params.maxEvents) {
+            throw new Error(`MCP provider ${params.name} returned more than maxEvents=${params.maxEvents}`);
+        }
+        const events = result.events.map((raw) => {
+            const parsed = McpEventOccurrenceSchema.safeParse(raw);
+            if (!parsed.success) {
+                throw new Error(`MCP provider ${params.name} returned invalid EventOccurrence: ${parsed.error.message}`);
+            }
+            if (parsed.data.name !== params.name) {
+                throw new Error(`MCP provider event name mismatch: expected ${params.name}, got ${parsed.data.name}`);
+            }
+            assertJsonSchemaValue(registered.descriptor.payloadSchema, parsed.data.data);
+            return parsed.data;
+        });
+        const truncated = result.truncated ?? false;
+        const hasMore = result.hasMore ?? false;
+        if (typeof truncated !== 'boolean' || typeof hasMore !== 'boolean') {
+            throw new Error(`MCP provider ${params.name} returned invalid pagination flags`);
+        }
+        const nextPollMs = result.nextPollMs ?? 5000;
+        if (typeof nextPollMs !== 'number' ||
+            !Number.isInteger(nextPollMs) ||
+            nextPollMs < 0 ||
+            nextPollMs > 300000) {
+            throw new Error(`MCP provider ${params.name} returned invalid nextPollMs`);
+        }
+        return {
+            events,
+            cursor: result.cursor,
+            truncated,
+            hasMore,
+            nextPollMs,
+        };
+    }
+    ok(id, result) {
+        return { jsonrpc: '2.0', id, result };
+    }
+    error(id, code, message) {
+        return { jsonrpc: '2.0', id, error: { code, message } };
+    }
+}
+export function createMcpEventsProvider(options) {
+    return new McpEventsProvider(options);
+}
+export { ExperimentalMcpEventsServer, decodeMcpEventCursor, encodeMcpEventCursor, } from './server.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-event-intelligence",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Durable temporal event intelligence for agent hosts: host-owned MCP event discovery, composite triggers, derived events, and targeted wakeups.",
   "license": "Apache-2.0",
   "type": "module",
@@ -14,6 +14,10 @@
     "./host": {
       "types": "./scripts/host-integration.d.mts",
       "import": "./scripts/host-integration.mjs"
+    },
+    "./provider": {
+      "types": "./dist/src/mcpEvents/provider.d.ts",
+      "import": "./dist/src/mcpEvents/provider.js"
     }
   },
   "bin": {

package/scripts/mcp-stdio-server.mjs

@@ -341,7 +341,7 @@ export async function buildEventIntelligenceMcpServer({
   const server = new McpServer(
     {
       name: 'mcp-event-intelligence',
-      version: '0.1.0',
+      version: '0.1.1',
     },
     {
       instructions:

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.sarooo17/event-intelligence",
   "title": "MCP Event Intelligence",
   "description": "Durable temporal event intelligence: composite triggers, derived events, and runtime wakeups.",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "repository": {
     "url": "https://github.com/sarooo17/event-intelligence",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-event-intelligence",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "transport": {
         "type": "stdio"
       },