mcp-event-intelligence 0.1.0 → 0.2.0

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.2.0",
   "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,14 @@
     "./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"
+    },
+    "./provider/erpnext": {
+      "types": "./dist/src/mcpEvents/erpnextProvider.d.ts",
+      "import": "./dist/src/mcpEvents/erpnextProvider.js"
     }
   },
   "bin": {

package/scripts/host-integration.d.mts

@@ -14,8 +14,12 @@ export interface HostMcpConnectionOptions {
   client?: HostMcpClientLike;
   request?: (method: string, params?: unknown) => Promise<unknown>;
   enabled?: boolean;
+  /** Isolation partition used by the shared EI host. Defaults to \"default\". */
+  scopeId?: string;
   pollIntervalMs?: number;
   maxEvents?: number;
+  /** Maximum number of immediately drained pages when the provider reports hasMore. */
+  maxPollBatches?: number;
 }
 
 export interface HostMcpRegistry {
@@ -36,8 +40,18 @@ export type HostWakeHandler = (
   packet: Record<string, unknown>,
 ) => Promise<HostWakeReceipt | string> | HostWakeReceipt | string;
 
+export interface EventIntelligenceStore {
+  init?(): Promise<unknown>;
+  /** Required when non-default scopes are used. Implementations should return an isolated store view. */
+  forScope?(scopeId: string): Promise<EventIntelligenceStore> | EventIntelligenceStore;
+  listScopeIds?(): Promise<string[]> | string[];
+  [key: string]: any;
+}
+
 export interface EventIntelligenceHostOptions {
   dataDir?: string;
+  /** Optional storage backend. PersistentEventStore is used when omitted. */
+  store?: EventIntelligenceStore;
   env?: Record<string, string | undefined>;
   mcpRegistry?: HostMcpRegistry;
   /** Low-level/manual fallback; prefer mcpRegistry for automatic discovery. */
@@ -49,19 +63,25 @@ export interface EventIntelligenceHostOptions {
   semanticEvaluator?: unknown;
 }
 
-export interface EventIntelligenceHost {
+export interface EventIntelligenceScopedHost {
+  readonly scopeId: string;
   readonly runtime: any;
-  readonly store: any;
+  readonly store: EventIntelligenceStore;
   readonly triggerControl: any;
   readonly triggerInspector: any;
   readonly eventSources: any[];
-  refreshMcpRegistry(): Promise<any[]>;
   attachMcpClient(connection: HostMcpConnectionOptions): Promise<{
     connectionId: string;
     events: any[];
   }>;
-  detachMcpClient(connectionId: string): Promise<boolean>;
   mcpStatus(): any[];
+}
+
+export interface EventIntelligenceHost extends EventIntelligenceScopedHost {
+  refreshMcpRegistry(): Promise<any[]>;
+  detachMcpClient(connectionId: string): Promise<boolean>;
+  loadedScopes(): string[];
+  scope(scopeId?: string): Promise<EventIntelligenceScopedHost>;
   close(): Promise<void>;
 }
 
@@ -84,3 +104,13 @@ export function createHostMcpEventsConnection(
 export function createEventIntelligenceHost(
   options?: EventIntelligenceHostOptions,
 ): Promise<EventIntelligenceHost>;
+
+
+export class PersistentEventStore implements EventIntelligenceStore {
+  constructor(dataDir: string);
+  readonly dataDir: string;
+  init(): Promise<unknown>;
+  forScope(scopeId?: string): Promise<PersistentEventStore>;
+  listScopeIds(): Promise<string[]>;
+  [key: string]: any;
+}

package/scripts/host-integration.mjs

@@ -4,6 +4,11 @@ import {
 import {
   createHostMcpEventsConnection,
 } from './lib/mcp-events-client.mjs';
+import {
+  DEFAULT_EVENT_SCOPE_ID,
+  PersistentEventStore,
+  normalizeEventScopeId,
+} from './lib/persistent-event-store.mjs';
 
 function normalizeMcpConnection(input) {
   const connectionId = String(
@@ -61,6 +66,31 @@ export function createMcpRegistryAdapter({
   };
 }
 
+function scopedHostView(runtime, context) {
+  const scopeId = context.scopeId;
+  return {
+    scopeId,
+    runtime: context,
+    store: context.store,
+    triggerControl: context.triggerControl,
+    triggerInspector: context.triggerInspector,
+    get eventSources() {
+      return context.triggerControl.listEventSources();
+    },
+    async attachMcpClient(connection) {
+      const normalized = normalizeMcpConnection({
+        ...connection,
+        scopeId,
+      });
+      return runtime.mcpEventsClient.attachConnection(normalized);
+    },
+    mcpStatus() {
+      return runtime.mcpEventsClient.status()
+        .filter((entry) => entry.scopeId === scopeId);
+    },
+  };
+}
+
 /**
  * Embed Event Intelligence once at the harness/host level.
  *
@@ -70,6 +100,7 @@ export function createMcpRegistryAdapter({
  */
 export async function createEventIntelligenceHost({
   dataDir,
+  store,
   env = {},
   mcpRegistry,
   mcpClients = [],
@@ -88,6 +119,7 @@ export async function createEventIntelligenceHost({
     wake,
     wakeHandlers,
     semanticEvaluator,
+    store,
   });
 
   const registryManaged = new Set();
@@ -117,7 +149,8 @@ export async function createEventIntelligenceHost({
       if (existing) {
         if (
           existing.identity === connection.identity &&
-          existing.serverId === connection.serverId
+          existing.serverId === connection.serverId &&
+          existing.scopeId === connection.scopeId
         ) {
           registryManaged.add(connectionId);
           outcomes.push({ connectionId, status: 'already_attached' });
@@ -179,6 +212,7 @@ export async function createEventIntelligenceHost({
   }
 
   return {
+    scopeId: DEFAULT_EVENT_SCOPE_ID,
     runtime,
     get store() {
       return runtime.store;
@@ -204,6 +238,14 @@ export async function createEventIntelligenceHost({
     mcpStatus() {
       return runtime.mcpEventsClient.status();
     },
+    loadedScopes() {
+      return runtime.loadedScopes();
+    },
+    async scope(scopeIdInput = DEFAULT_EVENT_SCOPE_ID) {
+      const scopeId = normalizeEventScopeId(scopeIdInput);
+      const context = await runtime.scope(scopeId);
+      return scopedHostView(runtime, context);
+    },
     async close() {
       unsubscribe?.();
       await runtime.close();
@@ -213,4 +255,5 @@ export async function createEventIntelligenceHost({
 
 export {
   createHostMcpEventsConnection,
+  PersistentEventStore,
 };