From dec6f4d2ff39d610da1c608ae714f8c82975908e Mon Sep 17 00:00:00 2001 From: nathan Date: Tue, 14 Apr 2026 15:14:17 -0400 Subject: [PATCH] Refactor documentation: Remove outdated README and Tool Inventory, add comprehensive DEMO_GUIDE and new Tool Inventory file --- documentation/DEMO_GUIDE.md => DEMO_GUIDE.md | 0 README.md | 356 ++++++++++++------ ...P - Tool Inventory.md => TOOL_INVENTORY.md | 0 documentation/README.md | 270 ------------- 4 files changed, 244 insertions(+), 382 deletions(-) rename documentation/DEMO_GUIDE.md => DEMO_GUIDE.md (100%) rename documentation/Nexus MCP - Tool Inventory.md => TOOL_INVENTORY.md (100%) delete mode 100644 documentation/README.md diff --git a/documentation/DEMO_GUIDE.md b/DEMO_GUIDE.md similarity index 100% rename from documentation/DEMO_GUIDE.md rename to DEMO_GUIDE.md diff --git a/README.md b/README.md index eec75a8..63af5a2 100644 --- a/README.md +++ b/README.md @@ -1,118 +1,231 @@ -# Nexus-MCP status page +# Nexus-MCP β€” Enterprise Integration Server -**Updated:** 2026-04-13 +Sharded Model Context Protocol server for enterprise systems. +Each shard is self-contained and can be toggled independently via feature flags. -This page is the high-visibility execution status for Nexus-MCP, the sharded enterprise integration server supporting 53 tools across 9 system categories. +--- -## Traffic-light legend + +## Status Page (Managed) -| Status | Meaning | -| --- | --- | -| 🟒 Green | Functional / production-ready | -| 🟑 Yellow | In progress / development | -| πŸ”΄ Red | Blocked / not started | +| 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 | -## Nexus-MCP shard status board +## Shard Status Board (Traffic Light) -Each shard is independently toggleable via feature flags. Shards load only when their `ENABLE_*` flag is set to `true` in `.env`. - -| Shard | System(s) | Tools | Status | Notes | Flag | +| Shard | System(s) | Status | NEXUS Ref | Flag | Standard Gate | |---|---|---|---|---|---| -| `identity` | Active Directory + Entra ID | 15 | 🟒 Green | Fully functional with AD live adapter | `ENABLE_IDENTITY` | -| `workday` | Workday HCM | 7 | 🟒 Green | Production-ready with mock & live modes | `ENABLE_WORKDAY` | -| `audit` | Cross-system drift | 9 | 🟑 Yellow | Minimal stub (restored 2026-04-13 for startup stability) | `ENABLE_AUDIT` | -| `itsm` | BMC Helix ITSM | 6 | πŸ”΄ Red | Placeholder pending credentials | `ENABLE_ITSM` | -| `assets` | Lansweeper + Intune | 11 | πŸ”΄ Red | Placeholder pending credentials | `ENABLE_ASSETS` | -| `logistics` | FedEx | 5 | πŸ”΄ Red | Placeholder pending credentials | `ENABLE_LOGISTICS` | +| 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 | -**Architecture:** Plugin-based sharded model β€” each shard is a self-contained module (`src/shards/*.py`) that registers its tools via a `register(mcp)` function. The orchestrator (`src/main.py`) checks feature flags and loads only enabled shards. This allows piece-at-a-time deployment without touching the core server code. +## Discipline Drives Quality -## Architecture wins +| 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 | -| Engineering discipline pillar | Current state | Evidence | -| --- | --- | --- | -| Enterprise resilience (tenacity) | 🟒 Green | All HTTP clients wrapped with automatic retry (exponential backoff 2sβ†’4sβ†’8s), circuit breaker pattern, graceful degradation. Retries 5xx/timeouts only (not 4xx). | -| Atomic deployment discipline | 🟒 Green | Each shard can be deployed independently via feature flags without risk to other shards. | -| Type hinting discipline | 🟒 Green | All shards and lib/ adapters use typed return contracts per repository standards. | -| Modular architecture discipline | 🟒 Green | Orchestrator (main.py), shards (tools), lib/ (adapters) cleanly separated β€” no cross-contamination. | -| Mock-mode discipline | 🟒 Green | USE_MOCK flag enables full testing without credentials (lib/mock_data.py with realistic drift scenarios). | -| SOC 2 audit logging | 🟒 Green | Automatic JSONL audit trail with PII redaction for every tool invocation (CC7.2 / CC6.1). | -| Traceability discipline | 🟒 Green | Commits, PRs, and session snapshots tracked. Feature flags and shard status mapped to roadmap priorities. | +## Sprint Traceability (2026) -## Execution roadmap +| 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 | + -| Workstream | Status | Notes | Next steps | -| --- | --- | --- | --- | -| **Core shards (Identity + Workday + Audit)** | 🟒 Green | Nexus-MCP sharded architecture fully operational. Server loads all 6 shards. Identity/Workday functional; Audit stubbed pending full implementation. | Complete audit tools implementation; run pytest validation suite. | -| **Enterprise resilience layer** | 🟒 Green | Retry logic, circuit breaker, and graceful degradation implemented across all HTTP clients. Automated testing validates 4xx vs 5xx distinction. | Monitor production behavior; gather metrics on retry/circuit breaker events. | -| **API/credentials transition** | 🟑 Yellow | Live AD backend working. Workday API and Entra Graph API awaiting credential approval (WIS-001, WIS-008 "Holding Pattern"). | Provision API tokens; activate live modes in Workday and Entra shards. | -| **Extended shards (ITSM + Assets + Logistics)** | πŸ”΄ Red | Stub shards created as placeholders. Await credential provisioning and client library development. | Design client adapters; implement stub tools for Helix, Lansweeper, Intune, FedEx. | +## Folder Structure -## Latest changes (2026-04-13) - -**βœ… Server startup stabilized** β€” All shards loading successfully -- Fixed broken audit shard that prevented server initialization (commit 8240d1b) -- Audit module temporarily uses minimal stub pending full implementation -- All 6 shards (identity, workday, audit, itsm, assets, logistics) now register correctly - -**πŸ“š Enterprise resilience layer added** -- Implemented automatic retry logic with exponential backoff (tenacity library) -- Circuit breaker pattern prevents cascading failures -- Graceful degradation in audit tools β€” continues with available systems if some fail -- Health check tool added for proactive monitoring (commit 15a0007) - -**πŸ”§ Stability improvements** -- Fixed retry logic: Now correctly retries 5xx/timeouts but NOT 4xx errors -- Updated deprecated datetime calls for Python 3.14+ compatibility -- All HTTP clients (Workday, Entra, AD, Intune, Lansweeper, FedEx, Helix) wrapped with resilience decorators - -## Recent activity (from git history) - -- Added local development quick-start and operational startup guidance. -- Added formalized README update prompt for repeatable status refreshes. -- Refined Workday runtime modular structure and validated three core tools. -- Completed type-hint quality refinements consistent with Pylance discipline. -- Added four mismatch-detection tools for status, title, department, and name variance review. -- Added focused pytest coverage for Workday mismatch scans and MCP wrappers. - -## Next milestones - -| Milestone | ID | Status | Exit criteria | -| --- | --- | --- | --- | -| Nexus-MCP verification | Integration | 🟑 Yellow | All mock-mode tools tested; pytest passes; Pylance zero errors; SOC 2 audit log verified | -| Live credential integration | WIS-008, WIS-001-003 | πŸ”΄ Red | Non-prod credentials approved, Entra + Workday API backends operational | -| Extended shard activation | Phase 2 | πŸ”΄ Red | ITSM, Assets, Logistics shards transition from Red to Yellow with stub client implementations | - -## Reference documents - -### Nexus-MCP core - -- [Nexus-MCP comprehensive README](nexus-mcp/README.md) β€” full tool reference, shard architecture, and API docs -- [Local setup guide](nexus-mcp/Local-Setup.md) β€” installation, configuration, feature flags, and troubleshooting -- [Nexus orchestrator](nexus-mcp/src/main.py) β€” feature flag logic and shard loader -- [SOC 2 audit logger](nexus-mcp/lib/audit_log.py) β€” automatic PII redaction and JSONL event writer - -### Legacy implementation (archived for reference) - -- [Identity MCP server](Identity/identity_mcp_server.py) β€” original AD tool implementation (see identity shard) -- [Workday MCP server](Workday/workday-mcp/server.py) β€” original worker + drift tools (see workday + audit shards) -- [Workday execution backlog](Workday/Planning/workday-ad-identity-sync-next-steps.md) -- [Workday sprint board](Workday/Planning/workday-ad-identity-sync-sprint-board.md) -- [Workday implementation plan](Workday/Planning/workday-mcp-implementation-plan -```bash -cd nexus-mcp -python -m venv .venv -source .venv/Scripts/activate # Windows: .venv\Scripts\Activate.ps1 -pip install -e . -cp .env.example .env - -# Edit .env: set USE_MOCK=true -python src/main.py +``` +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 ``` -See [nexus-mcp/Local-Setup.md](nexus-mcp/Local-Setup.md) for full installation guide. +--- -### Claude Desktop configuration +## 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 { @@ -120,19 +233,38 @@ See [nexus-mcp/Local-Setup.md](nexus-mcp/Local-Setup.md) for full installation g "nexus": { "command": "python", "args": ["src/main.py"], - "cwd": "/path/to/mcp_servers/nexus-mcp", - "env": { - "USE_MOCK": "true" - } + "cwd": "/path/to/nexus-mcp" } } -} -``` +}Sprint Status & Next Steps -Restart Claude Desktop to load the Nexus tool -- [Workday execution backlog](Workday/Planning/workday-ad-identity-sync-next-steps.md) -- [Workday sprint board](Workday/Planning/workday-ad-identity-sync-sprint-board.md) -- [Workday implementation plan](Workday/Planning/workday-mcp-implementation-plan.md) -- [Workday installation guide](Workday/Planning/workday-mcp-install-guide.md) -- [Workday runtime entrypoint](Workday/workday-mcp/server.py) -- [Operational startup guidance](Local%20Setup.md) +### βœ… 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. diff --git a/documentation/Nexus MCP - Tool Inventory.md b/TOOL_INVENTORY.md similarity index 100% rename from documentation/Nexus MCP - Tool Inventory.md rename to TOOL_INVENTORY.md diff --git a/documentation/README.md b/documentation/README.md deleted file mode 100644 index 63af5a2..0000000 --- a/documentation/README.md +++ /dev/null @@ -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 (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 | - - -## 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.