@vantageos/vantage-crm-mcp 0.1.0

package/dist/mcp-server/lib/scopeEnforcement.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * VantageCRM MCP Server — Scope Enforcement
+ *
+ * 4-tier scope hierarchy:
+ *   read          — list/get queries (any authenticated token)
+ *   write         — create/update/delete mutations
+ *   admin         — admin-only operations (audit log, purge, RBAC mutations)
+ *   cloud-admin   — cross-workspace operations (multi-tenant platform admin)
+ *
+ * Stdio mode: full local access, no scope filtering (trust local user).
+ * HTTP mode:  scopes extracted from Bearer token → filter + reject on mismatch.
+ *
+ * Ref: elpi-corp/analysis/vantage-crm-spec-2026-05-20.md §3
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeError = void 0;
+exports.hasScope = hasScope;
+exports.requireScope = requireScope;
+exports.filterToolsByScope = filterToolsByScope;
+/** Ordered scope hierarchy for inheritance checks */
+const SCOPE_LEVEL = {
+    'read': 1,
+    'write': 2,
+    'workflow-trigger': 2, // same level as write, different domain
+    'admin': 3,
+    'cloud-admin': 4,
+};
+/**
+ * Check if the token's scopes satisfy the required scope.
+ * cloud-admin satisfies all scopes (superscope).
+ * admin satisfies read + write.
+ * write satisfies read.
+ */
+function hasScope(tokenScopes, required) {
+    if (tokenScopes.includes('cloud-admin'))
+        return true;
+    if (tokenScopes.includes(required))
+        return true;
+    // admin implies read + write
+    if (tokenScopes.includes('admin')) {
+        if (required === 'read' || required === 'write')
+            return true;
+    }
+    // write implies read
+    if (tokenScopes.includes('write') && required === 'read')
+        return true;
+    return false;
+}
+/**
+ * Require a scope — throws ScopeError if not satisfied.
+ * Used in HTTP mode before every tool handler.
+ */
+function requireScope(tokenScopes, required, toolName) {
+    if (!hasScope(tokenScopes, required)) {
+        throw new ScopeError(`Tool '${toolName}' requires scope '${required}'. Token has: [${tokenScopes.join(', ')}]`, required, tokenScopes);
+    }
+}
+class ScopeError extends Error {
+    required;
+    provided;
+    constructor(message, required, provided) {
+        super(message);
+        this.name = 'ScopeError';
+        this.required = required;
+        this.provided = provided;
+    }
+}
+exports.ScopeError = ScopeError;
+/**
+ * Filter a tool list to only include tools satisfying the given token scopes.
+ * Used in HTTP mode to build the visible tool list per token.
+ */
+function filterToolsByScope(tools, tokenScopes) {
+    return tools.filter((tool) => hasScope(tokenScopes, tool.requiredScope));
+}

