nexus-mcp/README.md

# Nexus-MCP status page

**Updated:** 2026-04-13

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 | Meaning |
| --- | --- |
| 🟢 Green | Functional / production-ready |
| 🟡 Yellow | In progress / development |
| 🔴 Red | Blocked / not started |

## Nexus-MCP shard status board

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

**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.

## Architecture wins

| 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. |

## Execution roadmap

| 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. |

## 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
```

See [nexus-mcp/Local-Setup.md](nexus-mcp/Local-Setup.md) for full installation guide.

### Claude Desktop configuration

```json
{
  "mcpServers": {
    "nexus": {
      "command": "python",
      "args": ["src/main.py"],
      "cwd": "/path/to/mcp_servers/nexus-mcp",
      "env": {
        "USE_MOCK": "true"
      }
    }
  }
}
```

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)