sage-governance 1.0.0 → 1.0.1

package/AGENTS.MD

@@ -312,7 +312,7 @@ When the request involves cloud infrastructure, API integrations, or
 deployment configs, the Security Agent also checks:
 
 - Environment variable handling (secrets must never be in code)
-- AI provider credential hygiene (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+- AI provider credential hygiene (OPENAI_API_KEY, etc.)
 - Database connection string exposure
 - Cloud misconfiguration patterns (public S3 buckets, open ports)
 - GDPR data processor agreement gaps (third-party API calls with PII)

package/README.md

@@ -84,7 +84,7 @@ Deterministic (no LLM) full-spectrum code scanner.
 
 | Severity | Category | Examples |
 |----------|----------|---------|
-| P0 | Secret exposure | Hardcoded API keys, Anthropic/OpenAI keys, DB passwords |
+| P0 | Secret exposure | Hardcoded API keys, OpenAI keys, DB passwords |
 | P0 | Critical PII | SSN, biometrics, medical data, GDPR Article 9 special categories |
 | P1 | Sensitive PII | Geolocation, passport numbers, date of birth |
 | P1 | Protected attribute direct use | `race`, `sex`, `age` as model features |
@@ -128,64 +128,144 @@ Developer asks coding agent to create classifier.py
 
 ---
 
-## Installation
+## Installation & Quick Start
 
-### Quick Start (recommended)
+### 1. Global Installation (recommended)
+
+Install SAGE globally via npm:
 
 ```bash
 npm install -g sage-governance
 ```
 
-This installs the `sage` CLI command globally. The Node.js wrapper automatically resolves `python3`, `python`, or `py` in that order.
+This installs the `sage` CLI command globally.
+
+### 2. Python Dependencies
 
-### Manual / Development
+Install the required Python packages:
 
 ```bash
-git clone https://github.com/[your-org]/sage-governance
-cd sage-governance
+pip install -r $(npm root -g)/sage-governance/requirements.txt
+```
+
+*(Alternatively, run `pip install mcp openai pydantic fairlearn diffprivlib pandas scikit-learn`)*
+
+---
+
+## Configuring SAGE in AI Clients
+
+Since SAGE is an MCP server, you must add it to the MCP configuration of your AI coding environment. Ensure the environment has access to your `OPENAI_API_KEY`.
 
-# Python dependencies
-pip install mcp anthropic pydantic fairlearn diffprivlib
+### 1. Cursor
 
-# Set your LLM provider key
-export ANTHROPIC_API_KEY=sk-ant-...
+To enable SAGE in Cursor, you can configure it globally or on a per-project basis.
 
-# Optional: override model
-export SAGE_LLM_MODEL=claude-sonnet-4-6
+#### Option A: Project-level Configuration (recommended)
+Create a `.cursor/mcp.json` file in your project root with the following content:
+
+```json
+{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
 ```
 
-### Run SAGE as MCP Server
+#### Option B: Global Settings
+1. Go to **Cursor Settings** -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Configure the fields:
+   - **Name**: `sage-governance`
+   - **Type**: `command`
+   - **Command**: `sage`
+   - **Args**: (leave empty)
+4. Click **Save**.
 
-```bash
-# Via CLI (after npm install -g)
-sage
+---
 
-# Directly via Python
-python sage/mcp_server.py
+### 2. OpenCode
+
+Add the following configuration to `opencode.json` in your project root directory:
+
+```json
+{
+  "mcp": {
+    "sage-governance": {
+      "type": "local",
+      "command": ["sage"],
+      "enabled": true,
+      "environment": {
+        "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
 ```
 
 ---
 
-## OpenCode Configuration (`opencode.json`)
+### 3. Claude Desktop
+
+Add SAGE to your global Claude Desktop configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add this entry under the `mcpServers` object:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.schema.json",
   "mcpServers": {
     "sage-governance": {
-      "type": "local",
       "command": "sage",
       "args": [],
       "env": {
-        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
-        "SAGE_LLM_MODEL": "claude-sonnet-4-6"
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
     }
   }
 }
 ```
 
-For Cline, Claude Code, or Continue, use the equivalent MCP server configuration for stdio transport.
+---
+
+### 4. Claude Code
+
+Run this single command in your terminal to automatically register SAGE with Claude Code:
+
+```bash
+claude mcp add sage-governance sage -- sage
+```
+
+---
+
+### 5. VS Code (Cline / Continue)
+
+Add the server to your Cline/Continue MCP configuration settings JSON:
+
+```json
+{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
+```
 
 ---
 
@@ -299,7 +379,7 @@ When base rates differ across groups, Demographic Parity, Equalized Odds, and Pr
 | George | Ethics & regulatory policy files, project management |
 | Jeremy | Data science validation, security pipeline, presentation |
 
-**Built with:** FastMCP · Python · Pydantic · Fairlearn · Anthropic API  
+**Built with:** FastMCP · Python · Pydantic · Fairlearn · OpenAI API  
 **Built by:** Oluwagbemisola, Prajwal, Roshan, Jeremy, George
 **License:** MIT
 
@@ -316,4 +396,4 @@ When base rates differ across groups, Demographic Parity, Equalized Odds, and Pr
 - ProPublica (2016). "Machine Bias." COMPAS audit.
 - Ali et al. (2019). "Discrimination through Optimization." ACM FAccT.
 - Beunec Technologies Inc Agentic Annotation Protocol - github.com/beunec
-- Anthropic Model Context Protocol — modelcontextprotocol.io
+- Model Context Protocol — modelcontextprotocol.io

package/bin/sage.js

@@ -40,6 +40,17 @@ if (!pythonExe) {
     process.exit(1);
 }
 
+// Check if running interactively or if help/setup/config argument is passed
+const isTTY = process.stdin.isTTY || process.stdout.isTTY;
+const hasHelpOrSetup = process.argv.some(arg => 
+    ['--help', '-h', 'help', 'setup', '--setup', 'config', '--config'].includes(arg.toLowerCase())
+);
+
+if (isTTY || hasHelpOrSetup) {
+    printSetupGuide();
+    process.exit(0);
+}
+
 const child = spawn(pythonExe, [MCP_SERVER_PATH, ...process.argv.slice(2)], {
     stdio: 'inherit',
     env: process.env
@@ -53,3 +64,109 @@ child.on('error', (err) => {
 child.on('exit', (code) => {
     process.exit(code);
 });
+
+function printSetupGuide() {
+    console.log(`
+\x1b[1;36m╔══════════════════════════════════════════════════════════════════════════╗\x1b[0m
+\x1b[1;36m║  SAGE — Supervisory Agentic Governance Engine                          ║\x1b[0m
+\x1b[1;36m║  Model Context Protocol (MCP) Server Setup & Configuration Guide          ║\x1b[0m
+\x1b[1;36m╚══════════════════════════════════════════════════════════════════════════╝\x1b[0m
+
+SAGE is designed to run as an MCP server inside your favorite AI coding environment.
+Since you ran SAGE in an interactive terminal, here is how to configure it.
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m1. CURSOR CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Go to: \x1b[1mCursor Settings -> Features -> MCP -> Add New MCP Server\x1b[0m
+
+  • \x1b[1mName:\x1b[0m sage-governance
+  • \x1b[1mType:\x1b[0m command
+  • \x1b[1mCommand:\x1b[0m sage
+  • \x1b[1mArgs:\x1b[0m (leave empty)
+
+Alternatively, add the following to \x1b[34m.cursor/mcp.json\x1b[0m in your project:
+
+\x1b[32m{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m2. OPENCODE CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Add the following to \x1b[34mopencode.json\x1b[0m in your project root directory:
+
+\x1b[32m{
+  "mcp": {
+    "sage-governance": {
+      "type": "local",
+      "command": ["sage"],
+      "enabled": true,
+      "environment": {
+        "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m3. CLAUDE DESKTOP CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Add the following to your global Claude Desktop configuration:
+Path: \x1b[34m~/Library/Application Support/Claude/claude_desktop_config.json\x1b[0m
+
+\x1b[32m{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m4. CLAUDE CODE CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Run the following command in your terminal:
+
+  \x1b[1;35mclaude mcp add sage-governance sage -- sage\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m5. VS CODE (CLINE / CONTINUE) CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Add the following to your Cline/Continue MCP settings json file:
+
+\x1b[32m{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1mNOTE:\x1b[0m Make sure you have python dependencies installed:
+  \x1b[35mpip install mcp openai pydantic fairlearn diffprivlib pandas scikit-learn\x1b[0m
+`);
+}
+

package/kimicode.json

@@ -0,0 +1,16 @@
+{
+  "_note": "Kimi Code MCP configuration. Copy this file or add the sage-governance block to your Kimi Code MCP server settings.",
+  "_docs": "https://kimi.moonshot.cn",
+  "_compatible_with": "Kimi Code",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}

package/opencode.json

@@ -1,13 +1,13 @@
 {
-  "$schema": "https://opencode.ai/config.schema.json",
-  "model": "anthropic/claude-sonnet-4-6",
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openai/gpt-4o-mini",
+  "mcp": {
     "sage-governance": {
       "type": "local",
-      "command": "sage",
-      "args": [],
-      "env": {
-        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+      "command": ["sage"],
+      "enabled": true,
+      "environment": {
+        "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sage-governance",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Supervisory Agentic Governance Engine — Open-source MCP governance layer for agentic coding systems. Intercepts, evaluates, and audits AI coding prompts for EU AI Act, GDPR, and fairness compliance.",
   "main": "bin/sage.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/sage.js",
-    "_prepublishOnly": "find . -path './.git' -prune -o -name '__pycache__' -type d -print -exec rm -rf {} + 2>/dev/null; echo 'pycache cleaned'",
+    "prepublishOnly": "find . -path './.git' -prune -o -name '__pycache__' -type d -print -exec rm -rf {} + 2>/dev/null; echo 'pycache cleaned'",
     "postinstall": "node -e \"console.log('\\n[SAGE] Python deps required — run: pip install -r requirements.txt\\n')\""
   },
   "files": [
@@ -23,7 +23,10 @@
     "opencode.json",
     "claude.json",
     "cursor.json",
-    "codex.json"
+    "codex.json",
+    "windsurf.json",
+    "trae.json",
+    "kimicode.json"
   ],
   "keywords": [
     "mcp",

package/sage/security_agent.py

@@ -80,7 +80,7 @@ class SecurityReport:
 # (regex, description, severity)
 _SECRET_PATTERNS: list[tuple[str, str, Severity]] = [
     # AI provider keys
-    (r"sk-ant-[A-Za-z0-9\-_]{40,}", "Anthropic API key hardcoded", "P0"),
+    (r"sk-ant-[A-Za-z0-9\-_]{40,}", "AI Provider API key hardcoded", "P0"),
     (r"sk-[A-Za-z0-9]{48}", "OpenAI API key hardcoded", "P0"),
     (r"AIza[0-9A-Za-z\-_]{35}", "Google API key hardcoded", "P0"),
     # Generic credentials

package/trae.json

@@ -0,0 +1,16 @@
+{
+  "_note": "Trae MCP configuration. Copy this file or add the sage-governance block to your Trae MCP server settings.",
+  "_docs": "https://trae.sh",
+  "_compatible_with": "Trae",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}

package/windsurf.json

@@ -0,0 +1,15 @@
+{
+  "_note": "Windsurf MCP configuration. Copy this file or add the sage-governance block to ~/.codeium/windsurf/mcp_config.json",
+  "_docs": "https://codeium.com/windsurf",
+  "_compatible_with": "Windsurf",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}