mcp-agentic-pipelines 1.0.1

package/packages/core/src/rate-limiter.ts

@@ -0,0 +1,136 @@
+/**
+ * Token Bucket Rate Limiter
+ *
+ * Per-tool rate limiting using the token bucket algorithm.
+ * Different rate categories for costly vs read-only operations.
+ */
+
+import { RateLimitError } from './errors.js';
+
+// ── Token Bucket ─────────────────────────────────────────────────────
+
+export class TokenBucket {
+  private tokens: number;
+  private lastRefill: number;
+
+  constructor(
+    private readonly maxTokens: number,
+    private readonly refillRate: number, // tokens per second
+  ) {
+    this.tokens = maxTokens;
+    this.lastRefill = Date.now();
+  }
+
+  /**
+   * Attempt to consume tokens from the bucket.
+   * @returns true if tokens were available and consumed.
+   */
+  tryConsume(count: number = 1): boolean {
+    this.refill();
+    if (this.tokens >= count) {
+      this.tokens -= count;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Estimate milliseconds until the next token is available.
+   */
+  timeUntilNextToken(): number {
+    this.refill();
+    if (this.tokens >= 1) return 0;
+    // tokens is between 0 and 1 (fractional). Need (1 - tokens) worth of refill.
+    const needed = 1 - this.tokens;
+    return Math.ceil((needed / this.refillRate) * 1000);
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+    this.lastRefill = now;
+  }
+}
+
+// ── Rate Limiter ─────────────────────────────────────────────────────
+
+/** Rate limit category — determines the token bucket parameters. */
+export type RateCategory = 'costly' | 'write' | 'read';
+
+const RATE_LIMITS: Record<RateCategory, { maxTokens: number; refillRate: number }> = {
+  costly: { maxTokens: 1, refillRate: 1 },      // 1 req/s
+  write:  { maxTokens: 5, refillRate: 5 },      // 5 req/s
+  read:   { maxTokens: 30, refillRate: 30 },    // 30 req/s
+};
+
+export class RateLimiter {
+  private buckets = new Map<string, TokenBucket>();
+  private enabled: boolean;
+
+  constructor(
+    private readonly defaultMaxRPS: number = 10,
+    enabled: boolean = true,
+  ) {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check and consume a rate limit token for a tool.
+   * Throws RateLimitError if limit exceeded.
+   *
+   * @param toolName - MCP tool name.
+   * @param category - Rate category override (auto-detected if omitted).
+   */
+  check(toolName: string, category?: RateCategory): void {
+    if (!this.enabled) return;
+
+    const bucket = this.getBucket(toolName, category);
+    if (!bucket.tryConsume()) {
+      const retryMs = bucket.timeUntilNextToken();
+      throw new RateLimitError(toolName, retryMs);
+    }
+  }
+
+  /**
+   * Create or retrieve a token bucket for a tool.
+   */
+  private getBucket(toolName: string, category?: RateCategory): TokenBucket {
+    if (!this.buckets.has(toolName)) {
+      const cat = category ?? this.detectCategory(toolName);
+      const limits = RATE_LIMITS[cat];
+      this.buckets.set(toolName, new TokenBucket(limits.maxTokens, limits.refillRate));
+    }
+    return this.buckets.get(toolName)!;
+  }
+
+  /**
+   * Auto-detect rate category from tool name prefix.
+   */
+  private detectCategory(toolName: string): RateCategory {
+    // Costly: full pipeline runs, audio processing
+    if (
+      toolName.startsWith('piste_fact_check') ||
+      toolName.startsWith('clinical_process') ||
+      toolName.startsWith('precis_query')
+    ) {
+      return 'costly';
+    }
+    // Write: ingestion, upload
+    if (
+      toolName.includes('ingest') ||
+      toolName.includes('upload') ||
+      toolName.includes('remove') ||
+      toolName.includes('extract')
+    ) {
+      return 'write';
+    }
+    // Read: everything else
+    return 'read';
+  }
+}
+
+/** Create a rate limiter from configuration. */
+export function createRateLimiter(enabled: boolean, maxRPS: number): RateLimiter {
+  return new RateLimiter(maxRPS, enabled);
+}

package/packages/core/src/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared TypeScript Types
+ *
+ * Common types used across all integration packages.
+ */
+
+import type { ResolvedLLMConfig } from './llm-config.js';
+
+// ── MCP Tool Types ───────────────────────────────────────────────────
+
+/** Standard MCP tool response content item. */
+export interface MCPTextContent {
+  type: 'text';
+  text: string;
+}
+
+/** Standard MCP tool response. */
+export interface MCPToolResponse {
+  content: MCPTextContent[];
+  isError?: boolean;
+}
+
+/** MCP resource content. */
+export interface MCPResourceContent {
+  uri: string;
+  mimeType: string;
+  text?: string;
+  blob?: string;
+}
+
+/** Definition of a registered MCP tool. */
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/** Definition of a registered MCP resource. */
+export interface ResourceDefinition {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+/** Definition of a registered MCP prompt. */
+export interface PromptDefinition {
+  name: string;
+  description: string;
+  arguments?: Array<{
+    name: string;
+    description: string;
+    required: boolean;
+  }>;
+}
+
+// ── Health Status ────────────────────────────────────────────────────
+
+export interface ServiceHealth {
+  service: string;
+  status: 'healthy' | 'unhealthy' | 'disabled';
+  provider?: string;
+  model?: string;
+  error?: string;
+}
+
+// ── LLM Provider Info ────────────────────────────────────────────────
+
+export interface LLMProviderInfo {
+  provider: string;
+  baseUrl: string;
+  defaultModel: string;
+  isOpenAICompatible: boolean;
+  configured: boolean;
+}
+
+// ── Audio Types (Clinical Intake) ────────────────────────────────────
+
+export interface AudioTurn {
+  role: 'user' | 'assistant';
+  text: string;
+  audioBase64?: string;
+  turnNumber: number;
+}
+
+export interface ClinicalSession {
+  sessionId: string;
+  patientName: string;
+  lang: 'en' | 'fr';
+  turns: AudioTurn[];
+  createdAt: string;
+  isComplete: boolean;
+}
+
+// ── Search Types (DeepPipe) ──────────────────────────────────────────
+
+export interface SearchHit {
+  score: number;
+  source: string;
+  snippet?: string;
+  documentId: number;
+}
+
+export interface SearchResults {
+  hits: SearchHit[];
+  totalHits: number;
+  elapsedMs: number;
+}
+
+export interface StoredDocument {
+  id: number;
+  source: string;
+  wordCount: number;
+  indexedAt: string;
+  format?: string;
+}
+
+// ── Chat Types (DeepPipe RAG) ────────────────────────────────────────
+
+export interface ChatSource {
+  index: number;
+  documentId: number;
+  title: string;
+  sourcePath: string;
+  score: number;
+}
+
+export interface ChatContext {
+  grounded: boolean;
+  sources: ChatSource[];
+  messages: Array<{ role: string; content: string }>;
+}
+
+// ── Fact-Check Types (Piste) ─────────────────────────────────────────
+
+export type VerdictLabel =
+  | 'TRUE'
+  | 'MOSTLY_TRUE'
+  | 'HALF_TRUE'
+  | 'MOSTLY_FALSE'
+  | 'FALSE'
+  | 'PANTS_ON_FIRE'
+  | 'UNVERIFIABLE';
+
+export interface FactCheckVerdict {
+  runId: string;
+  claimId: string;
+  verdict: {
+    label: VerdictLabel;
+    distribution: Record<string, number>;
+    explanation: string;
+    sources: Array<{
+      url: string;
+      title: string;
+      classification: 'SUPPORTS' | 'REFUTES' | 'UNRELATED';
+    }>;
+  };
+  auditUrl: string;
+  elapsedMs: number;
+}
+
+// ── Precis Types (Agentic RAG) ───────────────────────────────────────
+
+export interface PrecisQueryResult {
+  status: 'success' | 'blocked' | 'error';
+  traceId: string;
+  plan?: {
+    subtasks: Array<{ id: string; type: string; query: string }>;
+    reasoning: string;
+  };
+  report?: Record<string, unknown>;
+  evaluation?: {
+    relevancy: number;
+    trust: number;
+    exhaustivity: number;
+    hallucinationRate: number;
+    citationCoverage: number;
+    flaggedIssues: string[];
+  };
+  guardrail?: {
+    action: 'pass' | 'flag' | 'redact' | 'block';
+    issues: string[];
+    requiresHumanReview: boolean;
+  };
+  error?: string;
+}
+
+// ── Work Order Types (Precis) ────────────────────────────────────────
+
+export interface WorkOrder {
+  id: string;
+  tailNumber: string;
+  workOrderNumber: string;
+  date: string;
+  aircraftModel: string;
+  partNumbers: string[];
+  mechanicId: string;
+  station: string;
+  hoursWorked: number;
+  inspectorStamp: string;
+  adSbReferences: string[];
+  fieldsExtracted: number;
+}

package/packages/core/src/validation.ts

@@ -0,0 +1,101 @@
+/**
+ * Runtime Input Validation
+ *
+ * Wraps Zod schemas for validating MCP tool input arguments.
+ * Returns structured ValidationErrors on failure.
+ */
+
+import { z, ZodError } from 'zod';
+import { ValidationError } from './errors.js';
+
+/**
+ * Validate tool arguments against a Zod schema.
+ * Throws ValidationError with field-level detail on failure.
+ *
+ * @param schema - Zod schema to validate against.
+ * @param args - Raw arguments from MCP tool call.
+ * @param toolName - Tool name for error context.
+ * @returns Parsed and typed arguments.
+ */
+export function validateArgs<T extends z.ZodType>(
+  schema: T,
+  args: unknown,
+  toolName: string,
+): z.infer<T> {
+  try {
+    return schema.parse(args ?? {});
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const messages = error.errors
+        .map((e) => `${e.path.join('.') || '(root)'}: ${e.message}`)
+        .join('; ');
+      throw new ValidationError(toolName, messages);
+    }
+    throw new ValidationError(toolName, String(error));
+  }
+}
+
+/**
+ * Validate and sanitize a string input.
+ * Strips null bytes, normalizes Unicode, trims whitespace.
+ */
+export function sanitizeString(input: unknown, maxLength: number = 4000): string {
+  if (typeof input !== 'string') return '';
+  return input
+    .replace(/\u0000/g, '')          // Strip null bytes
+    .normalize('NFKC')                // Unicode normalization
+    .trim()
+    .slice(0, maxLength);
+}
+
+/**
+ * Validate that a base64 string is well-formed and within size limits.
+ */
+export function validateBase64(input: unknown, maxBytes: number = 10 * 1024 * 1024): { valid: true; buffer: Buffer } | { valid: false; error: string } {
+  if (typeof input !== 'string') {
+    return { valid: false, error: 'Input must be a base64-encoded string' };
+  }
+
+  // Estimate decoded size: base64 is ~4/3 of original
+  if (input.length > maxBytes * 1.4) {
+    return { valid: false, error: `Base64 input exceeds maximum size of ${Math.round(maxBytes / 1024 / 1024)} MB` };
+  }
+
+  try {
+    const buffer = Buffer.from(input, 'base64');
+    if (buffer.length > maxBytes) {
+      return { valid: false, error: `Decoded data exceeds maximum size of ${Math.round(maxBytes / 1024 / 1024)} MB` };
+    }
+    if (buffer.length === 0 && input.length > 0) {
+      return { valid: false, error: 'Invalid base64 encoding' };
+    }
+    return { valid: true, buffer };
+  } catch {
+    return { valid: false, error: 'Invalid base64 encoding' };
+  }
+}
+
+/**
+ * Clamp an integer value within [min, max], with a fallback for NaN.
+ */
+export function clampInt(raw: unknown, fallback: number, min: number, max: number): number {
+  const n = Number(raw ?? fallback);
+  if (Number.isNaN(n)) return fallback;
+  return Math.min(Math.max(Math.floor(n), min), max);
+}
+
+// ── Common reusable Zod schemas ──────────────────────────────────────
+
+/** Positive integer with bounds. */
+export const intSchema = (min: number, max: number, fallback: number) =>
+  z.coerce.number().int().min(min).max(max).default(fallback);
+
+/** Non-empty string with max length. */
+export const stringSchema = (maxLength: number = 4000) =>
+  z.string().min(1).max(maxLength).transform((s) => sanitizeString(s, maxLength));
+
+/** Language locale enum. */
+export const localeSchema = z.enum(['en', 'fr']);
+
+/** Base64-encoded data. */
+export const base64Schema = z.string().min(1);

package/packages/core/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "__tests__"]
+}

package/packages/deeppipe/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@unified-mcp/deeppipe",
+  "version": "0.1.0",
+  "description": "DeepPipe integration for unified MCP server — document ingestion, full-text search, and RAG chat via @kordabjinan/deeppipe",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@unified-mcp/core": "^0.1.0",
+    "@kordabjinan/deeppipe": "^0.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  }
+}