nathan/nexus-mcp
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Refactor documentation: Remove outdated README and Tool Inventory, add comprehensive DEMO_GUIDE and new Tool Inventory file

Browse Source
This commit is contained in:
nathan
2026-04-14 15:14:17 -04:00
parent f19fcc8f0b
commit dec6f4d2ff
4 changed files with 244 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/DEMO_GUIDE.md
-354
View File
@@ -1,354 +0,0 @@
# Nexus-MCP — demo and setup guide
Sharded enterprise integration MCP server for Active Directory, Entra ID, Workday, BMC Helix, Lansweeper, Intune, FedEx, and cross-system drift auditing.
> **All test scripts must be run from the `nexus-mcp/` directory.**
---
## 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 scan tools executing with severity classification and mismatch summaries.
**Expected:** 6 total mismatches across 9 employee records.
### Tool catalog browser
```bash
python list_tools.py
```
Shows the complete tool inventory (50 tools), organized by shard, with descriptions from docstrings.
### MCP protocol simulation
```bash
python test_mcp_protocol.py
```
Simulates the full MCP handshake: protocol negotiation → `tools/list` discovery → `tools/call` invocation → JSON response. Useful for verifying Claude Desktop compatibility.
---
## Test suite
Run from the `nexus-mcp/` directory:
```bash
# 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
```
**Expected baseline:** 10/10 passing in ~0.6s.
See `nexus-mcp/TEST_VALIDATION_REPORT.md` for full results and MCP protocol compliance details.
---
## Mock data and drift scenarios
Mock data is defined in `lib/mock_data.py`. Pre-seeded mismatches cover all severity levels:
| 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` |
**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"
```
---
## SOC 2 audit logging
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
```
---
## Troubleshooting
**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`
---
## 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
documentation/Nexus MCP - Tool Inventory.md
-145
View File
@@ -1,145 +0,0 @@
# Nexus MCP - Tool inventory
A complete reference of every service and tool currently registered in the Nexus MCP server. Sorted alphabetically by service, then by tool name within each service.
---
## Active Directory
**Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017)
| Tool | Description |
|---|---|
| `ad_get_disabled_accounts` | Returns all disabled user accounts in Active Directory. |
| `ad_get_group_members` | Returns all members of an AD group by its distinguished name. |
| `ad_get_stale_accounts` | Returns active AD accounts with no recorded login activity within a configurable number of days (default: 90). |
| `ad_get_user` | Looks up a single AD user by their sAMAccountName (login name) and returns a normalized user object. |
| `ad_get_user_by_email` | Looks up a single AD user by their email address and returns a normalized user object. |
| `ad_list_groups` | Lists all security and distribution groups in Active Directory. |
| `ad_search_users` | Searches AD users by display name or sAMAccountName fragment and returns a list of normalized user objects. |
---
## Audit (cross-system)
**Shard:** `audit` + `main.py` | **Status:** 🟢 Green
| Tool | Description |
|---|---|
| `nexus_audit_recent` | Returns the last *n* entries from the Nexus-MCP SOC 2 structured audit log. Each entry includes tool name, shard, action category, redacted argument summary, status, and latency. |
| `nexus_audit_stats` | Returns aggregate statistics over the entire audit log, including total call count, status breakdown, shard breakdown, top-10 tools by call volume, and recent errors. |
| `scan_department_mismatches` | Detects workers whose department in Workday differs from their department attribute in Active Directory. Severity: MEDIUM. |
| `scan_job_title_drift` | Detects workers whose job title in Workday differs from their title attribute in Active Directory. Severity: MEDIUM. |
| `scan_name_variance_mismatches` | Detects AD display names that do not align with the legal or preferred name stored in Workday. Severity: LOW. |
| `scan_status_reconciliation` | Detects workers who are terminated in Workday but still have an enabled account in Active Directory. Severity: HIGH. |
---
## BMC Helix (ITSM)
**Shard:** `itsm` | **Status:** 🔴 Red (Planned)
| Tool | Description |
|---|---|
| `helix_get_incident` | Retrieves full details for a single Helix incident ticket by its Entry ID (e.g. `INC0001234`). |
| `helix_get_problem` | Retrieves a Helix problem investigation record by its problem ID (e.g. `PRB0000456`). |
| `helix_list_changes` | Lists change requests from BMC Helix with optional status filter (e.g. Draft, Scheduled, In Progress). |
| `helix_list_cmdb_assets` | Lists hardware assets registered in the BMC Helix CMDB. |
| `helix_list_incidents` | Lists incidents from BMC Helix ITSM with optional filters for status and assignee. |
| `helix_search_cmdb` | Searches the BMC Helix CMDB for configuration items (CIs) matching a name fragment. |
---
## FedEx
**Shard:** `logistics` | **Status:** 🔴 Red (Planned — credentials pending)
| Tool | Description |
|---|---|
| `fedex_get_rates` | Returns available FedEx shipping service options and rates between two postal codes for a given package weight. |
| `fedex_get_shipment_events` | Returns the full ordered list of scan events (location, timestamp, description) for a single FedEx tracking number. |
| `fedex_track_multiple` | Tracks up to 30 FedEx shipments in a single API call and returns tracking results for each. |
| `fedex_track_shipment` | Tracks a single FedEx shipment by tracking number and returns full tracking details including current status and estimated delivery. |
| `fedex_validate_address` | Validates a shipping address against the FedEx Address Validation API and returns the classification and resolved address. |
---
## Microsoft Entra ID
**Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017)
| Tool | Description |
|---|---|
| `entra_get_conditional_access_policies` | Lists all Conditional Access policies configured in the Entra ID tenant. |
| `entra_get_group_members` | Lists members of an Entra ID group by its object ID. |
| `entra_get_risky_users` | Lists users currently flagged as risky by Entra ID Identity Protection. Requires `IdentityRiskyUser.Read.All` Graph permission. |
| `entra_get_signin_logs` | Retrieves recent sign-in log entries from Entra ID, ordered by most recent. Requires `AuditLog.Read.All` Graph permission. |
| `entra_get_user` | Retrieves a single Entra ID user by object ID or UPN and returns a normalized user object. |
| `entra_list_groups` | Lists all groups in the Microsoft Entra ID tenant. |
| `entra_list_service_principals` | Lists service principals (app registrations and enterprise applications) registered in Entra ID. |
| `entra_list_users` | Lists users in Microsoft Entra ID and returns normalized user objects. |
---
## Microsoft Intune
**Shard:** `assets` | **Status:** 🔴 Red (Planned)
| Tool | Description |
|---|---|
| `intune_get_autopilot_devices` | Lists all Windows Autopilot device registrations in Intune. |
| `intune_get_managed_device` | Retrieves full details for a single Intune managed device by its device ID or device name. |
| `intune_get_noncompliant_devices` | Returns all Intune-managed devices currently in a non-compliant state. |
| `intune_list_apps` | Lists managed applications deployed through Intune mobile app management. |
| `intune_list_compliance_policies` | Lists the device compliance policies configured in Intune. |
| `intune_list_configuration_profiles` | Lists the device configuration profiles configured in Intune. |
| `intune_list_managed_devices` | Lists all devices enrolled in Microsoft Intune with key health and compliance attributes. |
---
## Lansweeper
**Shard:** `assets` | **Status:** 🔴 Red (Planned)
| Tool | Description |
|---|---|
| `lansweeper_get_asset` | Retrieves full inventory details for a single Lansweeper asset by its asset ID. |
| `lansweeper_get_software` | Lists all installed software (name, version, publisher) on a given Lansweeper asset. |
| `lansweeper_list_assets` | Lists assets from Lansweeper with optional filtering by asset type (e.g. Windows, Linux, Network Device). |
| `lansweeper_search_assets` | Searches Lansweeper assets by name, IP address, or serial number fragment and returns matching records. |
---
## Workday
**Shard:** `workday` | **Status:** 🟡 Yellow (NEXUS-009)
| Tool | Description |
|---|---|
| `workday_find_worker_by_email` | Finds a Workday worker record by their primary work email address. |
| `workday_get_compensation` | Retrieves compensation details (grade, salary band) for a worker by their Workday ID. |
| `workday_get_worker` | Retrieves full details for a single Workday worker by their Workday worker ID. |
| `workday_list_organizations` | Lists supervisory organisations in the Workday tenant. |
| `workday_list_positions` | Lists open and filled positions in Workday HCM. |
| `workday_list_workers` | Lists workers from Workday HCM with support for pagination via `limit` and `offset`. |
| `workday_run_raas_report` | Executes a Workday Report-as-a-Service (RaaS) custom report by path and returns the result rows. |
---
## Summary
| Service | Shard | Status | Tool count |
|---|---|---|---|
| Active Directory | `identity` | 🟢 Green | 7 |
| Audit (cross-system) | `audit` / `main.py` | 🟢 Green | 6 |
| BMC Helix (ITSM) | `itsm` | 🔴 Planned | 6 |
| FedEx | `logistics` | 🔴 Planned | 5 |
| Microsoft Entra ID | `identity` | 🟢 Green | 8 |
| Microsoft Intune | `assets` | 🔴 Planned | 7 |
| Lansweeper | `assets` | 🔴 Planned | 4 |
| Workday | `workday` | 🟡 In progress | 7 |
| **Total** | | | **50** |
---
*Generated: 2026-04-14 | Source: `nexus-mcp/src/shards/` + `nexus-mcp/src/main.py`*
documentation/README.md
-270
View File
@@ -1,270 +0,0 @@
# Nexus-MCP — Enterprise Integration Server
Sharded Model Context Protocol server for enterprise systems.
Each shard is self-contained and can be toggled independently via feature flags.
---
<!-- STATUS_PAGE:BEGIN -->
## Status Page (Managed)
| Field | Value |
|---|---|
| Last Updated | 2026-04-13 |
| Latest Session Snapshot | SESSION_SNAPSHOT_2026-04-13.md |
| Change Signal | No staged files |
| Components Affected | none |
| TODO/RESTART Markers | none |
| BREAKING CHANGE (compose ports/volumes) | No |
## Shard Status Board (Traffic Light)
| Shard | System(s) | Status | NEXUS Ref | Flag | Standard Gate |
|---|---|---|---|---|---|
| identity | Active Directory + Entra ID | 🟢 Green | NEXUS-017 | ENABLE_IDENTITY | Tool tests passing |
| workday | Workday HCM | 🟡 Yellow | NEXUS-009 | ENABLE_WORKDAY | Credentials + live validation pending |
| audit | Cross-system drift + reporting | 🟡 Yellow | NEXUS-018 | ENABLE_AUDIT | Verification maturing |
| itsm | BMC Helix ITSM | 🔴 Red | NEXUS-021 | ENABLE_ITSM | Stub only |
| assets | Lansweeper + Intune | 🔴 Red | NEXUS-022 | ENABLE_ASSETS | Stub only |
| logistics | FedEx | 🔴 Red | NEXUS-023 | ENABLE_LOGISTICS | Stub only |
## Discipline Drives Quality
| Pillar | Target Standard | Current Signal |
|---|---|---|
| Type Hinting | Public interfaces typed | 🟢 Pydantic-based schemas in place |
| Pylance | Zero-error baseline | 🟡 Enforced goal, pending full workspace sweep |
| Modular Structure | Orchestrator -> shards -> adapters | 🟢 Applied in current architecture |
| Test Gates | Pre-push tests + validation | 🟢 Active local gate |
| Security Logging | SOC 2 audit trail with redaction | 🟢 Active |
## Sprint Traceability (2026)
| NEXUS ID | Area | Status |
|---|---|---|
| NEXUS-009 | Workday integration | 🟡 In progress |
| NEXUS-017 | Identity integration | 🟢 Production-ready |
| NEXUS-018 | Audit capability | 🟡 In progress |
| NEXUS-021 | ITSM shard | 🔴 Planned |
| NEXUS-022 | Assets shard | 🔴 Planned |
| NEXUS-023 | Logistics shard | 🔴 Planned |
<!-- STATUS_PAGE:END -->
## Folder Structure
```
nexus-mcp/
├── src/
│ ├── main.py # Core Orchestrator — reads flags, loads shards
│ └── shards/ # The 6 Shards (one file = one system domain)
│ ├── __init__.py
│ ├── identity.py # 🟢 AD & Entra tools
│ ├── workday.py # 🟡 Worker & Org tools
│ ├── itsm.py # 🔴 BMC Helix tools
│ ├── assets.py # 🔴 Lansweeper + Intune tools
│ ├── logistics.py # 🔴 FedEx tools
│ └── audit.py # 🟡 Cross-system drift + reporting
├── lib/ # Low-level system adapters (no tool logic here)
│ ├── config.py
│ ├── ad_adapter.py # LDAP/AD connection wrapper
│ ├── entra_client.py # Microsoft Graph (Entra)
│ ├── workday_client.py # Workday REST + OAuth2
│ ├── helix_client.py # BMC Helix AR-JWT auth
│ ├── lansweeper_client.py # Lansweeper GraphQL
│ ├── intune_client.py # Microsoft Graph (Intune)
│ └── fedex_client.py # FedEx REST + OAuth2
├── tests/
├── .env # Feature flags + credentials
├── .env.example # Template — copy this to .env
└── README.md
```
---
## Architecture: The Shard Contract
Every shard file exposes exactly one function:
```python
def register(mcp: FastMCP) -> None:
@mcp.tool()
async def my_tool(...) -> ...:
"""Tool docstring visible to the LLM."""
...
```
The orchestrator (`src/main.py`) reads feature flags and calls `register(mcp)` for each enabled shard. **No other file is changed to add or remove a shard.**
### Adding a new shard
1. Create `src/shards/my_system.py` following the template above.
2. Add the adapter to `lib/` if needed.
3. Add one line to `src/main.py`:
```python
from shards import my_system
if _enabled("MY_SYSTEM"):
my_system.register(mcp)
```
4. Add `ENABLE_MY_SYSTEM=true` to `.env`.
### Holding pattern
Leave a shard unregistered (or set flag to `false`) to hold it without breaking anything:
```python
# 🔴 Planned — credentials not yet available
# if _enabled("MY_SYSTEM"):
# my_system.register(mcp)
```
---
## Tools Reference
### Identity shard (🟢)
| Tool | Description |
|---|---|
| `ad_get_user` | Look up AD user by sAMAccountName |
| `ad_get_user_by_email` | Look up AD user by email |
| `ad_search_users` | Search AD by display name fragment |
| `ad_list_groups` | List all AD groups |
| `ad_get_group_members` | Members of a group by DN |
| `ad_get_disabled_accounts` | All disabled AD accounts |
| `ad_get_stale_accounts` | Accounts inactive beyond N days |
| `entra_list_users` | List Entra ID users |
| `entra_get_user` | Get user by ID or UPN |
| `entra_list_groups` | List Entra groups |
| `entra_get_group_members` | Members of an Entra group |
| `entra_list_service_principals` | List app registrations |
| `entra_get_conditional_access_policies` | List CA policies |
| `entra_get_signin_logs` | Recent sign-in logs |
| `entra_get_risky_users` | Identity Protection risky users |
### Workday shard (🟡)
| Tool | Description |
|---|---|
| `workday_list_workers` | Paginated worker list |
| `workday_get_worker` | Worker by Workday ID |
| `workday_find_worker_by_email` | Worker lookup by email |
| `workday_list_positions` | Open and filled positions |
| `workday_get_compensation` | Compensation details |
| `workday_list_organizations` | Supervisory orgs |
| `workday_run_raas_report` | Execute a RaaS custom report |
### ITSM shard (🔴)
| Tool | Description |
|---|---|
| `helix_list_incidents` | Incidents (filterable by status/assignee) |
| `helix_get_incident` | Incident by Entry ID |
| `helix_list_changes` | Change requests |
| `helix_get_problem` | Problem investigation ticket |
| `helix_search_cmdb` | CMDB CI search by name |
| `helix_list_cmdb_assets` | Hardware assets from CMDB |
### Assets shard (🔴)
| Tool | Description |
|---|---|
| `lansweeper_list_assets` | Asset list (filterable by type) |
| `lansweeper_get_asset` | Asset by ID |
| `lansweeper_get_software` | Installed software on asset |
| `lansweeper_search_assets` | Search by name/IP/serial |
| `intune_list_managed_devices` | Managed device inventory |
| `intune_get_managed_device` | Device by ID |
| `intune_get_noncompliant_devices` | Non-compliant devices |
| `intune_list_compliance_policies` | Compliance policies |
| `intune_list_configuration_profiles` | Config profiles |
| `intune_list_apps` | Deployed app list |
| `intune_get_autopilot_devices` | Autopilot registrations |
### Logistics shard (🔴)
| Tool | Description |
|---|---|
| `fedex_track_shipment` | Track by tracking number |
| `fedex_track_multiple` | Track up to 30 at once |
| `fedex_get_shipment_events` | Scan event history |
| `fedex_validate_address` | Address validation |
| `fedex_get_rates` | Rate quote between postal codes |
### Audit shard (🟡)
| Tool | Description | Execution |
|---|---|---|
| `audit_user_drift` | Single user across Workday / AD / Entra | Async |
| `audit_bulk_user_drift` | Up to 50 users concurrently | Async |
| `audit_device_drift` | Single device across Lansweeper / Intune / Helix | Async |
| `audit_entra_ad_sync_drift` | Full Entra→AD sync scan | Async |
| `audit_intune_lansweeper_device_drift` | Intune vs Lansweeper reconciliation | Async |
| `generate_weekly_report` | Full weekly cross-system report | Async |
| `generate_compliance_report` | Device + identity risk snapshot | Async |
| `generate_asset_reconciliation_report` | Intune vs Lansweeper diff | Async |
| `generate_itsm_weekly_summary` | Helix ticket volume summary | Async |
| `nexus_audit_recent` | Query recent audit events (last N days) | Sync |
| `nexus_audit_stats` | Aggregate statistics on audit activity | Sync |
**Recent Improvements (2026-04-13):**
- ✅ Async execution for all drift detection scans
- ✅ MCP protocol verification script (`verify_mcp_protocol.py`)
- ✅ Resilience layer with retry logic and graceful degradation
---
## Setup
```bash
cd nexus-mcp
cp .env.example .env # fill in credentials and set feature flags
pip install -e .
python src/main.py # or: nexus-mcp
```
## Claude Desktop Config
```json
{
"mcpServers": {
"nexus": {
"command": "python",
"args": ["src/main.py"],
"cwd": "/path/to/nexus-mcp"
}
}
}Sprint Status & Next Steps
### ✅ Recently Completed (2026-04-13)
- Async audit execution for high-volume scans
- Enterprise resilience framework (retry logic, circuit breakers)
- Pydantic schema standardization for cross-system data
- Code health report with actionable improvements
### 🟡 In Progress
- **Pytest validation** of all 33 tools against live APIs
- **Workday API credential approval** (NEXUS-009)
- **Claude Desktop integration testing** with updated config
### 🔴 Blocked / Pending Approval
- **ITSM shard (BMC Helix):** AR-JWT credentials pending
- **Assets shard (Lansweeper + Intune):** GraphQL + Graph API setup
- **Logistics shard (FedEx):** OAuth2 client registration
---
## Required Permissions
See [Local-Setup.md](Local-Setup.md) for the full permission matrix and credential configuration guide
All credentials can live in `nexus-mcp/.env` — no need to put them in the Claude config.
---
## Required Permissions
See [Local-Setup.md](Local-Setup.md) for the full permission matrix for each system.
The same requirements apply here — Nexus-MCP is a refactor of that server,
not a new system.