Building a Custom Rule Engine

// What the gateway POSTs to your webhook.
export interface WebhookRequest {
  metadata: WebhookMetadata;
  body: JsonRpcResponse;
}

export interface WebhookMetadata {
  /** Engine's ID in MCP Manager (CSO guid). */
  ruleEngineId: string;
  /** User whose tool call triggered this message. May be null for service-to-service traffic. */
  userGuid: string | null;
  /** Email of the user whose tool call triggered this message. May be null for service-to-service traffic. */
  userEmail: string | null;
  /** Gateway that fired the rule. May be null in edge cases. */
  gatewayGuid: string | null;
  /** MCP server involved in the message. May be null in edge cases. */
  serverGuid: string | null;
  /** Correlation ID — matches the value shown in your logs and alerts. */
  sessionId: string;
  /** ISO 8601. */
  timestamp: string;
  /**
   * Which leg of the tool call this is.
   *  - 'request'  → body is the upstream tool call (body.params.arguments carries the tool args)
   *  - 'response' → body is the tool result (body.result carries the returned content)
   */
  direction: 'request' | 'response';
  /** Tool that was called, when known. */
  toolName: string | null;
  /** MCP JSON-RPC method — 'tools/call' (gateway rules apply to tools only). */
  method: string;
  /** JSON-RPC id of the in-flight request — echo it back unchanged in any modify response. */
  requestId: string | number;
}

// The MCP message your engine inspects. JSON-RPC 2.0.
export interface JsonRpcResponse {
  jsonrpc: '2.0';
  id: string | number | null;
  /** Present on a result. A plain string, an OpenAI-shaped content envelope, or arbitrary JSON. */
  result?: unknown;
  /** Present on error responses from the upstream MCP server. */
  error?: { code: number; message: string; data?: unknown };
}

// What your webhook MUST return. Pick exactly one shape.
export type WebhookResponse = PassResponse | BlockResponse | ModifyResponse | ErrorResponse;

export interface PassResponse {
  type: 'pass';
  comment?: string;
}

export interface BlockResponse {
  type: 'block';
  comment?: string;
}

export interface ModifyResponse {
  type: 'modify';
  comment?: string;
  modifiedPayload: {
    /** A COMPLETE JSON-RPC response, not a partial. Same id as the inbound request. */
    body: JsonRpcResponse;
  };
}

export interface ErrorResponse {
  type: 'error';
  comment?: string;
}

import type { JsonRpcResponse } from './webhook-types';

/**
 * Pulls the user-visible text out of a tool response. Handles all three body shapes:
 *  - OpenAI-style { content: [{ type: 'text', text }] } → joins all text items with newlines
 *  - Plain string result → returns it
 *  - Anything else → JSON-stringifies it so a regex / classifier still has something to scan
 * Returns null when the response has no result at all (e.g. a JSON-RPC error response).
 */
export function extractResponseText(body: JsonRpcResponse): string | null {
  if (body.result == null) return null;
  if (typeof body.result === 'string') return body.result;
  if (typeof body.result === 'object') {
    const envelope = body.result as { content?: Array<{ type?: string; text?: string }> };
    if (Array.isArray(envelope.content)) {
      const texts = envelope.content
        .filter((item) => item?.type === 'text' && typeof item.text === 'string')
        .map((item) => item.text as string);
      if (texts.length > 0) return texts.join('\n');
    }
    return JSON.stringify(body.result);
  }
  return String(body.result);
}

/**
 * Builds a new JsonRpcResponse with the given text substituted back into the same slot the
 * original came from. Echoes the inbound id so the modify response is JSON-RPC-valid.
 */
export function buildResponseWithReplacedText(original: JsonRpcResponse, replacement: string): JsonRpcResponse {
  if (typeof original.result === 'string') {
    return { jsonrpc: '2.0', id: original.id, result: replacement };
  }
  if (original.result && typeof original.result === 'object') {
    const envelope = original.result as { content?: Array<{ type?: string; text?: string }> };
    if (Array.isArray(envelope.content)) {
      const rewritten = envelope.content.map((item) => (item?.type === 'text' ? { ...item, text: replacement } : item));
      return { jsonrpc: '2.0', id: original.id, result: { ...envelope, content: rewritten } };
    }
  }
  return { jsonrpc: '2.0', id: original.id, result: replacement };
}

import type { Request, Response } from 'express';
import express from 'express';
import { buildResponseWithReplacedText, extractResponseText } from './helpers';
import type { WebhookRequest, WebhookResponse } from './webhook-types';

const app = express();
app.use(express.json({ limit: '16mb' })); // matches the gateway's body cap

const SHARED_SECRET = process.env.MCP_RULE_ENGINE_SECRET ?? '';
const CREDIT_CARD_PATTERN = /\b(?:\d[ -]*?){13,19}\b/;
const EMAIL_PATTERN = /\b[\w.+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g;

app.post('/inspect', (request: Request, response: Response) => {
  // Verify the shared secret you configured in the rule engine's Headers section.
  if (request.headers['x-api-key'] !== SHARED_SECRET) {
    response.status(401).json({ error: 'Unauthorized' });
    return;
  }

  const envelope = request.body as WebhookRequest;
  const text = extractResponseText(envelope.body);

  // No usable text (e.g. an upstream JSON-RPC error) — let it through.
  if (text == null) {
    response.json({ type: 'pass', comment: 'no text to inspect' } satisfies WebhookResponse);
    return;
  }

  // Hard fail: credit card detected → block.
  if (CREDIT_CARD_PATTERN.test(text)) {
    response.json({ type: 'block', comment: 'credit card number detected' } satisfies WebhookResponse);
    return;
  }

  // Soft fail: emails → redact in place and forward.
  if (EMAIL_PATTERN.test(text)) {
    const redacted = text.replace(EMAIL_PATTERN, '[REDACTED EMAIL]');
    const modifiedBody = buildResponseWithReplacedText(envelope.body, redacted);
    response.json({
      type: 'modify',
      comment: 'redacted email address(es)',
      modifiedPayload: { body: modifiedBody },
    } satisfies WebhookResponse);
    return;
  }

  response.json({ type: 'pass' } satisfies WebhookResponse);
});

const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`Rule engine listening on :${port}`));