## deep-agentic-core-mcp Development Reference

## Ecosystem Context

### Role in DeepAgentLabs

`deep-agentic-core-mcp` is the MCP-native control surface for DeepAgentLabs. It
exposes spec-aligned operational artifacts and selected capabilities from the
ecosystem through a unified interface for hosts, agents, and external systems.

### Owns

- MCP server wiring, handler registration, tool/resource exposure, and transport
  boundaries
- Thin orchestration that composes capabilities from sibling packages without
  redefining their core logic
- The contract for how DeepAgentLabs capabilities are presented through MCP

### Does Not Own

- The canonical operational model or schema definitions — those belong in
  `ai-operations-spec`
- Primary instrumentation, trace analysis, or evaluation logic — those belong
  in `agenticlens`
- Fault injection and resilience simulation logic — those belong in
  `agentic-chaos`
- Agent-decision supervision or governance policy logic — those belong in
  `agentic-sidecar`

### Integrates With

- `ai-operations-spec` so returned artifacts and tool semantics align with the
  shared contract
- `agenticlens` as a source of analysis, provenance, and workflow evidence
- `agentic-chaos` as a source of resilience and degradation workflows
- `agentic-sidecar` when supervised-decision capabilities need MCP exposure in
  the future. At the ecosystem-role level, Sidecar is the **SUPERVISE** layer,
  while its concrete functionality spans both supervision and governance.

### Current Roadmap Focus

Phase 3 (lens provenance, chaos AIOS export and script policy, spec_version
routing and rule-cited conformance) is complete as of `0.3.3`. Phase 4 is
complete: the local Control Tower connector shipped in `0.3.6` and the unified
`core.*` workflow tools (fail-closed release check, incident summary, report
export) in `0.4.0`. Phase 5 is complete as of `0.5.0`: per-key tool policies
are enforced at dispatch (`services/access_policy.py`), the key and policy are
re-checked after the session lock, and calls leave correlated
`mcp.access-decision.v1` evidence (`services/access_evidence.py`). Phase 6 (0.6.0) binds hosted Tower credentials per user, bridges live
Sidecar stop/revoke with independent operator auth and adds the spec-owned
exploratory access extension. Paired Chaos 0.10 assertions authenticate observations
with Lens. Read docs/phase6-containment.md before changing these boundaries. Any new hosted dispatch path must go through the authorizer. Unified tools must stay compositions: delegate judgement to the
sibling that owns it (Evals gate, Lens comparison, Chaos report) and fail
closed on missing or invalid evidence. Changes here should strengthen composition and interoperability, not
duplicate implementation logic from sibling repos.

The v0.7 integration-readiness milestone adds `core.compatibility` and a packaged
candidate matrix in `resources/compatibility.json`. Keep it aligned with image
pins and CI using `tests/test_readiness_matrix.py`. It reports distribution
metadata only, not imported-source or live-host acceptance. The built-wheel
stdio protocol smoke runs without optional siblings. See docs/release-readiness.md.

### Before You Build Here

- Prefer adapting and exposing sibling-package behavior over rebuilding it in
  server-local modules
- If a new concept changes artifact meaning or shape across the ecosystem,
  update `ai-operations-spec` first
- Keep this package thin: MCP is the access layer, not the place to invent a
  second analysis engine, chaos engine, or policy runtime

## Build and Run

- Install: `make install` (runs `uv sync --extra dev`)
- Run server: `uv run deep-agentic-core-mcp`
- Test: `make test` or `make check` (lint + format + typecheck + test)
- Lint: `make lint`
- Type check: `make typecheck`

## Code Style

- Strict typing (mypy strict mode, Python 3.10+)
- Async-first — all MCP handlers are async
- Line length: 100
- Ruff rules: E, F, I, UP, B, SIM, N
- One purpose per file (separation of concerns)

## Architecture

MCP 2.0 constructor-based handler registration (not decorator-based):

```python
server = Server(
    SERVER_NAME,
    on_list_tools=handle_list_tools,
    on_call_tool=handle_call_tool,
    on_list_resources=handle_list_resources,
)
```

Handlers receive `(ctx: ServerRequestContext, params)` and return typed result
objects (`ListToolsResult`, `CallToolResult`, `ListResourcesResult`).

## Repo Map

| Path | Purpose |
|------|---------|
| `src/deep_agentic_core_mcp/server.py` | MCP server entrypoint, handler registration, tool dispatch |
| `src/deep_agentic_core_mcp/config.py` | Server identity and shared constants |
| `src/deep_agentic_core_mcp/tools/` | Tool implementations (`core.py`) and registry (`registry.py`) |
| `src/deep_agentic_core_mcp/resources/` | MCP resource definitions and catalog |
| `src/deep_agentic_core_mcp/prompts/` | Reusable prompt templates, wired into `prompts/list`/`prompts/get` |
| `src/deep_agentic_core_mcp/schemas/` | Request/response contracts |
| `src/deep_agentic_core_mcp/services/` | Shared orchestration logic |
| `src/deep_agentic_core_mcp/adapters/` | Integration boundaries to agenticlens and agentic-chaos |
| `tests/` | Pytest tests (asyncio_mode=auto) |
| `scripts/generate_tools_doc.py` | Generates `docs/tools.md` from `tools/registry.py` |
| `docs/tools.md` | **Generated** — never hand-edit, run `make docs` |
| `server.json` | MCP Registry metadata |
| `Makefile` | Local dev automation |

## Entry Points

