diff --git a/documentation/DEMO_GUIDE.md b/documentation/DEMO_GUIDE.md index f96a1a0..e28f464 100644 --- a/documentation/DEMO_GUIDE.md +++ b/documentation/DEMO_GUIDE.md @@ -1,101 +1,354 @@ -# Demo & Test Scripts +# Nexus-MCP — demo and setup guide -This directory contains scripts for testing and demonstrating the Nexus MCP server functionality. +Sharded enterprise integration MCP server for Active Directory, Entra ID, Workday, BMC Helix, Lansweeper, Intune, FedEx, and cross-system drift auditing. -## Quick Start +> **All test scripts must be run from the `nexus-mcp/` directory.** -All scripts run against mock data (no credentials required). +--- -### 🔍 Audit Tools Demonstration +## Prerequisites + +- Python 3.11 or newer +- Git +- PowerShell (Windows) or bash (Linux/macOS) +- Access to corporate systems (AD, Entra, Workday) — or enable mock mode (no credentials needed) + +--- + +## Installation + +### 1. Navigate to the server directory + +```bash +cd /path/to/mcp_servers/nexus-mcp +``` + +### 2. Create and activate a virtual environment + +**Windows (PowerShell):** + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +``` + +**Windows (bash/Git Bash):** + +```bash +python -m venv .venv +source .venv/Scripts/activate +``` + +**Linux/macOS:** + +```bash +python -m venv .venv +source .venv/bin/activate +``` + +### 3. Install dependencies + +```bash +pip install -e . +``` + +Installs nexus-mcp in editable mode with all required packages (`mcp`, `httpx`, `python-dotenv`, `ldap3`, `msal`, etc.). + +--- + +## Configuration + +### 1. Create .env file + +```bash +cp .env.example .env +``` + +### 2. Choose your mode + +**Option A: Mock mode (no credentials needed)** + +Good for development, testing shards, and exploring drift scenarios. + +```env +USE_MOCK=true + +ENABLE_IDENTITY=true +ENABLE_WORKDAY=true +ENABLE_AUDIT=true +ENABLE_ITSM=false +ENABLE_ASSETS=false +ENABLE_LOGISTICS=false + +AUDIT_LOGGING_ENABLED=true +AUDIT_LOG_FILE=./logs/nexus_audit.jsonl +AUDIT_LOG_STDERR=true +``` + +**Option B: Live mode (production credentials)** + +Requires actual service accounts and API credentials. Enable only the shards where credentials are available. + +```env +USE_MOCK=false + +ENABLE_IDENTITY=true +ENABLE_WORKDAY=false # Set true when credentials available +ENABLE_AUDIT=true +ENABLE_ITSM=false +ENABLE_ASSETS=false +ENABLE_LOGISTICS=false + +# Active Directory +AD_SERVER=ldap://your-dc.company.com +AD_PORT=389 +AD_BASE_DN=DC=company,DC=com +AD_USER=CN=svc_nexus,OU=Service Accounts,DC=company,DC=com +AD_PASSWORD=your_password +AD_USE_SSL=false + +# Microsoft Entra ID (Azure AD) +ENTRA_TENANT_ID=your_tenant_id +ENTRA_CLIENT_ID=your_client_id +ENTRA_CLIENT_SECRET=your_client_secret +``` + +Your `.env` file is never committed to git. + +--- + +## Running the server + +```bash +python src/main.py +``` + +**Expected startup output (mock mode, default shards):** + +``` +[nexus] ✅ identity shard loaded +[nexus] ✅ workday shard loaded +[nexus] ✅ audit shard loaded +[nexus] ⏸ itsm shard disabled (ENABLE_ITSM != true) +[nexus] ⏸ assets shard disabled (ENABLE_ASSETS != true) +[nexus] ⏸ logistics shard disabled (ENABLE_LOGISTICS != true) +[nexus] 🔒 SOC 2 audit middleware active → ./logs/nexus_audit.jsonl +``` + +The server runs on stdio transport and waits for MCP protocol messages. + +--- + +## Claude Desktop integration + +Add this block to your Claude Desktop `config.json`: + +- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` +- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` + +```json +{ + "mcpServers": { + "nexus": { + "command": "python", + "args": ["src/main.py"], + "cwd": "C:/Users/your-username/repos/mcp_servers/nexus-mcp", + "env": { + "USE_MOCK": "true" + } + } + } +} +``` + +Restart Claude Desktop. The Nexus tools will appear in the tool picker. + +--- + +## Feature flag reference + +| Flag | Shard | Systems | Default | +|---|---|---|---| +| `ENABLE_IDENTITY` | `identity.py` | Active Directory + Entra ID | `true` | +| `ENABLE_WORKDAY` | `workday.py` | Workday HCM | `true` | +| `ENABLE_AUDIT` | `audit.py` | Cross-system drift | `true` | +| `ENABLE_ITSM` | `itsm.py` | BMC Helix | `false` | +| `ENABLE_ASSETS` | `assets.py` | Lansweeper + Intune | `false` | +| `ENABLE_LOGISTICS` | `logistics.py` | FedEx | `false` | + +Set a flag to `false` (or omit it) to put that shard in holding pattern. The server will start successfully and skip those tools. + +--- + +## Quick start — demo scripts + +All scripts run from the `nexus-mcp/` directory against mock data. + +### Audit tools demonstration ```bash python test_client.py ``` -**Shows:** -- All 4 audit tools executing -- Detailed mismatch detection results -- Severity classification (HIGH/MEDIUM/LOW) -- Complete scan summaries +Shows all 4 audit scan tools executing with severity classification and mismatch summaries. -**Expected output:** 6 total mismatches across 9 employee records +**Expected:** 6 total mismatches across 9 employee records. ---- - -### 📋 Tool Catalog Browser +### Tool catalog browser ```bash python list_tools.py ``` -**Shows:** -- Complete tool inventory (48 tools) -- Tools organized by shard -- Tool descriptions from docstrings -- Shard loading status +Shows the complete tool inventory (50 tools), organized by shard, with descriptions from docstrings. ---- - -### 📡 MCP Protocol Simulation +### MCP protocol simulation ```bash python test_mcp_protocol.py ``` -**Shows:** -- MCP protocol handshake -- Tool discovery (tools/list) -- Tool invocation (tools/call) -- JSON response format -- Claude Desktop configuration example +Simulates the full MCP handshake: protocol negotiation → `tools/list` discovery → `tools/call` invocation → JSON response. Useful for verifying Claude Desktop compatibility. --- -### ✅ Full Test Suite +## Test suite + +Run from the `nexus-mcp/` directory: ```bash -python -m pytest tests/workday_tests/ tests/integration_test_audit_shard.py -v +# Full suite +pytest tests/ -v + +# Specific modules +pytest tests/identity_tests/ -v +pytest tests/workday_tests/ -v + +# With coverage +pytest tests/ --cov=lib --cov=src --cov-report=term-missing + +# Audit integration tests only +pytest tests/workday_tests/ tests/integration_test_audit_shard.py -v ``` -**Runs:** -- 4 unit tests (drift detection functions) -- 6 integration tests (MCP tool registration & execution) +**Expected baseline:** 10/10 passing in ~0.6s. -**Expected:** 10/10 passing in ~0.6s +See `nexus-mcp/TEST_VALIDATION_REPORT.md` for full results and MCP protocol compliance details. --- -## Test Data +## Mock data and drift scenarios -Mock data is defined in `lib/drift_detection.py`: +Mock data is defined in `lib/mock_data.py`. Pre-seeded mismatches cover all severity levels: -**Employee Records:** 9 (EMP001-EMP777) +| Employee | Mismatch | Severity | Detected by | +|---|---|---|---| +| Terminated worker | Active in Workday as terminated, AD account still enabled | HIGH | `scan_status_reconciliation` | +| Bob Martinez | Title differs — AD: "Sr. Software Engineer" vs Workday: "Software Engineer" | MEDIUM | `scan_job_title_drift` | +| Carol Chen | Department differs — Workday: "Product Management" vs AD: "Engineering" | MEDIUM | `scan_department_mismatches` | +| 3 employees | AD display name doesn't align with legal/preferred name in Workday | LOW | `scan_name_variance_mismatches` | -**Pre-seeded Mismatches:** -- 1 terminated user still enabled (HIGH) -- 1 job title inconsistency (MEDIUM) -- 1 department drift (MEDIUM) -- 3 name variances (LOW) +**Employee records:** 9 (EMP001–EMP777) | **Total pre-seeded mismatches:** 6 + +Try the audit tools in Claude chat with Nexus-MCP active: + +``` +"Scan for terminated workers still active in AD" +"Run a job title drift scan" +"Show me all stale AD accounts" +"Run audit statistics" +``` --- -## Validation Report +## SOC 2 audit logging -See `TEST_VALIDATION_REPORT.md` for: -- Complete test results -- Tool inventory -- MCP protocol compliance verification -- Commit readiness checklist +Every tool call is logged to `logs/nexus_audit.jsonl` (one JSON object per line, automatically redacted). + +Each entry contains: + +- `event_id` — UUID v4 for correlation +- `timestamp` — ISO 8601 UTC +- `tool` — MCP tool name +- `shard` — identity | workday | audit | etc. +- `action_category` — READ | AUDIT | REPORT +- `args_summary` — call arguments with passwords/tokens redacted +- `mock_mode` — true/false +- `status` — success | error +- `latency_ms` — execution time + +Query the audit log directly using the built-in tools: + +``` +"Show me the last 50 audit log entries" → nexus_audit_recent +"Give me audit statistics" → nexus_audit_stats +``` --- -## Next Steps +## Troubleshooting -1. **Review test output** - Confirm all tools work as expected -2. **Check validation report** - Review production readiness -3. **Commit code** - Use suggested commit message from report -4. **Integrate with Claude Desktop** - Add server to config (see test_mcp_protocol.py output) +**Server won't start** + +- Check Python version: `python --version` (must be 3.11+) +- Verify the venv is active (`(.venv)` should appear in your prompt) +- Verify dependencies: `pip list | grep mcp` + +**Shard not loading** + +- Check the feature flag in `.env`: `ENABLE_IDENTITY=true` +- Look for error messages in the startup output +- Verify the shard file exists: `ls src/shards/identity.py` + +**Credentials not working (live mode)** + +- Test AD connectivity: `python -c "import ldap3; print(ldap3.__version__)"` +- Verify the service account can bind to LDAP +- Check firewall rules for on-prem AD + +**Audit log not writing** + +- Check permissions on the `logs/` directory +- Verify `AUDIT_LOGGING_ENABLED=true` in `.env` --- -**Status:** ✅ All tests passing, ready for production +## Development workflow + +### Adding a tool to an existing shard + +1. Edit the shard file (e.g. `src/shards/identity.py`) +2. Add the tool function inside `register(mcp)` using the `@mcp.tool()` decorator +3. Restart the server and test in Claude Desktop + +### Creating a new shard + +1. Copy an existing shard as a template: `cp src/shards/identity.py src/shards/my_system.py` +2. Implement `register(mcp)` with your tools +3. Add the shard to `src/main.py`: + + ```python + if _enabled("MY_SYSTEM"): + my_system.register(mcp) + ``` + +4. Add the flag to `.env.example`: `ENABLE_MY_SYSTEM=false` + +### Switching between mock and live mode + +Change `USE_MOCK` in `.env` and restart — no code changes needed: + +```bash +USE_MOCK=false +python src/main.py +``` + +--- + +## Next steps + +1. Run `python test_client.py` to verify audit tools work in mock mode +2. Explore the pre-seeded drift scenarios using audit tools in Claude chat +3. Populate `.env` with live credentials for available systems +4. Enable additional shards as credentials are provisioned +5. Review `nexus-mcp/README.md` for the full tool reference and NEXUS work item tracking diff --git a/documentation/Local-Setup.md b/documentation/Local-Setup.md deleted file mode 100644 index 1304a73..0000000 --- a/documentation/Local-Setup.md +++ /dev/null @@ -1,333 +0,0 @@ -# Nexus-MCP local setup - -Sharded enterprise integration MCP server for Active Directory, Entra ID, Workday, and cross-system drift auditing. - ---- - -## Prerequisites - -- Python 3.11 or newer -- Git -- PowerShell (Windows) or bash (Linux/macOS) -- Access to corporate systems (AD, Entra, Workday) or mock mode enabled - ---- - -## Installation - -### 1. Clone and navigate - -```bash -cd /path/to/mcp_servers -cd nexus-mcp -``` - -### 2. Create virtual environment - -```bash -python -m venv .venv -``` - -### 3. Activate virtual environment - -**Windows (PowerShell):** -```powershell -.\.venv\Scripts\Activate.ps1 -``` - -**Windows (bash/Git Bash):** -```bash -source .venv/Scripts/activate -``` - -**Linux/macOS:** -```bash -source .venv/bin/activate -``` - -### 4. Install dependencies - -```bash -pip install -e . -``` - -This installs nexus-mcp in editable mode with all required packages (mcp, httpx, python-dotenv, ldap3, msal, etc.). - ---- - -## Configuration - -### 1. Create .env file - -```bash -cp .env.example .env -``` - -### 2. Choose your mode - -**Option A: Mock Mode (No credentials needed)** - -Good for development, testing shards, and exploring drift scenarios. - -```env -USE_MOCK=true - -# Enable the shards you want to test -ENABLE_IDENTITY=true -ENABLE_WORKDAY=true -ENABLE_AUDIT=true -ENABLE_ITSM=false -ENABLE_ASSETS=false -ENABLE_LOGISTICS=false - -# Audit logging -AUDIT_LOGGING_ENABLED=true -AUDIT_LOG_FILE=./logs/nexus_audit.jsonl -AUDIT_LOG_STDERR=true -``` - -**Option B: Live Mode (Production credentials)** - -Requires actual service accounts and API credentials. - -```env -USE_MOCK=false - -# Enable only the shards where you have credentials -ENABLE_IDENTITY=true -ENABLE_WORKDAY=false # Set true when credentials available -ENABLE_AUDIT=true -ENABLE_ITSM=false -ENABLE_ASSETS=false -ENABLE_LOGISTICS=false - -# Active Directory credentials -AD_SERVER=ldap://your-dc.company.com -AD_PORT=389 -AD_BASE_DN=DC=company,DC=com -AD_USER=CN=svc_nexus,OU=Service Accounts,DC=company,DC=com -AD_PASSWORD=your_password -AD_USE_SSL=false - -# Microsoft Entra ID (Azure AD) -ENTRA_TENANT_ID=your_tenant_id -ENTRA_CLIENT_ID=your_client_id -ENTRA_CLIENT_SECRET=your_client_secret - -# (Add other system credentials as needed) -``` - -### 3. Verify configuration - -Your `.env` file is never committed to git (listed in `.gitignore`). - ---- - -## Running the server - -### Start the MCP server - -```bash -python src/main.py -``` - -**Expected output (mock mode):** - -``` -[nexus] ✅ identity shard loaded -[nexus] ✅ workday shard loaded -[nexus] ✅ audit shard loaded -[nexus] ⏸ itsm shard disabled (ENABLE_ITSM != true) -[nexus] ⏸ assets shard disabled (ENABLE_ASSETS != true) -[nexus] ⏸ logistics shard disabled (ENABLE_LOGISTICS != true) -[nexus] 🔒 SOC 2 audit middleware active — 16 tools wrapped → ./logs/nexus_audit.jsonl -``` - -The server runs on stdio transport and waits for MCP protocol messages. - ---- - -## Claude Desktop integration - -Add this to your Claude Desktop `config.json`: - -**Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - -**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - -```json -{ - "mcpServers": { - "nexus": { - "command": "python", - "args": ["src/main.py"], - "cwd": "C:/Users/your-username/repos/mcp_servers/nexus-mcp", - "env": { - "USE_MOCK": "true" - } - } - } -} -``` - -Restart Claude Desktop. You should see the Nexus tools in the tool picker. - ---- - -## Feature flag reference - -Control which shards load at startup: - -| Flag | Shard | Systems | Default | -|---|---|---|---| -| `ENABLE_IDENTITY` | identity.py | AD + Entra ID | `true` | -| `ENABLE_WORKDAY` | workday.py | Workday HCM | `true` | -| `ENABLE_AUDIT` | audit.py | Cross-system drift | `true` | -| `ENABLE_ITSM` | itsm.py | BMC Helix | `false` | -| `ENABLE_ASSETS` | assets.py | Lansweeper + Intune | `false` | -| `ENABLE_LOGISTICS` | logistics.py | FedEx | `false` | - -Set a flag to `false` (or omit it) to put that shard in "holding pattern" mode. The server will start successfully but skip loading those tools. - ---- - -## Testing - -Run the test suite: - -```bash -pytest tests/ -v -``` - -Run specific test modules: - -```bash -pytest tests/identity_tests/ -v -pytest tests/workday_tests/ -v -``` - -Run with coverage: - -```bash -pytest tests/ --cov=lib --cov=src --cov-report=term-missing -``` - ---- - -## Mock mode drift scenarios - -The lib/mock_data.py file includes deliberate drift: - -- **Bob Martinez:** title differs between AD ("Sr. Software Engineer") and Workday/Entra ("Software Engineer") -- **Carol Chen:** department differs — Workday "Product Management" vs AD "Engineering" -- **David Kim:** AD account disabled but Entra account still enabled -- **Emma Wilson:** AD stale account (no login in 120 days) - -Use the audit tools to detect these: - -```python -# In Claude chat with Nexus-MCP active -"Run audit_user_drift for Bob Martinez" -"Show me all stale AD accounts" -``` - ---- - -## Troubleshooting - -### Server won't start - -- Check Python version: `python --version` (must be 3.11+) -- Verify virtual environment is active (you should see `(.venv)` in your prompt) -- Verify dependencies installed: `pip list | grep mcp` - -### Shard not loading - -- Check the feature flag in `.env`: `ENABLE_IDENTITY=true` -- Look for error messages in the startup output -- Verify the shard file exists: `ls src/shards/identity.py` - -### Credentials not working (live mode) - -- Test AD connectivity: `python -c "import ldap3; print(ldap3.__version__)"` -- Verify service account can bind to LDAP -- Check firewall rules if connecting to on-prem AD - -### Audit log not writing - -- Check permissions on the `logs/` directory -- Verify `AUDIT_LOGGING_ENABLED=true` in `.env` -- Check disk space - ---- - -## Development workflow - -### Adding a new tool to an existing shard - -1. Edit the shard file: `src/shards/identity.py` -2. Add your tool function inside the `register(mcp)` function -3. Restart the server -4. Test with Claude Desktop - -### Creating a new shard - -1. Copy an existing shard as a template: `cp src/shards/identity.py src/shards/my_system.py` -2. Implement the `register(mcp)` function with your tools -3. Add the shard to `src/main.py`: - ```python - if _enabled("MY_SYSTEM"): - my_system.register(mcp) - ``` -4. Add the feature flag to `.env.example`: `ENABLE_MY_SYSTEM=false` - -### Switching between mock and live mode - -Just change `USE_MOCK` in `.env` and restart: - -```bash -# Switch to live -USE_MOCK=false - -# Restart server -python src/main.py -``` - -No code changes needed — every shard checks the `USE_MOCK` flag automatically. - ---- - -## SOC 2 audit logging - -Every tool call is logged to `logs/nexus_audit.jsonl` (one JSON object per line). - -Each entry contains: -- `event_id` — UUID v4 for correlation -- `timestamp` — ISO 8601 UTC -- `tool` — MCP tool name -- `shard` — identity | workday | audit | etc. -- `action_category` — READ | AUDIT | REPORT -- `args_summary` — call arguments with passwords/tokens redacted -- `mock_mode` — true/false -- `status` — success | error -- `latency_ms` — execution time - -Query the audit log using the built-in tools: - -```python -# In Claude chat -"Show me the last 50 audit log entries" # calls nexus_audit_recent -"Give me audit statistics" # calls nexus_audit_stats -``` - ---- - -## Next steps - -1. Test mock mode with `USE_MOCK=true` to verify the shards load -2. Explore the drift scenarios using audit tools -3. Configure credentials for live systems -4. Enable additional shards as credentials become available -5. Build custom reports using the audit shard tools - -For more details, see [README.md](README.md) for the full tool reference.