@raghulm/aegis-mcp 1.0.2 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raghul M
+
+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

@@ -6,22 +6,12 @@
   [![Python version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
   [![MCP Protocol](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io/)
   [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://www.docker.com/)
-  [![npm version](https://img.shields.io/npm/v/@raghulm/aegis-mcp.svg)](https://www.npmjs.com/package/@raghulm/aegis-mcp)
-  [![npm downloads](https://img.shields.io/npm/dt/@raghulm/aegis-mcp.svg)](https://www.npmjs.com/package/@raghulm/aegis-mcp)
 </div>
 
 ---
 
 **Aegis MCP Server** empowers AI assistants (like Claude, Cursor, and GitHub Copilot) to perform cloud architecture administration, security scanning, and network analyses directly from their execution environments. It wraps powerful underlying tools and SDKs into secure, audited MCP tool sets.
 
-### Quick Start
-
-```bash
-npx @raghulm/aegis-mcp
-```
-
-That's it! The installer will check Python, clone the repo, set up dependencies, and print your MCP config.
-
 ---
 
 ## 📸 Demo in Action
@@ -144,39 +134,14 @@ MEDIUM: 7
 
 ## 🚀 Getting Started
 
-### One-Command Install (NPX)
+### Prerequisites
+
+- **Python 3.12+**
+- **Node.js 18+** (only if you want to run via npm/npx)
+- **Semgrep** — `pip install semgrep` (for SAST scanning)
+- Optional: AWS CLI / `boto3`, `kubectl`, Trivy (for their respective tools)
 
-```bash
-npx @raghulm/aegis-mcp
-```
-
-That's it. Aegis will:
-1. ✅ Check your Python version (3.12+ required)
-2. 📥 Clone and install the server into `~/.aegis-mcp`
-3. 🖨️ Print your ready-to-paste MCP config
-4. 🚀 Start the server
-
-**Additional commands:**
-
-```bash
-npx @raghulm/aegis-mcp --install   # Force reinstall / update
-npx @raghulm/aegis-mcp --config    # Print MCP config JSON only
-npx @raghulm/aegis-mcp --help      # Show all options
-```
-
-> 💡 **Tip:** After running `npx @raghulm/aegis-mcp`, copy the printed MCP config into your AI agent's config file (Claude Desktop, Cursor, Windsurf, etc.)
-
----
-
-### Prerequisites
-
-- **Node.js 16+** (for NPX install)
-- **Python 3.12+**
-- **Git**
-- **Semgrep** — `pip install semgrep` (for SAST scanning)
-- Optional: AWS CLI / `boto3`, `kubectl`, Trivy (for their respective tools)
-
-### Manual Installation
+### Installation
 
 ```bash
 git clone https://github.com/raghulvj01/aegis-mcp.git
@@ -192,10 +157,20 @@ source .venv/bin/activate
 .venv\Scripts\activate
 
 # Install dependencies
-pip install -r requirements.txt
-```
-
----
+pip install -r requirements.txt
+```
+
+### Install via npm (Public Package)
+
+```bash
+npm install -g @raghulm/aegis-mcp
+# or run without installing globally:
+npx -y @raghulm/aegis-mcp
+```
+
+On first run, the npm wrapper creates a local Python virtual environment and installs dependencies from `requirements.txt` automatically.
+
+---
 
 ## 🤖 Usage with AI Agents
 
@@ -203,16 +178,16 @@ pip install -r requirements.txt
 
 Add to your MCP config (e.g., `mcp_config.json`):
 
-```json
-{
-  "mcpServers": {
-    "aegis": {
-      "command": "c:\\path\\to\\aegis-mcp\\.venv\\Scripts\\python.exe",
-      "args": ["c:\\path\\to\\aegis-mcp\\run_stdio.py"]
-    }
-  }
-}
-```
+```json
+{
+  "mcpServers": {
+    "aegis": {
+      "command": "npx",
+      "args": ["-y", "@raghulm/aegis-mcp"]
+    }
+  }
+}
+```
 
 > ✅ **All 12 tools work**, including Semgrep SAST.
 
@@ -222,16 +197,16 @@ Add to `claude_desktop_config.json`:
 - **Windows**: `%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude\`
 - **Mac**: `~/Library/Application Support/Claude/`
 
-```json
-{
-  "mcpServers": {
-    "aegis": {
-      "command": "c:\\path\\to\\aegis-mcp\\.venv\\Scripts\\python.exe",
-      "args": ["c:\\path\\to\\aegis-mcp\\run_stdio.py"]
-    }
-  }
-}
-```
+```json
+{
+  "mcpServers": {
+    "aegis": {
+      "command": "npx",
+      "args": ["-y", "@raghulm/aegis-mcp"]
+    }
+  }
+}
+```
 
 > ⚠️ **11 of 12 tools work.** Semgrep SAST does not work due to Windows pipe limitations.
 
@@ -326,17 +301,34 @@ The `@audit_tool_call` decorator emits structured JSON logs for every invocation
 
 ---
 
-## 🛣️ Roadmap
-
-- [ ] Terraform security scanner
-- [ ] IAM policy risk detection
-- [ ] Kubernetes misconfiguration scanner (Basic `k8s_security_audit` implemented!)
-- [ ] GitHub Actions security audit
-- [ ] Cloud cost analysis tools
-
----
-
-## 🤝 Contributing
+## 🛣️ Roadmap
+
+- [ ] Terraform security scanner
+- [ ] IAM policy risk detection
+- [ ] Kubernetes misconfiguration scanner (Basic `k8s_security_audit` implemented!)
+- [ ] GitHub Actions security audit
+- [ ] Cloud cost analysis tools
+
+---
+
+## 📦 Publish to npm
+
+```bash
+# 1) Login to npm
+npm login
+
+# 2) Verify package contents
+npm run pack:check
+
+# 3) Publish publicly
+npm publish --access public
+```
+
+For scoped packages like `@raghulm/aegis-mcp`, keep `--access public` in the publish command.
+
+---
+
+## 🤝 Contributing
 
 1. Fork the project
 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)

package/audit/audit_logger.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from functools import wraps
+from time import perf_counter
+from typing import Any, Callable
+
+from server.logging import get_logger
+
+logger = get_logger("mcp.aegis.audit")
+
+
+
+def audit_tool_call(tool_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator that emits structured audit records for every tool invocation."""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            started = perf_counter()
+            logger.info(
+                "tool_call_started",
+                extra={
+                    "extra_payload": {
+                        "event": "tool_call_started",
+                        "tool": tool_name,
+                        "args": str(args),
+                        "kwargs": kwargs,
+                    }
+                },
+            )
+            try:
+                result = func(*args, **kwargs)
+                duration_ms = int((perf_counter() - started) * 1000)
+                logger.info(
+                    "tool_call_succeeded",
+                    extra={
+                        "extra_payload": {
+                            "event": "tool_call_succeeded",
+                            "tool": tool_name,
+                            "duration_ms": duration_ms,
+                        }
+                    },
+                )
+                return result
+            except Exception as exc:  # noqa: BLE001
+                duration_ms = int((perf_counter() - started) * 1000)
+                logger.error(
+                    "tool_call_failed",
+                    extra={
+                        "extra_payload": {
+                            "event": "tool_call_failed",
+                            "tool": tool_name,
+                            "duration_ms": duration_ms,
+                            "error": str(exc),
+                        }
+                    },
+                )
+                raise
+
+        return wrapper
+
+    return decorator

package/bin/aegis-mcp.js

@@ -1,164 +1,44 @@
-#!/usr/bin/env node
-
-const { execSync, spawn } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-const os = require("os");
-
-const REPO_URL = "https://github.com/raghulvj01/aegis-mcp.git";
-const INSTALL_DIR = path.join(os.homedir(), ".aegis-mcp");
-const VERSION = require("../package.json").version;
-
-const colors = {
-  reset: "\x1b[0m",
-  cyan: "\x1b[36m",
-  green: "\x1b[32m",
-  yellow: "\x1b[33m",
-  red: "\x1b[31m",
-  bold: "\x1b[1m",
-};
-
-function log(msg, color = "reset") {
-  console.error(`${colors[color]}${msg}${colors.reset}`);
-}
-
-function banner() {
-  console.error(`
-${colors.cyan}${colors.bold}
-  🛡️  Aegis MCP Server v${VERSION}
-  Open-source DevSecOps MCP for AI Agents
-${colors.reset}`);
-}
-
-function checkPython() {
-  const candidates = ["python3", "python"];
-  for (const cmd of candidates) {
-    try {
-      const version = execSync(`${cmd} --version 2>&1`, { encoding: "utf8" }).trim();
-      const match = version.match(/Python (\d+)\.(\d+)/);
-      if (match && (parseInt(match[1]) > 3 || (parseInt(match[1]) === 3 && parseInt(match[2]) >= 12))) {
-        log(`✅ Found ${version}`, "green");
-        return cmd;
-      } else if (match) {
-        log(`⚠️  Found ${version} but Python 3.12+ is required.`, "yellow");
-      }
-    } catch {}
-  }
-  log("❌ Python 3.12+ not found. Please install it from https://python.org", "red");
-  process.exit(1);
-}
-
-function isInstalled() {
-  return (
-    fs.existsSync(INSTALL_DIR) &&
-    fs.existsSync(path.join(INSTALL_DIR, "run_stdio.py"))
-  );
-}
-
-function install(pythonCmd) {
-  log("📦 Installing Aegis MCP...", "cyan");
-
-  if (fs.existsSync(INSTALL_DIR)) {
-    log("🔄 Updating existing installation...", "yellow");
-    execSync("git pull", { cwd: INSTALL_DIR, stdio: "inherit" });
-  } else {
-    log(`📥 Cloning from ${REPO_URL}...`, "cyan");
-    execSync(`git clone ${REPO_URL} "${INSTALL_DIR}"`, { stdio: "inherit" });
-  }
-
-  log("📦 Creating virtual environment...", "cyan");
-  execSync(`${pythonCmd} -m venv .venv`, { cwd: INSTALL_DIR, stdio: "inherit" });
-
-  const pip = process.platform === "win32"
-    ? path.join(INSTALL_DIR, ".venv", "Scripts", "pip.exe")
-    : path.join(INSTALL_DIR, ".venv", "bin", "pip");
-
-  log("📦 Installing Python dependencies...", "cyan");
-  execSync(`"${pip}" install -r requirements.txt`, { cwd: INSTALL_DIR, stdio: "inherit" });
-
-  log("✅ Aegis MCP installed successfully!", "green");
-}
-
-function run() {
-  const pythonExe = process.platform === "win32"
-    ? path.join(INSTALL_DIR, ".venv", "Scripts", "python.exe")
-    : path.join(INSTALL_DIR, ".venv", "bin", "python");
-
-  const scriptPath = path.join(INSTALL_DIR, "run_stdio.py");
-
-  log("🚀 Starting Aegis MCP Server...\n", "green");
-
-  const child = spawn(pythonExe, [scriptPath], {
-    stdio: "inherit",
-    env: { ...process.env, MCP_AUTH_DISABLED: "true" },
-  });
-
-  child.on("error", (err) => {
-    log(`\n❌ Failed to start Aegis MCP: ${err.message}`, "red");
-    process.exit(1);
-  });
-
-  child.on("exit", (code) => {
-    process.exit(code || 0);
-  });
-
-  process.on("SIGINT", () => child.kill("SIGINT"));
-  process.on("SIGTERM", () => child.kill("SIGTERM"));
-}
-
-function printMCPConfig() {
-  const pythonExe = process.platform === "win32"
-    ? path.join(INSTALL_DIR, ".venv", "Scripts", "python.exe")
-    : path.join(INSTALL_DIR, ".venv", "bin", "python");
-
-  const scriptPath = path.join(INSTALL_DIR, "run_stdio.py");
-
-  log("\n📋 Add this to your MCP config (claude_desktop_config.json / mcp_config.json):\n", "cyan");
-  console.error(JSON.stringify({
-    mcpServers: {
-      aegis: {
-        command: pythonExe,
-        args: [scriptPath],
-      },
-    },
-  }, null, 2));
-  console.error();
-}
-
-// ── Main ──────────────────────────────────────────────────────────────────────
-
-const args = process.argv.slice(2);
-
-banner();
-
-if (args.includes("--help") || args.includes("-h")) {
-  console.error(`Usage: npx aegis-mcp [options]
-
-Options:
-  (no args)        Install (if needed) and start the MCP server
-  --install        Force reinstall
-  --config         Print MCP config JSON and exit
-  --version, -v    Show version
-  --help, -h       Show this help
-`);
-  process.exit(0);
-}
-
-if (args.includes("--version") || args.includes("-v")) {
-  console.log(VERSION);
-  process.exit(0);
-}
-
-const pythonCmd = checkPython();
-
-if (args.includes("--install") || !isInstalled()) {
-  install(pythonCmd);
-}
-
-if (args.includes("--config")) {
-  printMCPConfig();
-  process.exit(0);
-}
-
-printMCPConfig();
-run();
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawn } = require("child_process");
+const { ensurePythonEnvironment } = require("./prepare-python-env");
+
+function main() {
+  let runtime;
+  try {
+    runtime = ensurePythonEnvironment();
+  } catch (error) {
+    console.error(`[aegis-mcp] ${error.message}`);
+    process.exit(1);
+  }
+
+  const runScript = path.join(runtime.projectRoot, "run_stdio.py");
+  const env = {
+    ...process.env,
+    MCP_AUTH_DISABLED: process.env.MCP_AUTH_DISABLED || "true",
+    PATH: `${runtime.scriptsDir}${path.delimiter}${process.env.PATH || ""}`
+  };
+
+  const child = spawn(runtime.pythonInVenv, [runScript, ...process.argv.slice(2)], {
+    cwd: runtime.projectRoot,
+    env,
+    stdio: "inherit"
+  });
+
+  child.on("error", (error) => {
+    console.error(`[aegis-mcp] Failed to start MCP server: ${error.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+main();

package/bin/prepare-python-env.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const PROJECT_ROOT = path.resolve(__dirname, "..");
+const REQUIREMENTS_FILE = path.join(PROJECT_ROOT, "requirements.txt");
+const VENV_DIR = path.join(PROJECT_ROOT, ".venv");
+const REQUIREMENTS_STAMP = path.join(VENV_DIR, ".requirements.sha256");
+const IS_WINDOWS = process.platform === "win32";
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    cwd: PROJECT_ROOT,
+    stdio: "inherit",
+    ...options
+  });
+}
+
+function candidatePythonCommands() {
+  const override = process.env.AEGIS_PYTHON;
+  if (override && override.trim()) {
+    const pieces = override.trim().split(/\s+/);
+    return [{ command: pieces[0], prefixArgs: pieces.slice(1), label: override.trim() }];
+  }
+
+  if (IS_WINDOWS) {
+    return [
+      { command: "py", prefixArgs: ["-3"], label: "py -3" },
+      { command: "python", prefixArgs: [], label: "python" },
+      { command: "python3", prefixArgs: [], label: "python3" }
+    ];
+  }
+
+  return [
+    { command: "python3", prefixArgs: [], label: "python3" },
+    { command: "python", prefixArgs: [], label: "python" }
+  ];
+}
+
+function findWorkingPython() {
+  for (const candidate of candidatePythonCommands()) {
+    const versionCheck = run(candidate.command, [...candidate.prefixArgs, "--version"], {
+      stdio: "pipe",
+      encoding: "utf8"
+    });
+    if (versionCheck.status === 0) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    "Python 3.12+ was not found. Install Python and make sure it is on PATH, or set AEGIS_PYTHON."
+  );
+}
+
+function venvPythonPath() {
+  if (IS_WINDOWS) {
+    return path.join(VENV_DIR, "Scripts", "python.exe");
+  }
+  return path.join(VENV_DIR, "bin", "python");
+}
+
+function venvScriptsPath() {
+  if (IS_WINDOWS) {
+    return path.join(VENV_DIR, "Scripts");
+  }
+  return path.join(VENV_DIR, "bin");
+}
+
+function requirementsHash() {
+  const content = fs.readFileSync(REQUIREMENTS_FILE);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function ensureVirtualEnvironment(python) {
+  const pythonInVenv = venvPythonPath();
+  if (fs.existsSync(pythonInVenv)) {
+    return;
+  }
+
+  console.error("[aegis-mcp] Creating Python virtual environment...");
+  const created = run(python.command, [...python.prefixArgs, "-m", "venv", VENV_DIR]);
+  if (created.status !== 0) {
+    throw new Error("Failed to create Python virtual environment.");
+  }
+}
+
+function installDependencies(pythonInVenv) {
+  console.error("[aegis-mcp] Installing Python dependencies from requirements.txt...");
+
+  const pipUpgrade = run(pythonInVenv, ["-m", "pip", "install", "--upgrade", "pip"]);
+  if (pipUpgrade.status !== 0) {
+    throw new Error("Failed to upgrade pip in virtual environment.");
+  }
+
+  const pipInstall = run(pythonInVenv, ["-m", "pip", "install", "-r", REQUIREMENTS_FILE]);
+  if (pipInstall.status !== 0) {
+    throw new Error("Failed to install Python dependencies.");
+  }
+}
+
+function ensurePythonEnvironment() {
+  if (!fs.existsSync(REQUIREMENTS_FILE)) {
+    throw new Error("requirements.txt was not found in package root.");
+  }
+
+  const python = findWorkingPython();
+  ensureVirtualEnvironment(python);
+
+  const pythonInVenv = venvPythonPath();
+  const expectedHash = requirementsHash();
+  const currentHash = fs.existsSync(REQUIREMENTS_STAMP)
+    ? fs.readFileSync(REQUIREMENTS_STAMP, "utf8").trim()
+    : "";
+
+  if (currentHash !== expectedHash) {
+    installDependencies(pythonInVenv);
+    fs.writeFileSync(REQUIREMENTS_STAMP, `${expectedHash}\n`, "utf8");
+  }
+
+  return {
+    projectRoot: PROJECT_ROOT,
+    pythonInVenv,
+    scriptsDir: venvScriptsPath()
+  };
+}
+
+module.exports = {
+  ensurePythonEnvironment
+};
+
+if (require.main === module) {
+  try {
+    ensurePythonEnvironment();
+  } catch (error) {
+    console.error(`[aegis-mcp] ${error.message}`);
+    process.exit(1);
+  }
+}