mcp-warden 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vikrant Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# mcp-warden
+
+![NPM Version](https://img.shields.io/npm/v/mcp-warden)
+![License](https://img.shields.io/npm/l/mcp-warden)
+![Bundle Size](https://img.shields.io/bundlephobia/min/mcp-warden)
+
+High-performance security guardrails for MCP-compatible AI agents and tool execution.
+
+## Features
+
+- Policy-based tool authorization for MCP tool calls.
+- Prompt-injection scanning for high-risk control phrases.
+- Output redaction for email addresses, API keys, and IP addresses.
+- Built-in rate limiting and circuit-breaker protection.
+- CLI audit workflow for identifying over-permissioned MCP servers.
+
+## Table of Contents
+
+- [Why Security Matters for AI Agents](#why-security-matters-for-ai-agents)
+- [Quick Start](#quick-start)
+- [Policy Configuration](#policy-configuration)
+- [CLI Commands](#cli-commands)
+- [Development](#development)
+- [License](#license)
+- [Security Disclaimer](#security-disclaimer)
+
+## Why Security Matters for AI Agents
+
+AI agents can execute tools with real-world side effects: reading files, modifying systems, calling external APIs, and handling sensitive data. Without guardrails, a single prompt injection or over-permissioned server can lead to data leakage, privilege escalation, or runaway tool loops.
+
+mcp-warden helps enforce a security boundary before and after tool execution:
+- Blocks unauthorized tools using explicit policy rules.
+- Detects prompt-injection signatures in tool arguments.
+- Enforces rate limits to reduce abuse and runaway call storms.
+- Applies circuit-breaker protection for repeated tool failures.
+- Redacts sensitive output data before it reaches downstream systems.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install mcp-warden
+```
+
+### 2. Define a policy
+
+```json
+{
+  "allowedTools": ["list_dir", "read_file", "grep_search"],
+  "restrictedPaths": [
+    {
+      "path": "/",
+      "mode": "blocked"
+    }
+  ],
+  "maxCallsPerMinute": 60,
+  "approvalRequired": true
+}
+```
+
+### 3. Protect your transport handler
+
+```ts
+import { McpGuardian, type GuardianPolicy } from "mcp-warden";
+
+const policy: GuardianPolicy = {
+  allowedTools: ["read_file", /^search_/],
+  restrictedPaths: [{ path: "/", mode: "blocked" }],
+  maxCallsPerMinute: 60,
+  approvalRequired: true
+};
+
+const guardian = new McpGuardian(policy, { dryRun: false });
+
+const guardedHandler = guardian.wrapHandler(async (request) => {
+  // Your MCP transport execution logic
+  return {
+    jsonrpc: "2.0",
+    id: request.id ?? null,
+    result: { ok: true }
+  };
+});
+```
+
+### 4. Use the CLI
+
+```bash
+# Audit MCP client config files for excessive permissions
+npx mcp-warden audit ./claude_desktop_config.json
+
+# Generate a default policy file
+npx mcp-warden init
+```
+
+If you install globally, you can use the short command directly:
+
+```bash
+mcp-warden audit ./claude_desktop_config.json
+mcp-warden init
+```
+
+## Policy Configuration
+
+| Option | Type | Required | Description | Example |
+|---|---|---|---|---|
+| allowedTools | Array<string \| RegExp> | Yes | Allowed tool names or regex matchers for tools/call requests. | ["read_file", /^search_/] |
+| restrictedPaths | Array<{ path: string; mode: "read-only" \| "blocked" }> | Yes | Directory access constraints used by filesystem-aware middleware. | [{ "path": "/", "mode": "blocked" }] |
+| maxCallsPerMinute | number | Yes | Rolling 60-second budget for tool calls. Requests above this limit are denied. | 60 |
+| approvalRequired | boolean | Yes | Indicates destructive actions should require explicit approval in your orchestration flow. | true |
+
+## CLI Commands
+
+- npx mcp-warden audit <config-path>
+- npx mcp-warden init [--output <path>] [--force]
+
+CLI output uses color-coded alerts:
+- Green: SAFE
+- Red: CRITICAL
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+## License
+
+MIT
+
+## Security Disclaimer
+
+mcp-warden is a runtime governance layer designed to mitigate risks. It is not a replacement for OS-level permissions, network-level firewalls, or the principle of least privilege. Always run AI agents in isolated environments when possible.

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import chalk from "chalk";
+import { Command } from "commander";
+import { GuardianPolicySchema } from "../types/policy.js";
+/**
+ * Policy file created by `mcp-warden init`.
+ */
+const DEFAULT_POLICY = {
+    allowedTools: ["list_dir", "read_file", "grep_search"],
+    restrictedPaths: [
+        {
+            path: "/",
+            mode: "blocked"
+        }
+    ],
+    maxCallsPerMinute: 60,
+    approvalRequired: true
+};
+/**
+ * True if a value is a plain object.
+ */
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Converts unknown values to a string array.
+ */
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
+/**
+ * Best-effort extraction of MCP servers from common config layouts.
+ */
+function extractServers(config) {
+    if (!isRecord(config)) {
+        return [];
+    }
+    const candidates = [
+        config.mcpServers,
+        isRecord(config.mcp) ? config.mcp.servers : undefined,
+        config.servers
+    ];
+    for (const candidate of candidates) {
+        if (!isRecord(candidate)) {
+            continue;
+        }
+        return Object.entries(candidate)
+            .filter(([, server]) => isRecord(server))
+            .map(([name, server]) => ({
+            name,
+            config: server
+        }));
+    }
+    return [];
+}
+/**
+ * Returns true when a path represents broad filesystem access.
+ */
+function isBroadPath(value) {
+    const normalized = value.trim().toLowerCase();
+    return (normalized === "/" ||
+        normalized === "~" ||
+        normalized === "$home" ||
+        normalized === "${home}" ||
+        normalized === "c:\\" ||
+        normalized.startsWith("/users"));
+}
+/**
+ * Detects critical full-access permissions in a server config.
+ */
+function getCriticalFindings(server) {
+    const findings = [];
+    const permissions = toStringArray(server.permissions);
+    if (permissions.some((entry) => ["*", "all", "full-disk-access", "filesystem:*"].includes(entry.trim().toLowerCase()))) {
+        findings.push("Permission set grants full disk access.");
+    }
+    const roots = toStringArray(server.roots);
+    const allowedPaths = toStringArray(server.allowedPaths);
+    const broadPath = [...roots, ...allowedPaths].find((entry) => isBroadPath(entry));
+    if (broadPath) {
+        findings.push(`Broad filesystem path is allowed: ${broadPath}`);
+    }
+    const args = toStringArray(server.args).map((arg) => arg.toLowerCase());
+    if (args.some((arg) => [
+        "--allow-all",
+        "--dangerously-skip-permissions",
+        "--full-disk-access",
+        "--allow-read=/",
+        "--allow-write=/"
+    ].some((flag) => arg.includes(flag)))) {
+        findings.push("Command-line flags indicate unrestricted filesystem access.");
+    }
+    if (isRecord(server.env)) {
+        const envPairs = Object.entries(server.env);
+        const hasWideEnvAccess = envPairs.some(([key, rawValue]) => {
+            if (typeof rawValue !== "string") {
+                return false;
+            }
+            const envKey = key.toLowerCase();
+            const envValue = rawValue.trim().toLowerCase();
+            return (["full_disk_access", "allow_all", "dangerously_skip_permissions"].includes(envKey) &&
+                ["1", "true", "yes", "on"].includes(envValue));
+        });
+        if (hasWideEnvAccess) {
+            findings.push("Environment variables enable unrestricted permissions.");
+        }
+    }
+    return findings;
+}
+/**
+ * Reads and parses a JSON configuration file from disk.
+ */
+async function readJsonFile(filePath) {
+    const content = await fs.readFile(filePath, "utf8");
+    return JSON.parse(content);
+}
+/**
+ * Runs audit mode and prints color-coded findings.
+ */
+async function runAudit(configPath) {
+    const absolutePath = path.resolve(process.cwd(), configPath);
+    const config = await readJsonFile(absolutePath);
+    const servers = extractServers(config);
+    console.log(chalk.bold(`Audit file: ${absolutePath}`));
+    if (servers.length === 0) {
+        console.log(chalk.red("CRITICAL: No MCP servers found. Verify config structure before deployment."));
+        process.exitCode = 1;
+        return;
+    }
+    let criticalCount = 0;
+    for (const server of servers) {
+        const findings = getCriticalFindings(server.config);
+        if (findings.length === 0) {
+            console.log(chalk.green(`SAFE: ${server.name}`));
+            continue;
+        }
+        criticalCount += 1;
+        console.log(chalk.red(`CRITICAL: ${server.name}`));
+        for (const finding of findings) {
+            console.log(chalk.red(`  - ${finding}`));
+        }
+    }
+    if (criticalCount > 0) {
+        console.log(chalk.red(`\nCritical servers: ${criticalCount}/${servers.length}`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.green(`\nAll servers safe: ${servers.length}/${servers.length}`));
+}
+/**
+ * Creates a default guardian policy JSON file.
+ */
+async function runInit(outputPath, force) {
+    const absolutePath = path.resolve(process.cwd(), outputPath);
+    if (!force) {
+        try {
+            await fs.access(absolutePath);
+            console.log(chalk.red(`CRITICAL: ${outputPath} already exists. Use --force to overwrite.`));
+            process.exitCode = 1;
+            return;
+        }
+        catch {
+            // File does not exist and can be created.
+        }
+    }
+    const policy = GuardianPolicySchema.parse(DEFAULT_POLICY);
+    const serialized = `${JSON.stringify(policy, null, 2)}\n`;
+    await fs.writeFile(absolutePath, serialized, "utf8");
+    console.log(chalk.green(`SAFE: Created ${outputPath}`));
+}
+/**
+ * Boots the mcp-warden CLI.
+ */
+async function main() {
+    const program = new Command();
+    program
+        .name("mcp-warden")
+        .description("Security auditing and policy tooling for MCP servers")
+        .version("0.1.0");
+    program
+        .command("audit")
+        .description("Audit a claude_desktop_config.json or cursor-settings.json file")
+        .argument("<config-path>", "Path to a JSON config file")
+        .action(async (configPath) => {
+        await runAudit(configPath);
+    });
+    program
+        .command("init")
+        .description("Generate a default mcp-policy.json")
+        .option("-o, --output <path>", "Output path for generated policy", "mcp-policy.json")
+        .option("-f, --force", "Overwrite existing file")
+        .action(async (options) => {
+        await runInit(options.output, Boolean(options.force));
+    });
+    await program.parseAsync(process.argv);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown CLI error";
+    console.error(chalk.red(`CRITICAL: ${message}`));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n\nimport { promises as fs } from \"node:fs\";\nimport * as path from \"node:path\";\nimport chalk from \"chalk\";\nimport { Command } from \"commander\";\nimport { GuardianPolicySchema, type GuardianPolicy } from \"../types/policy.js\";\n\n/**\n * Minimal server configuration shape extracted from MCP client config files.\n */\ninterface McpServerConfig {\n  args?: unknown;\n  env?: unknown;\n  permissions?: unknown;\n  roots?: unknown;\n  allowedPaths?: unknown;\n  [key: string]: unknown;\n}\n\n/**\n * Named server entry used by the audit report.\n */\ninterface ServerEntry {\n  name: string;\n  config: McpServerConfig;\n}\n\n/**\n * Policy file created by `mcp-warden init`.\n */\nconst DEFAULT_POLICY: GuardianPolicy = {\n  allowedTools: [\"list_dir\", \"read_file\", \"grep_search\"],\n  restrictedPaths: [\n    {\n      path: \"/\",\n      mode: \"blocked\"\n    }\n  ],\n  maxCallsPerMinute: 60,\n  approvalRequired: true\n};\n\n/**\n * True if a value is a plain object.\n */\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === \"object\" && !Array.isArray(value);\n}\n\n/**\n * Converts unknown values to a string array.\n */\nfunction toStringArray(value: unknown): string[] {\n  if (!Array.isArray(value)) {\n    return [];\n  }\n\n  return value.filter((entry): entry is string => typeof entry === \"string\");\n}\n\n/**\n * Best-effort extraction of MCP servers from common config layouts.\n */\nfunction extractServers(config: unknown): ServerEntry[] {\n  if (!isRecord(config)) {\n    return [];\n  }\n\n  const candidates: unknown[] = [\n    config.mcpServers,\n    isRecord(config.mcp) ? config.mcp.servers : undefined,\n    config.servers\n  ];\n\n  for (const candidate of candidates) {\n    if (!isRecord(candidate)) {\n      continue;\n    }\n\n    return Object.entries(candidate)\n      .filter(([, server]) => isRecord(server))\n      .map(([name, server]) => ({\n        name,\n        config: server as McpServerConfig\n      }));\n  }\n\n  return [];\n}\n\n/**\n * Returns true when a path represents broad filesystem access.\n */\nfunction isBroadPath(value: string): boolean {\n  const normalized = value.trim().toLowerCase();\n  return (\n    normalized === \"/\" ||\n    normalized === \"~\" ||\n    normalized === \"$home\" ||\n    normalized === \"${home}\" ||\n    normalized === \"c:\\\\\" ||\n    normalized.startsWith(\"/users\")\n  );\n}\n\n/**\n * Detects critical full-access permissions in a server config.\n */\nfunction getCriticalFindings(server: McpServerConfig): string[] {\n  const findings: string[] = [];\n\n  const permissions = toStringArray(server.permissions);\n  if (\n    permissions.some((entry) =>\n      [\"*\", \"all\", \"full-disk-access\", \"filesystem:*\"].includes(entry.trim().toLowerCase())\n    )\n  ) {\n    findings.push(\"Permission set grants full disk access.\");\n  }\n\n  const roots = toStringArray(server.roots);\n  const allowedPaths = toStringArray(server.allowedPaths);\n  const broadPath = [...roots, ...allowedPaths].find((entry) => isBroadPath(entry));\n  if (broadPath) {\n    findings.push(`Broad filesystem path is allowed: ${broadPath}`);\n  }\n\n  const args = toStringArray(server.args).map((arg) => arg.toLowerCase());\n  if (\n    args.some((arg) =>\n      [\n        \"--allow-all\",\n        \"--dangerously-skip-permissions\",\n        \"--full-disk-access\",\n        \"--allow-read=/\",\n        \"--allow-write=/\"\n      ].some((flag) => arg.includes(flag))\n    )\n  ) {\n    findings.push(\"Command-line flags indicate unrestricted filesystem access.\");\n  }\n\n  if (isRecord(server.env)) {\n    const envPairs = Object.entries(server.env);\n    const hasWideEnvAccess = envPairs.some(([key, rawValue]) => {\n      if (typeof rawValue !== \"string\") {\n        return false;\n      }\n\n      const envKey = key.toLowerCase();\n      const envValue = rawValue.trim().toLowerCase();\n      return (\n        [\"full_disk_access\", \"allow_all\", \"dangerously_skip_permissions\"].includes(envKey) &&\n        [\"1\", \"true\", \"yes\", \"on\"].includes(envValue)\n      );\n    });\n\n    if (hasWideEnvAccess) {\n      findings.push(\"Environment variables enable unrestricted permissions.\");\n    }\n  }\n\n  return findings;\n}\n\n/**\n * Reads and parses a JSON configuration file from disk.\n */\nasync function readJsonFile(filePath: string): Promise<unknown> {\n  const content = await fs.readFile(filePath, \"utf8\");\n  return JSON.parse(content) as unknown;\n}\n\n/**\n * Runs audit mode and prints color-coded findings.\n */\nasync function runAudit(configPath: string): Promise<void> {\n  const absolutePath = path.resolve(process.cwd(), configPath);\n  const config = await readJsonFile(absolutePath);\n  const servers = extractServers(config);\n\n  console.log(chalk.bold(`Audit file: ${absolutePath}`));\n\n  if (servers.length === 0) {\n    console.log(chalk.red(\"CRITICAL: No MCP servers found. Verify config structure before deployment.\"));\n    process.exitCode = 1;\n    return;\n  }\n\n  let criticalCount = 0;\n\n  for (const server of servers) {\n    const findings = getCriticalFindings(server.config);\n    if (findings.length === 0) {\n      console.log(chalk.green(`SAFE: ${server.name}`));\n      continue;\n    }\n\n    criticalCount += 1;\n    console.log(chalk.red(`CRITICAL: ${server.name}`));\n    for (const finding of findings) {\n      console.log(chalk.red(`  - ${finding}`));\n    }\n  }\n\n  if (criticalCount > 0) {\n    console.log(chalk.red(`\\nCritical servers: ${criticalCount}/${servers.length}`));\n    process.exitCode = 1;\n    return;\n  }\n\n  console.log(chalk.green(`\\nAll servers safe: ${servers.length}/${servers.length}`));\n}\n\n/**\n * Creates a default guardian policy JSON file.\n */\nasync function runInit(outputPath: string, force: boolean): Promise<void> {\n  const absolutePath = path.resolve(process.cwd(), outputPath);\n\n  if (!force) {\n    try {\n      await fs.access(absolutePath);\n      console.log(chalk.red(`CRITICAL: ${outputPath} already exists. Use --force to overwrite.`));\n      process.exitCode = 1;\n      return;\n    } catch {\n      // File does not exist and can be created.\n    }\n  }\n\n  const policy = GuardianPolicySchema.parse(DEFAULT_POLICY);\n  const serialized = `${JSON.stringify(policy, null, 2)}\\n`;\n  await fs.writeFile(absolutePath, serialized, \"utf8\");\n\n  console.log(chalk.green(`SAFE: Created ${outputPath}`));\n}\n\n/**\n * Boots the mcp-warden CLI.\n */\nasync function main(): Promise<void> {\n  const program = new Command();\n\n  program\n    .name(\"mcp-warden\")\n    .description(\"Security auditing and policy tooling for MCP servers\")\n    .version(\"0.1.0\");\n\n  program\n    .command(\"audit\")\n    .description(\"Audit a claude_desktop_config.json or cursor-settings.json file\")\n    .argument(\"<config-path>\", \"Path to a JSON config file\")\n    .action(async (configPath: string) => {\n      await runAudit(configPath);\n    });\n\n  program\n    .command(\"init\")\n    .description(\"Generate a default mcp-policy.json\")\n    .option(\"-o, --output <path>\", \"Output path for generated policy\", \"mcp-policy.json\")\n    .option(\"-f, --force\", \"Overwrite existing file\")\n    .action(async (options: { output: string; force?: boolean }) => {\n      await runInit(options.output, Boolean(options.force));\n    });\n\n  await program.parseAsync(process.argv);\n}\n\nmain().catch((error: unknown) => {\n  const message = error instanceof Error ? error.message : \"Unknown CLI error\";\n  console.error(chalk.red(`CRITICAL: ${message}`));\n  process.exitCode = 1;\n});\n"]}

package/dist/core/interceptor.d.ts

@@ -0,0 +1,122 @@
+import { type GuardianPolicy } from "../types/policy.js";
+import { type CircuitBreakerOptions } from "../security/circuit-breaker.js";
+/**
+ * JSON-RPC request identifier shape.
+ */
+export type JsonRpcId = string | number | null;
+/**
+ * Minimal JSON-RPC 2.0 request payload used by MCP transports.
+ */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: JsonRpcId;
+    method: string;
+    params?: unknown;
+}
+/**
+ * Standardized JSON-RPC 2.0 error object.
+ */
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Standardized JSON-RPC 2.0 error response payload.
+ */
+export interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    error: JsonRpcError;
+}
+/**
+ * Security violation metadata emitted by the guardian engine.
+ */
+export interface GuardianViolation {
+    code: "PERMISSION_DENIED";
+    reason: string;
+    method: string;
+    toolName?: string;
+}
+/**
+ * Validation result produced by the guardian engine.
+ */
+export interface ValidationResult {
+    isAllowed: boolean;
+    error?: JsonRpcErrorResponse;
+    violation?: GuardianViolation;
+}
+/**
+ * Decision object returned by guardian middleware.
+ */
+export interface MiddlewareDecision {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * Execution context provided to each middleware stage.
+ */
+export interface GuardianContext {
+    readonly request: JsonRpcRequest;
+    readonly policy: GuardianPolicy;
+    readonly isDryRun: boolean;
+    readonly toolName?: string;
+    readonly toolArgs?: unknown;
+}
+/**
+ * Async middleware function signature used by the guardian engine.
+ */
+export type GuardianMiddleware = (context: GuardianContext, next: () => Promise<MiddlewareDecision>) => Promise<MiddlewareDecision>;
+/**
+ * Logging function for policy violations.
+ */
+export type GuardianLogger = (violation: GuardianViolation) => void;
+/**
+ * Configuration object for McpGuardian construction.
+ */
+export interface McpGuardianOptions {
+    dryRun?: boolean;
+    logger?: GuardianLogger;
+    injectionKeywords?: readonly string[];
+    circuitBreaker?: CircuitBreakerOptions;
+    redactToolOutputs?: boolean;
+    nowProvider?: () => number;
+}
+/**
+ * Core policy guard for intercepting JSON-RPC tool calls.
+ *
+ * This class can be used as a standalone validator (`validateRequest`) or as a
+ * transport wrapper through `wrapHandler` to gate downstream request handlers.
+ */
+export declare class McpGuardian {
+    private readonly policy;
+    private readonly isDryRun;
+    private readonly logger;
+    private readonly middlewares;
+    private readonly circuitBreaker;
+    private readonly injectionKeywords;
+    private readonly redactToolOutputs;
+    private readonly rateLimiter;
+    private readonly nowProvider;
+    /**
+     * Creates a guardian instance with policy and optional runtime controls.
+     */
+    constructor(policy: GuardianPolicy, options?: McpGuardianOptions);
+    /**
+     * Registers additional middleware checks that run after the built-in policy check.
+     */
+    use(middleware: GuardianMiddleware): this;
+    /**
+     * Validates an incoming JSON-RPC request against the configured guardrail chain.
+     */
+    validateRequest(request: JsonRpcRequest): Promise<ValidationResult>;
+    /**
+     * Wraps a JSON-RPC handler and blocks requests that violate policy.
+     */
+    wrapHandler<TResponse>(handler: (request: JsonRpcRequest) => Promise<TResponse | JsonRpcErrorResponse>): (request: JsonRpcRequest) => Promise<TResponse | JsonRpcErrorResponse>;
+    /**
+     * Runs middleware chain using a deterministic Koa-style composition model.
+     */
+    private runMiddlewares;
+}
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/core/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../../src/core/interceptor.ts"],"names":[],"mappings":"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"}