mcp-gov 1.0.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mcp-gov",
+  "version": "1.0.0",
+  "description": "MCP Governance System - Permission control and audit logging for Model Context Protocol servers",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "mcp-gov-proxy": "bin/mcp-gov-proxy.js",
+    "mcp-gov-wrap": "bin/mcp-gov-wrap.js",
+    "mcp-gov-unwrap": "bin/mcp-gov-unwrap.js"
+  },
+  "scripts": {
+    "example:github": "node examples/github/server.js",
+    "test": "node test/proxy.test.js && node test/wrapper.test.js && node test/unwrap.test.js && node test/platform.test.js && node test/integration.test.js && node test/multi-service.test.js && node test/performance.test.js && node test/service-param.test.js",
+    "test:all": "npm test",
+    "test:proxy": "node test/proxy.test.js",
+    "test:wrapper": "node test/wrapper.test.js",
+    "test:unwrap": "node test/unwrap.test.js",
+    "test:platform": "node test/platform.test.js",
+    "test:integration": "node test/integration.test.js",
+    "test:multi-service": "node test/multi-service.test.js",
+    "test:performance": "node test/performance.test.js",
+    "test:service-param": "node test/service-param.test.js",
+    "postinstall": "node postinstall.js",
+    "publish:npm": "./scripts/publish.sh"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "postinstall.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amrhas82/mcp-gov.git"
+  },
+  "keywords": [
+    "mcp",
+    "governance",
+    "permissions",
+    "audit"
+  ],
+  "author": "amrhas82",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "axios": "^1.6.0",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10"
+  }
+}

package/postinstall.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+const colors = {
+  bright: '\x1b[1m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m'
+};
+
+console.log('');
+console.log(`${colors.green}==========================================`);
+console.log(`  mcp-gov installed successfully`);
+console.log(`==========================================${colors.reset}`);
+console.log('');
+console.log(`${colors.bright}${colors.yellow}Quick Start:${colors.reset}`);
+console.log('');
+console.log(`  ${colors.cyan}mcp-gov-wrap${colors.reset}    Add governance to claude_desktop_config.json`);
+console.log(`  ${colors.cyan}mcp-gov-unwrap${colors.reset}  Remove governance`);
+console.log('');
+console.log(`${colors.bright}Docs:${colors.reset} https://github.com/amrhas82/mcp-gov`);
+console.log('');
+console.log(`${colors.green}==========================================${colors.reset}`);
+console.log('');

package/src/index.js

