nathan
458264268e
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.
150 lines
5.4 KiB
Markdown
150 lines
5.4 KiB
Markdown
# 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
|