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

feat(docs): update tool inventory and add resilience documentation

Browse Source 
- 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.
This commit is contained in:
nathan 2026-04-14 14:53:02 -04:00
parent 5c90bdbd04
commit e6e4810e47
8 changed files with 126 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
nexus-mcp/DEMO_GUIDE.md → documentation/DEMO_GUIDE.md
View File

0
nexus-mcp/Local-Setup.md → documentation/Local-Setup.md
View File

10
documentation/Nexus MCP - Tool Inventory.md
View File

@ -6,12 +6,12 @@ A complete reference of every service and tool currently registered in the Nexus
## Active Directory ## Active Directory
**Shard:** `identity` | **Status:** 🟢 Green (WIS-017) **Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `ad_get_disabled_accounts` | Returns all disabled user accounts in Active Directory (userAccountControl = 514). | | `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 (DN). | | `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_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` | 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_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 ## Microsoft Entra ID
**Shard:** `identity` | **Status:** 🟢 Green (WIS-017) **Shard:** `identity` | **Status:** 🟢 Green (NEXUS-017)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
@ -112,7 +112,7 @@ A complete reference of every service and tool currently registered in the Nexus
## Workday ## Workday
**Shard:** `workday` | **Status:** 🟡 Yellow (WIS-009) **Shard:** `workday` | **Status:** 🟡 Yellow (NEXUS-009)
| Tool | Description | | Tool | Description |
|---|---| |---|---|

40
nexus-mcp/README.md → documentation/README.md
View File

@ -19,14 +19,14 @@ Each shard is self-contained and can be toggled independently via feature flags.
## Shard Status Board (Traffic Light) ## 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 | | identity | Active Directory + Entra ID | 🟢 Green | NEXUS-017 | ENABLE_IDENTITY | Tool tests passing |
| workday | Workday HCM | 🟡 Yellow | WIS-009 | ENABLE_WORKDAY | Credentials + live validation pending | | workday | Workday HCM | 🟡 Yellow | NEXUS-009 | ENABLE_WORKDAY | Credentials + live validation pending |
| audit | Cross-system drift + reporting | 🟡 Yellow | WIS-018 | ENABLE_AUDIT | Verification maturing | | audit | Cross-system drift + reporting | 🟡 Yellow | NEXUS-018 | ENABLE_AUDIT | Verification maturing |
| itsm | BMC Helix ITSM | 🔴 Red | WIS-021 | ENABLE_ITSM | Stub only | | itsm | BMC Helix ITSM | 🔴 Red | NEXUS-021 | ENABLE_ITSM | Stub only |
| assets | Lansweeper + Intune | 🔴 Red | WIS-022 | ENABLE_ASSETS | Stub only | | assets | Lansweeper + Intune | 🔴 Red | NEXUS-022 | ENABLE_ASSETS | Stub only |
| logistics | FedEx | 🔴 Red | WIS-023 | ENABLE_LOGISTICS | Stub only | | logistics | FedEx | 🔴 Red | NEXUS-023 | ENABLE_LOGISTICS | Stub only |
## Discipline Drives Quality ## Discipline Drives Quality
@ -40,17 +40,16 @@ Each shard is self-contained and can be toggled independently via feature flags.
## Sprint Traceability (2026) ## Sprint Traceability (2026)
| WIS ID | Area | Status | | NEXUS ID | Area | Status |
|---|---|---| |---|---|---|
| WIS-009 | Workday integration | 🟡 In progress | | NEXUS-009 | Workday integration | 🟡 In progress |
| WIS-017 | Identity integration | 🟢 Production-ready | | NEXUS-017 | Identity integration | 🟢 Production-ready |
| WIS-018 | Audit capability | 🟡 In progress | | NEXUS-018 | Audit capability | 🟡 In progress |
| WIS-021 | ITSM shard | 🔴 Planned | | NEXUS-021 | ITSM shard | 🔴 Planned |
| WIS-022 | Assets shard | 🔴 Planned | | NEXUS-022 | Assets shard | 🔴 Planned |
| WIS-023 | Logistics shard | 🔴 Planned | | NEXUS-023 | Logistics shard | 🔴 Planned |
<!-- STATUS_PAGE:END --> <!-- STATUS_PAGE:END -->
## Folder Structure ## 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. 1. Create `src/shards/my_system.py` following the template above.
2. Add the adapter to `lib/` if needed. 2. Add the adapter to `lib/` if needed.
3. Add one line to `src/main.py`: 3. Add one line to `src/main.py`:
```python ```python
from shards import my_system from shards import my_system
if _enabled("MY_SYSTEM"): if _enabled("MY_SYSTEM"):
my_system.register(mcp) my_system.register(mcp)
``` ```
4. Add `ENABLE_MY_SYSTEM=true` to `.env`. 4. Add `ENABLE_MY_SYSTEM=true` to `.env`.
### Holding pattern ### Holding pattern
@ -123,6 +124,7 @@ Leave a shard unregistered (or set flag to `false`) to hold it without breaking
## Tools Reference ## Tools Reference
### Identity shard (🟢) ### Identity shard (🟢)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `ad_get_user` | Look up AD user by sAMAccountName | | `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 | | `entra_get_risky_users` | Identity Protection risky users |
### Workday shard (🟡) ### Workday shard (🟡)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `workday_list_workers` | Paginated worker list | | `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 | | `workday_run_raas_report` | Execute a RaaS custom report |
### ITSM shard (🔴) ### ITSM shard (🔴)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `helix_list_incidents` | Incidents (filterable by status/assignee) | | `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 | | `helix_list_cmdb_assets` | Hardware assets from CMDB |
### Assets shard (🔴) ### Assets shard (🔴)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `lansweeper_list_assets` | Asset list (filterable by type) | | `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 | | `intune_get_autopilot_devices` | Autopilot registrations |
### Logistics shard (🔴) ### Logistics shard (🔴)
| Tool | Description | | Tool | Description |
|---|---| |---|---|
| `fedex_track_shipment` | Track by tracking number | | `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 | | `fedex_get_rates` | Rate quote between postal codes |
### Audit shard (🟡) ### Audit shard (🟡)
| Tool | Description | Execution | | Tool | Description | Execution |
|---|---|---| |---|---|---|
| `audit_user_drift` | Single user across Workday / AD / Entra | Async | | `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 | | `nexus_audit_stats` | Aggregate statistics on audit activity | Sync |
**Recent Improvements (2026-04-13):** **Recent Improvements (2026-04-13):**
- ✅ Async execution for all drift detection scans - ✅ Async execution for all drift detection scans
- ✅ MCP protocol verification script (`verify_mcp_protocol.py`) - ✅ MCP protocol verification script (`verify_mcp_protocol.py`)
- ✅ Resilience layer with retry logic and graceful degradation - ✅ Resilience layer with retry logic and graceful degradation
@ -238,7 +246,7 @@ python src/main.py # or: nexus-mcp
### 🟡 In Progress ### 🟡 In Progress
- **Pytest validation** of all 33 tools against live APIs - **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 - **Claude Desktop integration testing** with updated config
### 🔴 Blocked / Pending Approval ### 🔴 Blocked / Pending Approval

