nexus-mcp/CLAUDE.md

nexus-mcp

Self-hosted MCP server that bridges enterprise systems (Active Directory, Entra ID, Workday, BMC Helix ITSM, Lansweeper, Intune, FedEx) with LLM-based agents via the Model Context Protocol. Normalizes data into canonical schemas, detects cross-system inconsistencies, and logs every tool call for SOC 2 compliance.

Repository Layout

nexus-mcp/          # Main Python package
  src/
    main.py         # Orchestrator: loads enabled shards, applies audit middleware
    shards/         # One module per integration domain
      identity.py   # AD + Entra ID (15 tools) — live
      workday.py    # Workday HCM (12 tools) — integration in progress
      audit.py      # Cross-system drift scanning (6 tools) — live
      itsm.py       # BMC Helix ITSM — stub
      assets.py     # Lansweeper + Intune — stub
      logistics.py  # FedEx — stub
  lib/
    config.py       # Pydantic BaseSettings for all system credentials
    schemas.py      # Canonical data models (CanonicalUser, Device, Incident, …)
    adapters.py     # System API response → canonical schema transforms
    ad_adapter.py   # Production LDAP/Active Directory backend
    audit_log.py    # SOC 2 JSONL logger (append-only, auto-redacts secrets)
    drift_detection.py  # Cross-system mismatch scanning logic
    mock_data.py    # Synthetic test data with pre-seeded drift scenarios
    resilience.py   # Retry/timeout/circuit-breaker patterns
    *_client.py     # REST/GraphQL clients (Entra, Workday, Helix, Lansweeper, Intune, FedEx)
  tests/
    identity_tests/ # AD/Entra unit + integration tests
    workday_tests/  # Workday drift detection tests
    test_resilience.py
  .env.example      # All config keys with comments
  pyproject.toml    # Package config, entry point, test markers
  list_tools.py     # Browse all registered MCP tools
  verify_mcp_protocol.py  # Validate MCP compatibility
documentation/
scripts/
.github/
  agents/           # AI assistant instructions (Frank v6, Data Analyst, …)
  prompts/          # 30+ workflow automation prompts

Setup

cd nexus-mcp
python -m venv .venv
source .venv/bin/activate       # Windows: .\.venv\Scripts\Activate.ps1
pip install -e .

cp .env.example .env

Edit .env before starting. The key flags:

Variable	Purpose
USE_MOCK=true	Run all tools on synthetic data — no credentials needed
ENABLE_IDENTITY=true	Load the identity shard (AD + Entra)
ENABLE_WORKDAY=true	Load the Workday shard
ENABLE_AUDIT=true	Load the audit/drift shard
ENABLE_ITSM/ASSETS/LOGISTICS	Load stub shards
AUDIT_LOGGING_ENABLED=true	Write SOC 2 audit log to logs/nexus_audit.jsonl

For live mode, fill in the system-specific credential sections (AD, Entra, Workday, etc.) in .env.

Running

# From nexus-mcp/ directory
python -m main
# or after pip install -e .
nexus-mcp

Communicates via stdio (MCP protocol). Connect via any MCP-compatible client (Claude Desktop, VS Code extension, etc.). See documentation/VSCODE_INTEGRATION_GUIDE.md for IDE setup.

Testing

# All unit tests (integration tests skipped by default)
pytest

# Skip integration tests explicitly
pytest -m "not integration"

# With coverage
pytest --cov=src --cov=lib

# Single file
pytest tests/identity_tests/test_ad_adapter.py

# Browse all registered tools
python list_tools.py

# Verify MCP protocol compliance
python verify_mcp_protocol.py

# Watch audit log
tail -f logs/nexus_audit.jsonl

Mock mode (USE_MOCK=true) is the fastest way to exercise all tools — no external systems required. lib/mock_data.py has pre-seeded drift scenarios for realistic testing.

Architecture

Shard Pattern

Every shard exports a single register(mcp: FastMCP) -> None function. main.py reads feature flags and calls register() for each enabled shard. No other file changes when adding or removing a shard.

# Minimal shard skeleton
def register(mcp: FastMCP) -> None:
    @mcp.tool()
    async def my_tool(arg: str) -> dict:
        """Tool description visible to the LLM."""
        ...

Canonical Schemas

All system adapters transform native API responses into Pydantic models defined in lib/schemas.py:

• CanonicalUser — normalized across AD, Entra ID, Workday
• CanonicalDevice — normalized across Intune, Lansweeper, Helix
• CanonicalIncident, CanonicalShipment, FieldDrift — other domains

Use canonical types as return values; never pass raw dicts between layers.

SOC 2 Audit Middleware

Applied in main.py after all shards load — wraps every tool automatically. Each call records event_id, timestamp, tool, shard, action_category, args_summary (secrets redacted), mock_mode, status, and latency_ms to logs/nexus_audit.jsonl.

Shard Status

Shard	Systems	Status	Notes
identity	AD + Entra ID	Live	15 tools; tests passing
workday	Workday HCM	In progress	12 tools; credentials + validation pending
audit	Cross-system drift	Live	4 scan tools + 2 audit log query tools
itsm	BMC Helix ITSM	Stub	6 tools planned
assets	Lansweeper + Intune	Stub	13 tools planned
logistics	FedEx	Stub	5 tools planned

Branching

• main — stable; changes via PR only
• feat/, project/, chore/ — short-lived feature branches
• Rebase is intentional, not automated
• See CONTRIBUTING.md for full workflow