docs(docs): consolidate setup guide into DEMO_GUIDE
- Merge all content from Local-Setup.md into DEMO_GUIDE.md: installation, venv activation, .env config, feature flags, Claude Desktop integration, mock drift scenarios, SOC 2 audit logging, troubleshooting, and dev workflow - Delete Local-Setup.md (now redundant) - Correct stale tool count: 48 → 50 (verified from @mcp.tool() grep) - Fix audit tool names: replaced removed audit_user_drift references with current scan_* tool names - Add working-directory callout (scripts require nexus-mcp/ as cwd) Continues doc reorganization from SESSION_SNAPSHOT_2026-04-13_2
This commit is contained in:
parent
f040ac2d07
commit
f19fcc8f0b
@ -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
|
||||
|
||||
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user