- Console script: `deep-agentic-core-mcp` → `server.py:main()`
- Local server boot: `run_server()` → `stdio_server()` → `server.run()`
- HTTP console script: `deep-agentic-core-mcp-http` → `transport_http.py:main()`
- Operator console script: `deep-agentic-core-mcp-admin` → `admin.py:main()` (key policies, revocation)
- Hosted signup and key lifecycle: `signup.py`, backed by DynamoDB

## Local and Hosted Deployment Contract

Maintain both transports in this repository. The base PyPI package provides
local stdio; the optional `http` extra adds hosted Streamable HTTP dependencies.
HTTP/signup support is included from `0.3.0`; PyPI `0.2.0` provides local stdio.

HTTP requires bearer authentication and Redis-backed user-scoped workflow state.
The AWS deployment uses DynamoDB for user records and hashed keys. HTTP always
rejects `chaos.run_experiment`; local stdio retains trusted local execution.
Test transport-specific authorization and state isolation when changing dispatch.

- Pull requests, pushes to `main`, and manual CI runs perform checks and package
  builds without deploying AWS or publishing to PyPI.
- Pushing a `v*` tag runs `release-pypi.yml`: the full test matrix and packaging
  checks, PyPI publication, GitHub Release, MCP Registry publication. AWS deployment is manual from 0.4.1. Infrastructure changes use the operator flow.
- Prepare matching versions in `pyproject.toml`, `__init__.py`, `server.json`,
  and `uv.lock`, plus dated changelog notes, before pushing the release tag.
- Keep Docker files under `deploy/docker/` and infrastructure under `deploy/aws/`.
  Keep credentials and local deployment state out of Git. Document configuration
  in [deploy/aws/CI-CD.md](deploy/aws/CI-CD.md) and client behavior in
  [docs/user-guide.md](docs/user-guide.md).

## Adding a New Tool

1. Add implementation in `tools/` (return a dict)
2. Register in `tools/registry.py` (name, description, and the metadata
   fields: `category`, `prerequisites`, `expected_duration`, `mutates_session`)
3. Add handler entry in `server.py` `_TOOL_DISPATCH`
4. Add test in `tests/test_server.py`
5. Run `make docs` to regenerate `docs/tools.md`

## Feature Completion Expectations

- Every behavior change must include tests.
- User-facing tools and workflows must include or update examples in
  `README.md`, generated tool docs, or test fixtures that demonstrate expected
  usage.
- When a roadmap item or milestone meaningfully changes status, update
  `README.md` and the roadmap document in the same change.
- If that milestone or release changes the public ecosystem story, also update
  the shared org-profile docs in the `.github` repository:
  `profile/README.md` and, when relevant, `profile/ROADMAP.md`.
- When work is packaged as a release-ready change, also update
  `pyproject.toml`, `src/deep_agentic_core_mcp/__init__.py`, and
  `CHANGELOG.md`.

## Package Boundaries

- This server is a **thin orchestration layer** — reuse agenticlens and
  agentic-chaos logic, don't reimplement it
- All tools should read/return AI Operations Specification-compatible artifacts
- MCP types come from `mcp.types` (re-exports `mcp_types`)

## Pre-push Checklist

Run `make check` before every push. It runs: lint → format-check → typecheck → test.
If `tools/registry.py` changed, also run `make docs-check` (regenerates
`docs/tools.md` and fails if that changed anything you didn't commit) —
not part of `check` itself so the default gate stays fast.

## Release

Two phases, split by the merge to `main` — bumping happens before, and the
tag-driven release automation happens after.

**1. Pre-release (on the feature branch, before merge):** Bump version in
`pyproject.toml`, `src/deep_agentic_core_mcp/__init__.py`, and
`server.json`, `uv.lock`, and `CHANGELOG.md` (a dated release section under
`[Unreleased]`). Commit as
part of the branch's normal history; goes in with the rest of the PR.

**2. Release (on `main`, once that branch has merged):**

1. Pull the merge commit on `main`.
2. Tag: create an annotated `vX.Y.Z` tag pointing at the merge commit,
   using the `CHANGELOG.md` release section for that version as the tag
   message:
   `git tag -a vX.Y.Z -F <file-with-that-section> --cleanup=verbatim`.
   `--cleanup=verbatim` is required — git's default cleanup silently strips
   lines starting with `#`, which would eat the changelog's `###` headers.
3. Push the tag: `git push origin vX.Y.Z`.

That tag push is the release trigger. `release-pypi.yml` runs automatically
from the same tag and does all of the following:

- publishes the package to PyPI via Trusted Publishing (OIDC)
- creates the GitHub Release object for `vX.Y.Z`
- publishes the server to the MCP Registry
- leaves AWS deployment to an explicit manual operator action

The GitHub Release title is the tag name, and its body is copied from the
matching `CHANGELOG.md` section so the changelog, tag, PyPI release,
GitHub Releases page, and MCP Registry publish all stay aligned.


## Release pipeline from 0.4.1

Tag releases validate, publish PyPI/GitHub Release and publish the MCP Registry.
Automatic AWS deployment is removed from GitHub Actions. Existing AWS build and
operator deployment scripts remain available for an explicit manual deployment;
publishing a package does not update the running AWS service. Standalone image
recipes include Sidecar 0.9.2; a live runtime bridge requires explicit host bindings.

## Coordinated major release policy

The maintainer authorized 1.0.0 as a coordinated milestone with outstanding
validation disclosed. Preserve draft/candidate schema labels and track remaining
acceptance work on the roadmap. Follow the updated
[shared release policy](https://github.com/DeepAgentLabs/.github/blob/main/profile/RELEASE_POLICY.md).
Schema versions remain independent of package versions.