@@ -0,0 +1,199 @@
+/**
+ * GovernedMCPServer - MCP Server with permission control and audit logging.
+ * Middleware wrapper that intercepts tool registration to inject governance.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { parseToolName } from './operation-detector.js';
+
+/**
+ * @typedef {Object} ServerConfig
+ * @property {string} name - Server name
+ * @property {string} version - Server version
+ */
+
+/**
+ * @typedef {Object.<string, Object.<string, 'allow'|'deny'>>} PermissionRules
+ */
+
+/**
+ * @typedef {Object} ToolDefinition
+ * @property {string} name - Tool name
+ * @property {string} description - Tool description
+ * @property {Object} inputSchema - JSON Schema for input
+ */
+
+/**
+ * @typedef {function(any): Promise<Object>} ToolHandler
+ */
+
+/**
+ * MCP Server with governance layer for permission control and audit logging.
+ */
+export class GovernedMCPServer {
+  /**
+   * @param {ServerConfig} config - Server configuration {name, version}
+   * @param {PermissionRules} rules - Permission rules {serviceName: {operation: 'allow'|'deny'}}
+   */
+  constructor(config, rules = {}) {
+    this.config = config;
+    this.rules = rules;
+    this.tools = new Map(); // Store tool definitions and handlers
+    this.server = new Server(
+      {
+        name: config.name,
+        version: config.version
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+
+    // Set up tool handlers
+    this._setupHandlers();
+  }
+
+  /**
+   * Set up MCP protocol handlers for listing and calling tools.
+   * @private
+   */
+  _setupHandlers() {
+    // Handle tools/list request
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: Array.from(this.tools.values()).map(t => ({
+          name: t.definition.name,
+          description: t.definition.description,
+          inputSchema: t.definition.inputSchema
+        }))
+      };
+    });
+
+    // Handle tools/call request
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const toolName = request.params.name;
+      const args = request.params.arguments || {};
+
+      const tool = this.tools.get(toolName);
+      if (!tool) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Unknown tool: ${toolName}`
+            }
+          ],
+          isError: true
+        };
+      }
+
+      // Check permission
+      const allowed = this.checkPermission(toolName);
+
+      if (!allowed) {
+        this.logOperation(toolName, args, 'denied', 'Permission denied by governance rules');
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Permission denied: ${toolName} is not allowed by governance policy`
+            }
+          ],
+          isError: true
+        };
+      }
+
+      this.logOperation(toolName, args, 'allowed');
+
+      try {
+        const result = await tool.handler(args);
+        this.logOperation(toolName, args, 'success');
+        return result;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logOperation(toolName, args, 'error', errorMessage);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: ${errorMessage}`
+            }
+          ],
+          isError: true
+        };
+      }
+    });
+  }
+
+  /**
+   * Check if a tool operation is permitted by rules.
+   * @param {string} toolName - Tool name to check
+   * @returns {boolean} True if allowed, false if denied
+   */
+  checkPermission(toolName) {
+    const { service, operation } = parseToolName(toolName);
+
+    // Check if service has rules
+    if (!this.rules[service]) {
+      // Default to 'allow' if no rule exists (permissive for POC)
+      return true;
+    }
+
+    // Check operation permission
+    const permission = this.rules[service][operation];
+    if (permission === 'deny') {
+      return false;
+    }
+
+    // Default to allow
+    return true;
+  }
+
+  /**
+   * Log operation to stderr as structured JSON.
+   * @param {string} tool - Tool name
+   * @param {Object|string} args - Arguments (will be truncated to 200 chars)
+   * @param {string} status - Status: 'allowed', 'denied', 'success', 'error'
+   * @param {string} detail - Optional detail message
+   */
+  logOperation(tool, args, status, detail = '') {
+    const argsStr = typeof args === 'string' ? args : JSON.stringify(args);
+    const truncatedArgs = argsStr.length > 200 ? argsStr.substring(0, 200) + '...' : argsStr;
+
+    const logEntry = {
+      timestamp: new Date().toISOString(),
+      tool,
+      args: truncatedArgs,
+      status,
+      detail
+    };
+
+    console.error(JSON.stringify(logEntry));
+  }
+
+  /**
+   * Register a tool with governance wrapper.
+   * @param {ToolDefinition} toolDef - Tool definition {name, description, inputSchema}
+   * @param {ToolHandler} handler - Async handler function
+   */
+  registerTool(toolDef, handler) {
+    this.tools.set(toolDef.name, {
+      definition: toolDef,
+      handler
+    });
+  }
+
+  /**
+   * Start the MCP server with stdio transport.
+   */
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('MCP Server started:', this.config.name, 'v' + this.config.version);
+  }
+}

package/src/operation-detector.js

@@ -0,0 +1,67 @@
+/**
+ * Operation detection logic for MCP tool names.
+ * Analyzes tool names to determine operation type (admin/delete/execute/write/read).
+ */
+
+import { OPERATION_KEYWORDS } from './operation-keywords.js';
+
+/**
+ * @typedef {'admin'|'delete'|'execute'|'write'|'read'} OperationType
+ */
+
+/**
+ * Extract service name from tool name prefix (e.g., "github_list_repos" → "github")
+ * @param {string} toolName - Full tool name
+ * @returns {string} Service name or "unknown"
+ */
+export function extractService(toolName) {
+  if (!toolName || typeof toolName !== 'string') {
+    return 'unknown';
+  }
+
+  // Split by underscore and take first segment as service name
+  const parts = toolName.split('_');
+  return parts.length > 1 ? parts[0] : 'unknown';
+}
+
+/**
+ * Detect operation type from tool name using priority-based keyword matching.
+ * Priority order: admin → delete → execute → write → read
+ * @param {string} toolName - Tool name to analyze
+ * @returns {OperationType} Operation type: 'admin', 'delete', 'execute', 'write', 'read', or 'write' (default)
+ */
+export function detectOperation(toolName) {
+  if (!toolName || typeof toolName !== 'string') {
+    return 'write'; // Conservative default
+  }
+
+  const lowerName = toolName.toLowerCase();
+
+  // Check keywords in priority order
+  /** @type {OperationType[]} */
+  const operationTypes = ['admin', 'delete', 'execute', 'write', 'read'];
+
+  for (const opType of operationTypes) {
+    const keywords = /** @type {Record<OperationType, string[]>} */ (OPERATION_KEYWORDS)[opType];
+    for (const keyword of keywords) {
+      if (lowerName.includes(keyword)) {
+        return opType;
+      }
+    }
+  }
+
+  // Default to 'write' if no match (conservative)
+  return 'write';
+}
+
+/**
+ * Parse tool name into service and operation components.
+ * @param {string} toolName - Full tool name
+ * @returns {{service: string, operation: OperationType}} Parsed components
+ */
+export function parseToolName(toolName) {
+  return {
+    service: extractService(toolName),
+    operation: detectOperation(toolName)
+  };
+}

package/src/operation-keywords.js

@@ -0,0 +1,75 @@
+/**
+ * Exhaustive keyword mappings for operation detection.
+ * Priority order: admin → delete → execute → write → read
+ */
+
+export const OPERATION_KEYWORDS = {
+  // ADMIN operations - highest priority (system control)
+  admin: [
+    'admin', 'superuser', 'root', 'sudo', 'elevate', 'privilege',
+    'grant', 'revoke', 'permission', 'role', 'access', 'policy',
+    'configure', 'config', 'setting', 'preference', 'setup',
+    'initialize', 'init', 'bootstrap', 'install', 'uninstall',
+    'enable', 'disable', 'activate', 'deactivate', 'toggle',
+    'migrate', 'migration', 'backup', 'restore', 'export', 'import',
+    'deploy', 'deployment', 'provision', 'manage', 'management'
+  ],
+
+  // DELETE operations - second priority (destructive)
+  delete: [
+    'delete', 'remove', 'destroy', 'erase', 'clear', 'purge',
+    'drop', 'truncate', 'unlink', 'discard', 'revoke', 'cancel',
+    'terminate', 'kill', 'stop', 'abort', 'close', 'shutdown',
+    'deactivate', 'disable', 'detach', 'disconnect', 'unpublish',
+    'archive', 'trash', 'clean', 'wipe', 'reset', 'revert'
+  ],
+
+  // EXECUTE operations - third priority (action/mutation)
+  execute: [
+    'execute', 'run', 'invoke', 'call', 'trigger', 'fire',
+    'launch', 'start', 'begin', 'process', 'perform', 'apply',
+    'send', 'submit', 'post', 'publish', 'deploy', 'release',
+    'build', 'compile', 'generate', 'compute', 'calculate',
+    'merge', 'rebase', 'commit', 'push', 'pull', 'sync',
+    'approve', 'reject', 'accept', 'decline', 'confirm',
+    'schedule', 'queue', 'enqueue', 'dispatch', 'broadcast',
+    'notify', 'alert', 'trigger', 'activate', 'deactivate',
+    'lock', 'unlock', 'freeze', 'unfreeze', 'suspend', 'resume'
+  ],
+
+  // WRITE operations - fourth priority (creation/modification)
+  write: [
+    'create', 'add', 'insert', 'new', 'make', 'build',
+    'write', 'save', 'store', 'persist', 'record',
+    'update', 'modify', 'edit', 'change', 'alter', 'set',
+    'put', 'patch', 'replace', 'overwrite', 'append',
+    'upload', 'push', 'commit', 'submit', 'publish',
+    'move', 'rename', 'copy', 'duplicate', 'clone',
+    'attach', 'link', 'associate', 'bind', 'connect',
+    'assign', 'allocate', 'register', 'enroll', 'subscribe',
+    'comment', 'reply', 'respond', 'post', 'share',
+    'transfer', 'migrate', 'convert', 'transform',
+    'fork', 'branch', 'tag', 'label', 'mark',
+    'star', 'favorite', 'like', 'follow', 'watch',
+    'open', 'reopen', 'draft', 'issue', 'pr', 'pull_request'
+  ],
+
+  // READ operations - lowest priority (safe/non-mutating)
+  read: [
+    'get', 'list', 'fetch', 'retrieve', 'query', 'find',
+    'search', 'lookup', 'check', 'verify', 'validate',
+    'read', 'view', 'show', 'display', 'print', 'render',
+    'describe', 'info', 'detail', 'summary', 'status',
+    'count', 'total', 'aggregate', 'stats', 'statistics',
+    'download', 'export', 'extract', 'parse', 'decode',
+    'inspect', 'audit', 'log', 'trace', 'monitor',
+    'compare', 'diff', 'match', 'filter', 'sort',
+    'scan', 'analyze', 'review', 'preview', 'browse',
+    'watch', 'observe', 'listen', 'subscribe', 'poll',
+    'test', 'ping', 'health', 'heartbeat', 'check'
+  ]
+};
+
+// Total keyword count for reference
+export const TOTAL_KEYWORDS = Object.values(OPERATION_KEYWORDS)
+  .reduce((sum, keywords) => sum + keywords.length, 0);