0
nexus-mcp/RESILIENCE.md → documentation/RESILIENCE.md
View File

0
nexus-mcp/TEST_VALIDATION_REPORT.md → documentation/TEST_VALIDATION_REPORT.md
View File

83
documentation/nexus-work-item-register.md Normal file
View File

@ -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`) |

28
scripts/update_readme_status.py
View File

@ -134,14 +134,14 @@ def render_status_block(
## Shard Status Board (Traffic Light) ## 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 | | identity | Active Directory + Entra ID | 🟢 Green | NEXUS-017 | ENABLE_IDENTITY | Tool tests passing |
| workday | Workday HCM | 🟡 Yellow | WIS-009 | ENABLE_WORKDAY | Credentials + live validation pending | | workday | Workday HCM | 🟡 Yellow | NEXUS-009 | ENABLE_WORKDAY | Credentials + live validation pending |
| audit | Cross-system drift + reporting | 🟡 Yellow | WIS-018 | ENABLE_AUDIT | Verification maturing | | audit | Cross-system drift + reporting | 🟡 Yellow | NEXUS-018 | ENABLE_AUDIT | Verification maturing |
| itsm | BMC Helix ITSM | 🔴 Red | WIS-021 | ENABLE_ITSM | Stub only | | itsm | BMC Helix ITSM | 🔴 Red | NEXUS-021 | ENABLE_ITSM | Stub only |
| assets | Lansweeper + Intune | 🔴 Red | WIS-022 | ENABLE_ASSETS | Stub only | | assets | Lansweeper + Intune | 🔴 Red | NEXUS-022 | ENABLE_ASSETS | Stub only |
| logistics | FedEx | 🔴 Red | WIS-023 | ENABLE_LOGISTICS | Stub only | | logistics | FedEx | 🔴 Red | NEXUS-023 | ENABLE_LOGISTICS | Stub only |
## Discipline Drives Quality ## Discipline Drives Quality
@ -155,14 +155,14 @@ def render_status_block(
## Sprint Traceability (2026) ## Sprint Traceability (2026)
| WIS ID | Area | Status | | NEXUS ID | Area | Status |
|---|---|---| |---|---|---|
| WIS-009 | Workday integration | 🟡 In progress | | NEXUS-009 | Workday integration | 🟡 In progress |
| WIS-017 | Identity integration | 🟢 Production-ready | | NEXUS-017 | Identity integration | 🟢 Production-ready |
| WIS-018 | Audit capability | 🟡 In progress | | NEXUS-018 | Audit capability | 🟡 In progress |
| WIS-021 | ITSM shard | 🔴 Planned | | NEXUS-021 | ITSM shard | 🔴 Planned |
| WIS-022 | Assets shard | 🔴 Planned | | NEXUS-022 | Assets shard | 🔴 Planned |
| WIS-023 | Logistics shard | 🔴 Planned | | NEXUS-023 | Logistics shard | 🔴 Planned |
{STATUS_END} {STATUS_END}
""" """