From e6e4810e47940930fe64b2a33ab561bad21c2f78 Mon Sep 17 00:00:00 2001 From: nathan Date: Tue, 14 Apr 2026 14:53:02 -0400 Subject: [PATCH] feat(docs): update tool inventory and add resilience documentation - Updated Nexus MCP Tool Inventory with new NEXUS references and improved tool descriptions. - Added comprehensive README.md for Nexus MCP, detailing architecture, folder structure, and tool references. - Introduced RESILIENCE.md to document the new enterprise system resilience features, including automatic retry logic and circuit breaker patterns. - Created TEST_VALIDATION_REPORT.md summarizing test results and server capabilities post-rebuild. - Established a canonical work item register (nexus-work-item-register.md) to track NEXUS-XXX work items and their statuses. - Updated scripts to reflect changes in work item references from WIS to NEXUS. --- {nexus-mcp => documentation}/DEMO_GUIDE.md | 0 {nexus-mcp => documentation}/Local-Setup.md | 0 documentation/Nexus MCP - Tool Inventory.md | 10 +-- {nexus-mcp => documentation}/README.md | 40 +++++---- {nexus-mcp => documentation}/RESILIENCE.md | 0 .../TEST_VALIDATION_REPORT.md | 0 documentation/nexus-work-item-register.md | 83 +++++++++++++++++++ scripts/update_readme_status.py | 28 +++---- 8 files changed, 126 insertions(+), 35 deletions(-) rename {nexus-mcp => documentation}/DEMO_GUIDE.md (100%) rename {nexus-mcp => documentation}/Local-Setup.md (100%) rename {nexus-mcp => documentation}/README.md (89%) rename {nexus-mcp => documentation}/RESILIENCE.md (100%) rename {nexus-mcp => documentation}/TEST_VALIDATION_REPORT.md (100%) create mode 100644 documentation/nexus-work-item-register.md diff --git a/nexus-mcp/DEMO_GUIDE.md b/documentation/DEMO_GUIDE.md similarity index 100% rename from nexus-mcp/DEMO_GUIDE.md rename to documentation/DEMO_GUIDE.md diff --git a/nexus-mcp/Local-Setup.md b/documentation/Local-Setup.md similarity index 100% rename from nexus-mcp/Local-Setup.md rename to documentation/Local-Setup.md diff --git a/documentation/Nexus MCP - Tool Inventory.md b/documentation/Nexus MCP - Tool Inventory.md index f825b5e..e4f4cf5 100644 --- a/documentation/Nexus MCP - Tool Inventory.md +++ b/documentation/Nexus MCP - Tool Inventory.md @@ -6,12 +6,12 @@ A complete reference of every service and tool currently registered in the Nexus ## Active Directory -**Shard:** `identity` | **Status:** 🟢 Green (WIS-017) +**Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017) | Tool | Description | |---|---| -| `ad_get_disabled_accounts` | Returns all disabled user accounts in Active Directory (userAccountControl = 514). | -| `ad_get_group_members` | Returns all members of an AD group by its distinguished name (DN). | +| `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. | @@ -66,7 +66,7 @@ A complete reference of every service and tool currently registered in the Nexus ## Microsoft Entra ID -**Shard:** `identity` | **Status:** 🟢 Green (WIS-017) +**Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017) | Tool | Description | |---|---| @@ -112,7 +112,7 @@ A complete reference of every service and tool currently registered in the Nexus ## Workday -**Shard:** `workday` | **Status:** 🟡 Yellow (WIS-009) +**Shard:** `workday` | **Status:** 🟡 Yellow (NEXUS-009) | Tool | Description | |---|---| diff --git a/nexus-mcp/README.md b/documentation/README.md similarity index 89% rename from nexus-mcp/README.md rename to documentation/README.md index 81c8c0d..63af5a2 100644 --- a/nexus-mcp/README.md +++ b/documentation/README.md @@ -19,14 +19,14 @@ Each shard is self-contained and can be toggled independently via feature flags. ## Shard Status Board (Traffic Light) -| Shard | System(s) | Status | WIS Ref | Flag | Standard Gate | +| Shard | System(s) | Status | NEXUS Ref | Flag | Standard Gate | |---|---|---|---|---|---| -| identity | Active Directory + Entra ID | 🟢 Green | WIS-017 | ENABLE_IDENTITY | Tool tests passing | -| workday | Workday HCM | 🟡 Yellow | WIS-009 | ENABLE_WORKDAY | Credentials + live validation pending | -| audit | Cross-system drift + reporting | 🟡 Yellow | WIS-018 | ENABLE_AUDIT | Verification maturing | -| itsm | BMC Helix ITSM | 🔴 Red | WIS-021 | ENABLE_ITSM | Stub only | -| assets | Lansweeper + Intune | 🔴 Red | WIS-022 | ENABLE_ASSETS | Stub only | -| logistics | FedEx | 🔴 Red | WIS-023 | ENABLE_LOGISTICS | Stub only | +| 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 @@ -40,17 +40,16 @@ Each shard is self-contained and can be toggled independently via feature flags. ## Sprint Traceability (2026) -| WIS ID | Area | Status | +| NEXUS ID | Area | Status | |---|---|---| -| WIS-009 | Workday integration | 🟡 In progress | -| WIS-017 | Identity integration | 🟢 Production-ready | -| WIS-018 | Audit capability | 🟡 In progress | -| WIS-021 | ITSM shard | 🔴 Planned | -| WIS-022 | Assets shard | 🔴 Planned | -| WIS-023 | Logistics shard | 🔴 Planned | +| 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 | - ## Folder Structure ``` @@ -101,11 +100,13 @@ The orchestrator (`src/main.py`) reads feature flags and calls `register(mcp)` f 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 @@ -123,6 +124,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking ## Tools Reference ### Identity shard (🟢) + | Tool | Description | |---|---| | `ad_get_user` | Look up AD user by sAMAccountName | @@ -142,6 +144,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `entra_get_risky_users` | Identity Protection risky users | ### Workday shard (🟡) + | Tool | Description | |---|---| | `workday_list_workers` | Paginated worker list | @@ -153,6 +156,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `workday_run_raas_report` | Execute a RaaS custom report | ### ITSM shard (🔴) + | Tool | Description | |---|---| | `helix_list_incidents` | Incidents (filterable by status/assignee) | @@ -163,6 +167,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `helix_list_cmdb_assets` | Hardware assets from CMDB | ### Assets shard (🔴) + | Tool | Description | |---|---| | `lansweeper_list_assets` | Asset list (filterable by type) | @@ -178,6 +183,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `intune_get_autopilot_devices` | Autopilot registrations | ### Logistics shard (🔴) + | Tool | Description | |---|---| | `fedex_track_shipment` | Track by tracking number | @@ -187,6 +193,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `fedex_get_rates` | Rate quote between postal codes | ### Audit shard (🟡) + | Tool | Description | Execution | |---|---|---| | `audit_user_drift` | Single user across Workday / AD / Entra | Async | @@ -202,6 +209,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking | `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 @@ -238,7 +246,7 @@ python src/main.py # or: nexus-mcp ### 🟡 In Progress - **Pytest validation** of all 33 tools against live APIs -- **Workday API credential approval** (WIS-009) +- **Workday API credential approval** (NEXUS-009) - **Claude Desktop integration testing** with updated config ### 🔴 Blocked / Pending Approval diff --git a/nexus-mcp/RESILIENCE.md b/documentation/RESILIENCE.md similarity index 100% rename from nexus-mcp/RESILIENCE.md rename to documentation/RESILIENCE.md diff --git a/nexus-mcp/TEST_VALIDATION_REPORT.md b/documentation/TEST_VALIDATION_REPORT.md similarity index 100% rename from nexus-mcp/TEST_VALIDATION_REPORT.md rename to documentation/TEST_VALIDATION_REPORT.md diff --git a/documentation/nexus-work-item-register.md b/documentation/nexus-work-item-register.md new file mode 100644 index 0000000..d71e3e1 --- /dev/null +++ b/documentation/nexus-work-item-register.md @@ -0,0 +1,83 @@ +# Nexus work item register + +Canonical registry for all NEXUS-XXX work items. This supersedes the original `WIS-XXX` numbering used during the Workday-AD Identity Sync planning phase. + +**ID format:** `NEXUS-NNN` (zero-padded to 3 digits) +**Source of truth:** This file. All other documents should reference NEXUS-XXX IDs. +**Legacy mapping:** Original IDs were `WIS-NNN` (same numbers, renamed for project scope clarity). + +--- + +## Shard assignments (current) + +These NEXUS IDs are actively used as shard tracking references in `nexus-mcp/README.md`: + +| NEXUS ID | Shard | System(s) | Status | +|---|---|---|---| +| NEXUS-009 | `workday` | Workday HCM | 🟡 In progress | +| NEXUS-017 | `identity` | Active Directory + Entra ID | 🟢 Production-ready | +| NEXUS-018 | `audit` | Cross-system drift + reporting | 🟡 In progress | +| NEXUS-021 | `itsm` | BMC Helix ITSM | 🔴 Planned | +| NEXUS-022 | `assets` | Lansweeper + Intune | 🔴 Planned | +| NEXUS-023 | `logistics` | FedEx | 🔴 Planned | + +--- + +## Full work item backlog + +Derived from `archive/Workday/Planning/workday-ad-identity-sync-sprint-board.md` (v1, 2026-04-03). +Original scope was Workday-AD identity sync; items have since been absorbed into the broader Nexus-MCP roadmap. + +| NEXUS ID | Priority | Work item | Dependency | Status | +|---|---|---|---|---| +| NEXUS-001 | P0 | Finalize OAuth grant type and token lifecycle policy | — | READY | +| NEXUS-002 | P0 | Provision non-prod Workday API credentials and tenant access | NEXUS-001 | READY | +| NEXUS-003 | P0 | Confirm ISU, security group, and domain read-only permissions | NEXUS-002 | READY | +| NEXUS-004 | P0 | Publish field allowlist and explicit denylist in version control | NEXUS-003 | READY | +| NEXUS-005 | P0 | Create endpoint mapping table for all Workday tools | NEXUS-004 | READY | +| NEXUS-006 | P1 | Scaffold Workday MCP project files to Identity parity | NEXUS-005 | DONE | +| NEXUS-007 | P1 | Implement memory backend with deterministic worker fixtures | NEXUS-006 | DONE | +| NEXUS-008 | P1 | Implement API backend token flow with secure secret loading | NEXUS-006, NEXUS-002 | IN_PROGRESS | +| NEXUS-009 | P1 | Implement and validate Workday shard tools | NEXUS-008, NEXUS-005 | IN_PROGRESS | +| NEXUS-010 | P1 | Add allowlist schema validation tests for all tool outputs | NEXUS-009, NEXUS-004 | READY | +| NEXUS-011 | P1 | Implement remaining Workday tools (worker, org, manager, effective dates) | NEXUS-009, NEXUS-010 | READY | +| NEXUS-012 | P1 | Add adapter resilience for 401/403/404/429/5xx with retry/timeouts | NEXUS-011 | DONE | +| NEXUS-013 | P2 | Define canonical correlation key precedence across Workday and AD | NEXUS-011 | READY | +| NEXUS-014 | P2 | Implement mismatch detector: terminated in Workday but active in AD | NEXUS-013 | DONE | +| NEXUS-015 | P2 | Implement mismatch detector: future-dated hire prematurely provisioned | NEXUS-013 | READY | +| NEXUS-016 | P2 | Implement mismatch detector: active worker missing in AD | NEXUS-013 | READY | +| NEXUS-017 | P2 | Identity shard: AD + Entra tools production-ready | NEXUS-013 | DONE | +| NEXUS-018 | P2 | Audit shard: cross-system drift detection and reporting | NEXUS-013 | IN_PROGRESS | +| NEXUS-019 | P3 | Build Power Automate daily sync flow (non-prod) | NEXUS-011, NEXUS-014–018 | READY | +| NEXUS-020 | P3 | Build Power Automate weekly drift reporting flow | NEXUS-019 | READY | +| NEXUS-021 | P3 | ITSM shard: BMC Helix incidents, changes, problems, CMDB | NEXUS-019, NEXUS-021 | READY | +| NEXUS-022 | P4 | Assets shard: Lansweeper + Intune device inventory | NEXUS-019, NEXUS-021 | READY | +| NEXUS-023 | P4 | Logistics shard: FedEx shipment tracking and address validation | NEXUS-014–018 | READY | +| NEXUS-024 | P4 | Implement rollback procedures and tests for each remediation action | NEXUS-023 | READY | +| NEXUS-025 | P5 | Instrument KPI baseline for Q1 2026 MTTP | Historical ticket access | READY | +| NEXUS-026 | P5 | Implement KPI dashboard metrics and weekly trend outputs | NEXUS-020, NEXUS-025 | READY | +| NEXUS-027 | P6 | Enable production logging/redaction and operational monitoring | NEXUS-012, NEXUS-026 | READY | +| NEXUS-028 | P6 | Execute pilot rollout and validate SLA/severity routing | NEXUS-022, NEXUS-027 | READY | +| NEXUS-029 | P7 | Production cutover and manual reconciliation retirement | NEXUS-028 | READY | +| NEXUS-030 | P7 | Q3 outcome verification and executive evidence pack | NEXUS-029 | READY | + +--- + +## Status key + +| Value | Meaning | +|---|---| +| `READY` | Not started; all dependencies met or waived | +| `IN_PROGRESS` | Actively being worked | +| `VALIDATING` | Implementation complete; under test/review | +| `BLOCKED` | Waiting on an external dependency | +| `DONE` | Accepted and closed | + +--- + +## Change log + +| Date | Change | +|---|---| +| 2026-04-14 | Register created; WIS-XXX IDs retired in favour of NEXUS-XXX | +| 2026-04-03 | Original sprint board authored (`workday-ad-identity-sync-sprint-board.md`) | diff --git a/scripts/update_readme_status.py b/scripts/update_readme_status.py index ea92416..996ef61 100644 --- a/scripts/update_readme_status.py +++ b/scripts/update_readme_status.py @@ -134,14 +134,14 @@ def render_status_block( ## Shard Status Board (Traffic Light) -| Shard | System(s) | Status | WIS Ref | Flag | Standard Gate | +| Shard | System(s) | Status | NEXUS Ref | Flag | Standard Gate | |---|---|---|---|---|---| -| identity | Active Directory + Entra ID | 🟢 Green | WIS-017 | ENABLE_IDENTITY | Tool tests passing | -| workday | Workday HCM | 🟡 Yellow | WIS-009 | ENABLE_WORKDAY | Credentials + live validation pending | -| audit | Cross-system drift + reporting | 🟡 Yellow | WIS-018 | ENABLE_AUDIT | Verification maturing | -| itsm | BMC Helix ITSM | 🔴 Red | WIS-021 | ENABLE_ITSM | Stub only | -| assets | Lansweeper + Intune | 🔴 Red | WIS-022 | ENABLE_ASSETS | Stub only | -| logistics | FedEx | 🔴 Red | WIS-023 | ENABLE_LOGISTICS | Stub only | +| 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 @@ -155,14 +155,14 @@ def render_status_block( ## Sprint Traceability (2026) -| WIS ID | Area | Status | +| NEXUS ID | Area | Status | |---|---|---| -| WIS-009 | Workday integration | 🟡 In progress | -| WIS-017 | Identity integration | 🟢 Production-ready | -| WIS-018 | Audit capability | 🟡 In progress | -| WIS-021 | ITSM shard | 🔴 Planned | -| WIS-022 | Assets shard | 🔴 Planned | -| WIS-023 | Logistics shard | 🔴 Planned | +| 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_END} """