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
|
```bash
|
||||||
python test_client.py
|
python test_client.py
|
||||||
```
|
```
|
||||||
|
|
||||||
**Shows:**
|
Shows all 4 audit scan tools executing with severity classification and mismatch summaries.
|
||||||
- All 4 audit tools executing
|
|
||||||
- Detailed mismatch detection results
|
|
||||||
- Severity classification (HIGH/MEDIUM/LOW)
|
|
||||||
- Complete scan 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
|
```bash
|
||||||
python list_tools.py
|
python list_tools.py
|
||||||
```
|
```
|
||||||
|
|
||||||
**Shows:**
|
Shows the complete tool inventory (50 tools), organized by shard, with descriptions from docstrings.
|
||||||
- Complete tool inventory (48 tools)
|
|
||||||
- Tools organized by shard
|
|
||||||
- Tool descriptions from docstrings
|
|
||||||
- Shard loading status
|
|
||||||
|
|
||||||
---
|
### MCP protocol simulation
|
||||||
|
|
||||||
### 📡 MCP Protocol Simulation
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
python test_mcp_protocol.py
|
python test_mcp_protocol.py
|
||||||
```
|
```
|
||||||
|
|
||||||
**Shows:**
|
Simulates the full MCP handshake: protocol negotiation → `tools/list` discovery → `tools/call` invocation → JSON response. Useful for verifying Claude Desktop compatibility.
|
||||||
- MCP protocol handshake
|
|
||||||
- Tool discovery (tools/list)
|
|
||||||
- Tool invocation (tools/call)
|
|
||||||
- JSON response format
|
|
||||||
- Claude Desktop configuration example
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### ✅ Full Test Suite
|
## Test suite
|
||||||
|
|
||||||
|
Run from the `nexus-mcp/` directory:
|
||||||
|
|
||||||
```bash
|
```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:**
|
**Expected baseline:** 10/10 passing in ~0.6s.
|
||||||
- 4 unit tests (drift detection functions)
|
|
||||||
- 6 integration tests (MCP tool registration & execution)
|
|
||||||
|
|
||||||
**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:**
|
**Employee records:** 9 (EMP001–EMP777) | **Total pre-seeded mismatches:** 6
|
||||||
- 1 terminated user still enabled (HIGH)
|
|
||||||
- 1 job title inconsistency (MEDIUM)
|
Try the audit tools in Claude chat with Nexus-MCP active:
|
||||||
- 1 department drift (MEDIUM)
|
|
||||||
- 3 name variances (LOW)
|
```
|
||||||
|
"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:
|
Every tool call is logged to `logs/nexus_audit.jsonl` (one JSON object per line, automatically redacted).
|
||||||
- Complete test results
|
|
||||||
- Tool inventory
|
Each entry contains:
|
||||||
- MCP protocol compliance verification
|
|
||||||
- Commit readiness checklist
|
- `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
|
**Server won't start**
|
||||||
2. **Check validation report** - Review production readiness
|
|
||||||
3. **Commit code** - Use suggested commit message from report
|
- Check Python version: `python --version` (must be 3.11+)
|
||||||
4. **Integrate with Claude Desktop** - Add server to config (see test_mcp_protocol.py output)
|
- 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