TheUnderdark

TheUnderdark is a planned storage execution adapter for Roadex projects. It will expose narrowly scoped storage workflows through MCP, integrate with Overseer approvals, and produce redacted execution evidence for O'Brien's bounded maintenance workflows.

The first acceptance target is the storage-dependent Overseer workflow used by DonutHole.

Overseer does not currently provide a pluggable storage-adapter registry. The first integration slice must therefore define both TheUnderdark's MCP contract and the separately reviewed Overseer adapter-client/registration seam.

Status

The project summary is approved and the implementation team is under review. No storage adapter, persistent service, Overseer registration, or live storage execution is enabled yet.

Safety principles

• Bind the MCP backend to loopback only.
• Deny access outside explicitly registered project roots.
• Treat acknowledgment as message processing, not execution authorization.
• Require exact approval and idempotency controls for mutating operations.
• Return redacted evidence rather than credentials, raw databases, or private project exports.
• Keep service installation, registration, restarts, and remote exposure behind separate Overseer and human approval gates.

See the approved project summary and security boundaries for the initial contract. The Overseer integration findings capture the verified current blocker. The approved A-Team plan defines ownership and approval boundaries for implementation. The first approved design slice consists of the bounded storage contract and threat model. The proposed Overseer adapter contract defines the separately gated registry, approval, dispatch, and reconciliation integration.

Repository layout

• src/ — service implementation
• tests/ — unit, contract, and integration tests
• assets/ — non-secret project assets
• docs/ — architecture, security, and operator documentation

Fixture-only development

The current implementation is deliberately limited to client-spawned stdio and temporary fixture roots. It is not registered with Overseer and cannot operate on persistent project storage through its public API.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
.venv/bin/pytest -q

The installed theunderdark-mcp serve --stdio command exposes the bounded MCP tool inventory with an empty fixture control plane. Tests construct explicit temporary registrations and authorizations in process. Streamable HTTP, persistent configuration, a shared port, and service installation remain later approval-gated stages.