feat(mcpl): per-server tool allow/deny policy

Adds enabledTools/disabledTools to McplServerConfig — bare tool names
with `*` substring wildcards. Filtered both at tool-list time (model
never sees the tool) and at dispatch time (call rejected with a
tool-result error). The dual gate is deliberate: schema omission alone
doesn't stop a model from imitating a denied call it sees in its own
prior message history.

Deny wins over allow on overlap. Regex metacharacters in patterns are
escaped, so only `*` is special.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Anarchid

src/framework.ts

@@ -51,6 +51,7 @@ import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { safeSlice } from './safe-slice.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
+import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
 import { UsageTracker, type PersistedUsageState } from './usage/usage-tracker.js';
 import type { SessionUsageSnapshot, UsageUpdatedEvent } from './usage/types.js';
@@ -2111,6 +2112,13 @@ export class AgentFramework {
     }
     const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
     const toolName = call.name.slice(prefix.length + 2); // Strip prefix + '--'
+    if (!isToolAllowed(toolName, config)) {
+      return {
+        success: false,
+        error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+        isError: true,
+      };
+    }
     try {
       const result = await server.sendToolsCall(toolName, call.input as Record<string, unknown>);
       return {
@@ -2660,6 +2668,7 @@ export class AgentFramework {
       try {
         const result = await server.sendToolsList();
         for (const tool of result.tools) {
+          if (!isToolAllowed(tool.name, config)) continue;
           // MCP tool schemas are generic JSON Schema; cast to membrane's ToolDefinition format
           const schema = tool.inputSchema as import('./types/index.js').ToolDefinition['inputSchema'];
           tools.push({
@@ -2749,6 +2758,23 @@ export class AgentFramework {
       return;
     }
 
+    const config = this.mcplServerConfigs.get(serverId);
+    if (!isToolAllowed(toolName, config)) {
+      this.emitTrace({ type: 'tool:failed', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, error: 'denied by tool policy' });
+      this.pushEvent({
+        type: 'tool-result',
+        callId: call.id,
+        agentName,
+        moduleName: `mcpl:${serverId}`,
+        result: {
+          success: false,
+          error: `Tool '${call.name}' is not permitted by this server's tool policy.`,
+          isError: true,
+        },
+      });
+      return;
+    }
+
     this.emitTrace({ type: 'tool:started', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, input: call.input });
     const startTime = Date.now();
     const args = (call.input && typeof call.input === 'object') ? call.input as Record<string, unknown> : {};

src/mcpl/tool-policy.ts

@@ -0,0 +1,52 @@
+/**
+ * Tool allow/deny policy for MCPL servers.
+ *
+ * `enabledTools` and `disabledTools` on McplServerConfig hold bare tool names
+ * (no toolPrefix) with `*` substring wildcards. This module owns the predicate
+ * used at both tool-list time and dispatch time.
+ *
+ * Semantics:
+ *   - No fields set                 → all tools allowed.
+ *   - Only enabledTools set         → tool must match at least one pattern.
+ *   - Only disabledTools set        → tool must NOT match any pattern.
+ *   - Both set                      → must match enabledTools AND not match disabledTools.
+ *                                     (deny wins on overlap.)
+ */
+
+/**
+ * Compile a pattern with `*` substring wildcards into a regex.
+ * `*` matches any run of characters (including empty); other characters are literal.
+ */
+function compilePattern(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function anyMatch(patterns: string[], name: string): boolean {
+  for (const p of patterns) {
+    if (compilePattern(p).test(name)) return true;
+  }
+  return false;
+}
+
+export interface ToolPolicy {
+  enabledTools?: string[];
+  disabledTools?: string[];
+}
+
+/**
+ * Returns true if `bareToolName` (server-native name, no prefix) is allowed
+ * under the supplied policy.
+ */
+export function isToolAllowed(bareToolName: string, policy: ToolPolicy | undefined): boolean {
+  if (!policy) return true;
+  const { enabledTools, disabledTools } = policy;
+
+  if (disabledTools && disabledTools.length > 0 && anyMatch(disabledTools, bareToolName)) {
+    return false;
+  }
+  if (enabledTools && enabledTools.length > 0) {
+    return anyMatch(enabledTools, bareToolName);
+  }
+  return true;
+}

src/mcpl/types.ts

@@ -180,6 +180,24 @@ export interface McplServerConfig {
   /** Feature sets to explicitly disable on connect */
   disabledFeatureSets?: string[];
 
+  /**
+   * Tool allow-list (bare tool names as the server exports them, no toolPrefix).
+   * Supports `*` as a substring wildcard (e.g. `read_*`, `*_file`, `*`).
+   * If set, only tools matching at least one pattern are exposed.
+   * `disabledTools` takes precedence on conflict.
+   *
+   * Filter is applied in two places: at tool-list time (model never sees the
+   * tool) and at dispatch time (call rejected with a tool-result error, in
+   * case the model imitates a prior call from message history).
+   */
+  enabledTools?: string[];
+
+  /**
+   * Tool deny-list (bare tool names, same wildcard syntax as enabledTools).
+   * Wins over enabledTools on conflict.
+   */
+  disabledTools?: string[];
+
   /** Scope configurations per feature set */
   scopes?: Record<string, ScopeConfig>;
 

test/tool-policy.test.ts

@@ -0,0 +1,58 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { isToolAllowed } from '../src/mcpl/tool-policy.js';
+
+describe('isToolAllowed', () => {
+  it('allows everything when no policy is set', () => {
+    assert.strictEqual(isToolAllowed('upload_file', undefined), true);
+    assert.strictEqual(isToolAllowed('upload_file', {}), true);
+  });
+
+  it('allow-list: only listed tools pass', () => {
+    const policy = { enabledTools: ['list_files', 'read_file'] };
+    assert.strictEqual(isToolAllowed('list_files', policy), true);
+    assert.strictEqual(isToolAllowed('read_file', policy), true);
+    assert.strictEqual(isToolAllowed('upload_file', policy), false);
+  });
+
+  it('deny-list: listed tools blocked, rest allowed', () => {
+    const policy = { disabledTools: ['delete_file', 'rename'] };
+    assert.strictEqual(isToolAllowed('delete_file', policy), false);
+    assert.strictEqual(isToolAllowed('rename', policy), false);
+    assert.strictEqual(isToolAllowed('read_file', policy), true);
+  });
+
+  it('deny wins over allow on overlap', () => {
+    const policy = { enabledTools: ['*'], disabledTools: ['upload_*'] };
+    assert.strictEqual(isToolAllowed('upload_file', policy), false);
+    assert.strictEqual(isToolAllowed('read_file', policy), true);
+  });
+
+  it('wildcards: prefix, suffix, and bare *', () => {
+    assert.strictEqual(isToolAllowed('read_file', { enabledTools: ['read_*'] }), true);
+    assert.strictEqual(isToolAllowed('write_file', { enabledTools: ['read_*'] }), false);
+    assert.strictEqual(isToolAllowed('read_file', { enabledTools: ['*_file'] }), true);
+    assert.strictEqual(isToolAllowed('read_dir', { enabledTools: ['*_file'] }), false);
+    assert.strictEqual(isToolAllowed('anything_at_all', { enabledTools: ['*'] }), true);
+  });
+
+  it('literal patterns require exact match (not substring)', () => {
+    const policy = { enabledTools: ['read'] };
+    assert.strictEqual(isToolAllowed('read', policy), true);
+    assert.strictEqual(isToolAllowed('read_file', policy), false);
+  });
+
+  it('regex metacharacters in patterns are treated literally', () => {
+    const policy = { enabledTools: ['get.file', 'foo+bar', 'baz(qux)'] };
+    assert.strictEqual(isToolAllowed('get.file', policy), true);
+    assert.strictEqual(isToolAllowed('getXfile', policy), false, '. is not a regex wildcard');
+    assert.strictEqual(isToolAllowed('foo+bar', policy), true);
+    assert.strictEqual(isToolAllowed('foobar', policy), false, '+ is not a regex quantifier');
+    assert.strictEqual(isToolAllowed('baz(qux)', policy), true);
+  });
+
+  it('empty arrays behave like absent fields', () => {
+    assert.strictEqual(isToolAllowed('anything', { enabledTools: [] }), true);
+    assert.strictEqual(isToolAllowed('anything', { disabledTools: [] }), true);
+  });
+});