package/dist/mcp-server/registry.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * VantageCRM MCP — Central Tool Registry
+ *
+ * Aggregates all 60 tools from 10 categories.
+ * Each tool: name, description, requiredScope, inputSchema, handler.
+ *
+ * Tool count: 8 + 6 + 8 + 5 + 5 + 7 + 7 + 4 + 5 + 5 = 60
+ *
+ * Ref: elpi-corp/analysis/vantage-crm-spec-2026-05-20.md §3.12
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_HANDLERS = exports.ALL_TOOL_DEFINITIONS = void 0;
+const contacts_1 = require("./tools/contacts");
+const companies_1 = require("./tools/companies");
+const deals_1 = require("./tools/deals");
+const activities_1 = require("./tools/activities");
+const customFields_1 = require("./tools/customFields");
+const customObjects_1 = require("./tools/customObjects");
+const workflows_1 = require("./tools/workflows");
+const search_1 = require("./tools/search");
+const admin_1 = require("./tools/admin");
+const rbac_1 = require("./tools/rbac");
+/** All tool definitions for MCP registration */
+exports.ALL_TOOL_DEFINITIONS = [
+    ...contacts_1.CONTACT_TOOLS, // 8
+    ...companies_1.COMPANY_TOOLS, // 6
+    ...deals_1.DEAL_TOOLS, // 8
+    ...activities_1.ACTIVITY_TOOLS, // 5
+    ...customFields_1.CUSTOM_FIELD_TOOLS, // 5
+    ...customObjects_1.CUSTOM_OBJECT_TOOLS, // 7
+    ...workflows_1.WORKFLOW_TOOLS, // 7
+    ...search_1.SEARCH_TOOLS, // 4
+    ...admin_1.ADMIN_TOOLS, // 5
+    ...rbac_1.RBAC_TOOLS, // 5
+    // TOTAL: 60
+];
+exports.TOOL_HANDLERS = {
+    // Contacts (8)
+    create_contact: contacts_1.create_contact,
+    get_contact: contacts_1.get_contact,
+    update_contact: contacts_1.update_contact,
+    list_contacts: contacts_1.list_contacts,
+    search_contacts: contacts_1.search_contacts,
+    delete_contact: contacts_1.delete_contact,
+    list_contacts_by_custom_field: contacts_1.list_contacts_by_custom_field,
+    restore_contact: contacts_1.restore_contact,
+    // Companies (6)
+    create_company: companies_1.create_company,
+    get_company: companies_1.get_company,
+    update_company: companies_1.update_company,
+    list_companies: companies_1.list_companies,
+    search_companies: companies_1.search_companies,
+    delete_company: companies_1.delete_company,
+    // Deals (8)
+    create_deal: deals_1.create_deal,
+    get_deal: deals_1.get_deal,
+    update_deal: deals_1.update_deal,
+    list_deals: deals_1.list_deals,
+    search_deals: deals_1.search_deals,
+    delete_deal: deals_1.delete_deal,
+    move_deal_stage: deals_1.move_deal_stage,
+    forecast_pipeline: deals_1.forecast_pipeline,
+    // Activities (5)
+    create_activity: activities_1.create_activity,
+    get_activity: activities_1.get_activity,
+    update_activity: activities_1.update_activity,
+    list_activities: activities_1.list_activities,
+    list_activities_by_type: activities_1.list_activities_by_type,
+    // Custom Fields (5)
+    add_custom_field: customFields_1.add_custom_field,
+    update_custom_field_definition: customFields_1.update_custom_field_definition,
+    list_custom_fields: customFields_1.list_custom_fields,
+    set_custom_field_value: customFields_1.set_custom_field_value,
+    delete_custom_field: customFields_1.delete_custom_field,
+    // Custom Objects (7)
+    add_custom_object: customObjects_1.add_custom_object,
+    list_custom_objects: customObjects_1.list_custom_objects,
+    create_record: customObjects_1.create_record,
+    update_record: customObjects_1.update_record,
+    delete_record: customObjects_1.delete_record,
+    list_records: customObjects_1.list_records,
+    search_records: customObjects_1.search_records,
+    // Workflows (7)
+    create_workflow: workflows_1.create_workflow,
+    update_workflow: workflows_1.update_workflow,
+    list_workflows: workflows_1.list_workflows,
+    pause_workflow: workflows_1.pause_workflow,
+    resume_workflow: workflows_1.resume_workflow,
+    list_executions: workflows_1.list_executions,
+    replay_execution: workflows_1.replay_execution,
+    // Search / Analytics (4)
+    pipeline_value: search_1.pipeline_value,
+    win_rate: search_1.win_rate,
+    conversion_rate: search_1.conversion_rate,
+    activity_summary: search_1.activity_summary,
+    // Admin (5)
+    list_audit_log: admin_1.list_audit_log,
+    get_entity_history: admin_1.get_entity_history,
+    get_actor_history: admin_1.get_actor_history,
+    purge_archived_records: admin_1.purge_archived_records,
+    list_workspace_limits: admin_1.list_workspace_limits,
+    // RBAC (5)
+    list_workspace_members: rbac_1.list_workspace_members,
+    add_workspace_member: rbac_1.add_workspace_member,
+    update_member_role: rbac_1.update_member_role,
+    remove_workspace_member: rbac_1.remove_workspace_member,
+    update_member_permissions: rbac_1.update_member_permissions,
+};
+/** Validate handler count matches definition count at module load */
+const handlerCount = Object.keys(exports.TOOL_HANDLERS).length;
+const definitionCount = exports.ALL_TOOL_DEFINITIONS.length;
+if (handlerCount !== definitionCount) {
+    throw new Error(`Registry mismatch: ${handlerCount} handlers vs ${definitionCount} definitions. ` +
+        `Check mcp-server/registry.ts.`);
+}

