Uploaded 'claude.md'

docs: add CLAUDE.md for AI assistant onboarding Adds a CLAUDE.md at the repo root documenting project purpose, directory layout, setup, run/test commands, the shard registration pattern, canonical schema conventions, SOC 2 audit middleware behavior, shard status, and branching guidelines.
2026-05-30 07:24:38 -04:00 · 2026-05-30 07:24:38 -04:00 · 458264268e
commit 458264268e
parent 61041d0c3e
1 changed files with 149 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,149 @@
+# 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
+
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# 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.
+
+```python
+# 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