package/dist/mcp-server/server.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * VantageCRM MCP Server — Entry Point
+ *
+ * Mode detection (stdio vs HTTP):
+ *   1. CLI flag: --mode stdio | --mode http
+ *   2. Env var: VANTAGE_MCP_MODE=stdio | VANTAGE_MCP_MODE=http
+ *   3. Default: stdio (safe for local/self-host)
+ *
+ * Required env:
+ *   CONVEX_URL — Convex deployment URL (all modes)
+ *
+ * Optional env (HTTP mode only):
+ *   PORT — HTTP port (default 3001)
+ *
+ * Usage examples:
+ *   stdio: npx ts-node mcp-server/server.ts --mode stdio
+ *   HTTP:  VANTAGE_MCP_MODE=http PORT=3001 npx ts-node mcp-server/server.ts
+ *
+ * Ref: elpi-corp/analysis/vantage-crm-spec-2026-05-20.md §3.1
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+function detectMode() {
+    // Check CLI args first
+    const modeArgIndex = process.argv.indexOf('--mode');
+    if (modeArgIndex !== -1) {
+        const modeValue = process.argv[modeArgIndex + 1];
+        if (modeValue === 'http')
+            return 'http';
+        if (modeValue === 'stdio')
+            return 'stdio';
+    }
+    // Check env var
+    const envMode = process.env.VANTAGE_MCP_MODE?.toLowerCase();
+    if (envMode === 'http')
+        return 'http';
+    if (envMode === 'stdio')
+        return 'stdio';
+    // Default: stdio (safest for self-host)
+    return 'stdio';
+}
+async function main() {
+    const mode = detectMode();
+    // Validate CONVEX_URL is set (required in both modes)
+    if (!process.env.CONVEX_URL) {
+        process.stderr.write('[VantageCRM MCP] ERROR: CONVEX_URL environment variable is not set.\n' +
+            '  Set it to your Convex deployment URL: https://your-deployment.convex.cloud\n');
+        process.exit(1);
+    }
+    process.stderr.write(`[VantageCRM MCP] Starting in ${mode} mode...\n`);
+    if (mode === 'stdio') {
+        const { startStdioServer } = await Promise.resolve().then(() => __importStar(require('./transport/stdio')));
+        await startStdioServer();
+    }
+    else {
+        const { startHttpServer } = await Promise.resolve().then(() => __importStar(require('./transport/http')));
+        await startHttpServer();
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[VantageCRM MCP] Fatal error: ${message}\n`);
+    process.exit(1);
+});

package/dist/mcp-server/tests/registry.test.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * MCP Server — Registry Tests
+ *
+ * Validates:
+ * - Exactly 60 tools are registered
+ * - Every tool has a handler
+ * - Every tool has required fields (name, description, requiredScope, inputSchema)
+ * - No duplicate tool names
+ * - All categories have correct counts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const registry_1 = require("../registry");
+(0, vitest_1.describe)('MCP Registry', () => {
+    (0, vitest_1.it)('has exactly 60 tools', () => {
+        (0, vitest_1.expect)(registry_1.ALL_TOOL_DEFINITIONS).toHaveLength(60);
+    });
+    (0, vitest_1.it)('has exactly 60 handlers', () => {
+        (0, vitest_1.expect)(Object.keys(registry_1.TOOL_HANDLERS)).toHaveLength(60);
+    });
+    (0, vitest_1.it)('every tool definition has a handler', () => {
+        const missing = registry_1.ALL_TOOL_DEFINITIONS.filter((def) => !registry_1.TOOL_HANDLERS[def.name]);
+        (0, vitest_1.expect)(missing.map((d) => d.name)).toEqual([]);
+    });
+    (0, vitest_1.it)('no duplicate tool names', () => {
+        const names = registry_1.ALL_TOOL_DEFINITIONS.map((d) => d.name);
+        const unique = new Set(names);
+        (0, vitest_1.expect)(unique.size).toBe(names.length);
+    });
+    (0, vitest_1.it)('every tool has required fields', () => {
+        for (const def of registry_1.ALL_TOOL_DEFINITIONS) {
+            (0, vitest_1.expect)(def.name, `Tool missing name`).toBeTruthy();
+            (0, vitest_1.expect)(def.description, `${def.name} missing description`).toBeTruthy();
+            (0, vitest_1.expect)(def.requiredScope, `${def.name} missing requiredScope`).toBeTruthy();
+            (0, vitest_1.expect)(def.inputSchema, `${def.name} missing inputSchema`).toBeTruthy();
+        }
+    });
+    (0, vitest_1.it)('all scope values are valid', () => {
+        const validScopes = new Set(['read', 'write', 'admin', 'cloud-admin', 'workflow-trigger']);
+        for (const def of registry_1.ALL_TOOL_DEFINITIONS) {
+            (0, vitest_1.expect)(validScopes.has(def.requiredScope), `${def.name} has invalid scope: ${def.requiredScope}`).toBe(true);
+        }
+    });
+    (0, vitest_1.describe)('category counts', () => {
+        const CONTACT_TOOLS = ['create_contact', 'get_contact', 'update_contact', 'list_contacts', 'search_contacts', 'delete_contact', 'list_contacts_by_custom_field', 'restore_contact'];
+        const COMPANY_TOOLS = ['create_company', 'get_company', 'update_company', 'list_companies', 'search_companies', 'delete_company'];
+        const DEAL_TOOLS = ['create_deal', 'get_deal', 'update_deal', 'list_deals', 'search_deals', 'delete_deal', 'move_deal_stage', 'forecast_pipeline'];
+        const ACTIVITY_TOOLS = ['create_activity', 'get_activity', 'update_activity', 'list_activities', 'list_activities_by_type'];
+        const CUSTOM_FIELD_TOOLS = ['add_custom_field', 'update_custom_field_definition', 'list_custom_fields', 'set_custom_field_value', 'delete_custom_field'];
+        const CUSTOM_OBJECT_TOOLS = ['add_custom_object', 'list_custom_objects', 'create_record', 'update_record', 'delete_record', 'list_records', 'search_records'];
+        const WORKFLOW_TOOLS = ['create_workflow', 'update_workflow', 'list_workflows', 'pause_workflow', 'resume_workflow', 'list_executions', 'replay_execution'];
+        const SEARCH_TOOLS = ['pipeline_value', 'win_rate', 'conversion_rate', 'activity_summary'];
+        const ADMIN_TOOLS = ['list_audit_log', 'get_entity_history', 'get_actor_history', 'purge_archived_records', 'list_workspace_limits'];
+        const RBAC_TOOLS = ['list_workspace_members', 'add_workspace_member', 'update_member_role', 'remove_workspace_member', 'update_member_permissions'];
+        const registeredNames = new Set(registry_1.ALL_TOOL_DEFINITIONS.map((d) => d.name));
+        (0, vitest_1.it)('contacts: 8 tools', () => {
+            for (const name of CONTACT_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(CONTACT_TOOLS).toHaveLength(8);
+        });
+        (0, vitest_1.it)('companies: 6 tools', () => {
+            for (const name of COMPANY_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(COMPANY_TOOLS).toHaveLength(6);
+        });
+        (0, vitest_1.it)('deals: 8 tools', () => {
+            for (const name of DEAL_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(DEAL_TOOLS).toHaveLength(8);
+        });
+        (0, vitest_1.it)('activities: 5 tools (no delete — OQ-4)', () => {
+            for (const name of ACTIVITY_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(ACTIVITY_TOOLS).toHaveLength(5);
+            (0, vitest_1.expect)(registeredNames.has('delete_activity')).toBe(false);
+        });
+        (0, vitest_1.it)('customFields: 5 tools', () => {
+            for (const name of CUSTOM_FIELD_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(CUSTOM_FIELD_TOOLS).toHaveLength(5);
+        });
+        (0, vitest_1.it)('customObjects: 7 tools', () => {
+            for (const name of CUSTOM_OBJECT_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(CUSTOM_OBJECT_TOOLS).toHaveLength(7);
+        });
+        (0, vitest_1.it)('workflows: 7 tools', () => {
+            for (const name of WORKFLOW_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(WORKFLOW_TOOLS).toHaveLength(7);
+        });
+        (0, vitest_1.it)('search/analytics: 4 tools', () => {
+            for (const name of SEARCH_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(SEARCH_TOOLS).toHaveLength(4);
+        });
+        (0, vitest_1.it)('admin: 5 tools (admin scope minimum)', () => {
+            for (const name of ADMIN_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(ADMIN_TOOLS).toHaveLength(5);
+            // Verify all admin tools require at minimum admin scope
+            for (const name of ADMIN_TOOLS) {
+                const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === name);
+                (0, vitest_1.expect)(def.requiredScope === 'admin' || def.requiredScope === 'cloud-admin', `${name} must require admin or cloud-admin scope`).toBe(true);
+            }
+        });
+        (0, vitest_1.it)('rbac: 5 tools', () => {
+            for (const name of RBAC_TOOLS) {
+                (0, vitest_1.expect)(registeredNames.has(name), `missing: ${name}`).toBe(true);
+            }
+            (0, vitest_1.expect)(RBAC_TOOLS).toHaveLength(5);
+        });
+    });
+    (0, vitest_1.describe)('scope integrity', () => {
+        (0, vitest_1.it)('all admin tools require admin+ scope', () => {
+            const adminToolNames = ['list_audit_log', 'get_entity_history', 'get_actor_history', 'purge_archived_records'];
+            for (const name of adminToolNames) {
+                const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === name);
+                (0, vitest_1.expect)(def.requiredScope).toBe('admin');
+            }
+        });
+        (0, vitest_1.it)('delete_custom_field requires admin scope', () => {
+            const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === 'delete_custom_field');
+            (0, vitest_1.expect)(def.requiredScope).toBe('admin');
+        });
+        (0, vitest_1.it)('add_custom_object requires admin scope (DDL)', () => {
+            const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === 'add_custom_object');
+            (0, vitest_1.expect)(def.requiredScope).toBe('admin');
+        });
+        (0, vitest_1.it)('replay_execution requires workflow-trigger scope', () => {
+            const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === 'replay_execution');
+            (0, vitest_1.expect)(def.requiredScope).toBe('workflow-trigger');
+        });
+        (0, vitest_1.it)('all list/get tools require only read scope', () => {
+            const readOnlyTools = ['get_contact', 'list_contacts', 'get_company', 'list_companies',
+                'get_deal', 'list_deals', 'get_activity', 'list_activities',
+                'list_custom_fields', 'list_custom_objects', 'list_records',
+                'list_workflows', 'list_executions', 'pipeline_value', 'win_rate',
+                'conversion_rate', 'activity_summary', 'list_workspace_members'];
+            for (const name of readOnlyTools) {
+                const def = registry_1.ALL_TOOL_DEFINITIONS.find((d) => d.name === name);
+                (0, vitest_1.expect)(def?.requiredScope, `${name} should be read scope`).toBe('read');
+            }
+        });
+    });
+    (0, vitest_1.describe)('handler validation', () => {
+        (0, vitest_1.it)('all handlers are functions', () => {
+            for (const [name, handler] of Object.entries(registry_1.TOOL_HANDLERS)) {
+                (0, vitest_1.expect)(typeof handler, `handler for ${name} is not a function`).toBe('function');
+            }
+        });
+    });
+});

package/dist/mcp-server/tests/scopeEnforcement.test.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * MCP Server — Scope Enforcement Tests
+ *
+ * Tests the 4-tier scope hierarchy:
+ *   read < write < admin < cloud-admin
+ *
+ * Validates: read token → write tool rejected
+ *            write token → admin tool rejected
+ *            admin token → read/write tools pass
+ *            cloud-admin → all tools pass
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const scopeEnforcement_1 = require("../lib/scopeEnforcement");
+// ---------------------------------------------------------------------------
+// hasScope
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('hasScope', () => {
+    (0, vitest_1.it)('read token satisfies read', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['read'], 'read')).toBe(true);
+    });
+    (0, vitest_1.it)('read token does NOT satisfy write', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['read'], 'write')).toBe(false);
+    });
+    (0, vitest_1.it)('read token does NOT satisfy admin', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['read'], 'admin')).toBe(false);
+    });
+    (0, vitest_1.it)('write token satisfies read (inheritance)', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['write'], 'read')).toBe(true);
+    });
+    (0, vitest_1.it)('write token satisfies write', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['write'], 'write')).toBe(true);
+    });
+    (0, vitest_1.it)('write token does NOT satisfy admin', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['write'], 'admin')).toBe(false);
+    });
+    (0, vitest_1.it)('admin token satisfies read (inheritance)', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['admin'], 'read')).toBe(true);
+    });
+    (0, vitest_1.it)('admin token satisfies write (inheritance)', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['admin'], 'write')).toBe(true);
+    });
+    (0, vitest_1.it)('admin token satisfies admin', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['admin'], 'admin')).toBe(true);
+    });
+    (0, vitest_1.it)('admin token does NOT satisfy cloud-admin', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['admin'], 'cloud-admin')).toBe(false);
+    });
+    (0, vitest_1.it)('cloud-admin satisfies ALL scopes', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['cloud-admin'], 'read')).toBe(true);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['cloud-admin'], 'write')).toBe(true);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['cloud-admin'], 'admin')).toBe(true);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['cloud-admin'], 'cloud-admin')).toBe(true);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['cloud-admin'], 'workflow-trigger')).toBe(true);
+    });
+    (0, vitest_1.it)('empty scopes satisfy nothing', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)([], 'read')).toBe(false);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)([], 'write')).toBe(false);
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)([], 'admin')).toBe(false);
+    });
+    (0, vitest_1.it)('multiple scopes: [read, write] satisfies write', () => {
+        (0, vitest_1.expect)((0, scopeEnforcement_1.hasScope)(['read', 'write'], 'write')).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// requireScope
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('requireScope', () => {
+    (0, vitest_1.it)('passes when scope is satisfied', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['write'], 'write', 'test_tool')).not.toThrow();
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['write'], 'read', 'test_tool')).not.toThrow();
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['admin'], 'write', 'test_tool')).not.toThrow();
+    });
+    (0, vitest_1.it)('throws ScopeError when scope is insufficient', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['read'], 'write', 'create_contact')).toThrow(scopeEnforcement_1.ScopeError);
+    });
+    (0, vitest_1.it)('ScopeError contains required scope and provided scopes', () => {
+        try {
+            (0, scopeEnforcement_1.requireScope)(['read'], 'admin', 'purge_records');
+            vitest_1.expect.fail('should have thrown');
+        }
+        catch (err) {
+            (0, vitest_1.expect)(err).toBeInstanceOf(scopeEnforcement_1.ScopeError);
+            const scopeErr = err;
+            (0, vitest_1.expect)(scopeErr.required).toBe('admin');
+            (0, vitest_1.expect)(scopeErr.provided).toEqual(['read']);
+            (0, vitest_1.expect)(scopeErr.message).toContain('purge_records');
+        }
+    });
+    (0, vitest_1.it)('read token → write tool = rejected', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['read'], 'write', 'create_deal')).toThrow(scopeEnforcement_1.ScopeError);
+    });
+    (0, vitest_1.it)('write token → admin tool = rejected', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['write'], 'admin', 'list_audit_log')).toThrow(scopeEnforcement_1.ScopeError);
+    });
+    (0, vitest_1.it)('admin token → all non-cloud-admin tools = pass', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['admin'], 'read', 'list_contacts')).not.toThrow();
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['admin'], 'write', 'create_contact')).not.toThrow();
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['admin'], 'admin', 'list_audit_log')).not.toThrow();
+    });
+    (0, vitest_1.it)('cloud-admin → all tools = pass', () => {
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['cloud-admin'], 'admin', 'purge_archived_records')).not.toThrow();
+        (0, vitest_1.expect)(() => (0, scopeEnforcement_1.requireScope)(['cloud-admin'], 'cloud-admin', 'any_tool')).not.toThrow();
+    });
+});
+// ---------------------------------------------------------------------------
+// filterToolsByScope
+// ---------------------------------------------------------------------------
+(0, vitest_1.describe)('filterToolsByScope', () => {
+    const tools = [
+        { name: 'get_contact', description: '', requiredScope: 'read', inputSchema: {} },
+        { name: 'create_contact', description: '', requiredScope: 'write', inputSchema: {} },
+        { name: 'list_audit_log', description: '', requiredScope: 'admin', inputSchema: {} },
+        { name: 'cross_workspace_op', description: '', requiredScope: 'cloud-admin', inputSchema: {} },
+    ];
+    (0, vitest_1.it)('read token sees only read tools', () => {
+        const visible = (0, scopeEnforcement_1.filterToolsByScope)(tools, ['read']);
+        (0, vitest_1.expect)(visible.map((t) => t.name)).toEqual(['get_contact']);
+    });
+    (0, vitest_1.it)('write token sees read + write tools', () => {
+        const visible = (0, scopeEnforcement_1.filterToolsByScope)(tools, ['write']);
+        (0, vitest_1.expect)(visible.map((t) => t.name)).toEqual(['get_contact', 'create_contact']);
+    });
+    (0, vitest_1.it)('admin token sees read + write + admin tools', () => {
+        const visible = (0, scopeEnforcement_1.filterToolsByScope)(tools, ['admin']);
+        (0, vitest_1.expect)(visible.map((t) => t.name)).toEqual(['get_contact', 'create_contact', 'list_audit_log']);
+    });
+    (0, vitest_1.it)('cloud-admin sees all tools', () => {
+        const visible = (0, scopeEnforcement_1.filterToolsByScope)(tools, ['cloud-admin']);
+        (0, vitest_1.expect)(visible).toHaveLength(4);
+    });
+    (0, vitest_1.it)('empty scopes see nothing', () => {
+        const visible = (0, scopeEnforcement_1.filterToolsByScope)(tools, []);
+        (0, vitest_1.expect)(visible).toHaveLength(0);
+    });
+});