Metadata-Version: 2.5
Name: deep-agentic-core-mcp
Version: 0.3.0
Summary: Unified MCP server for AgenticLens and Agentic Chaos workflows.
Project-URL: Homepage, https://github.com/DeepAgentLabs/mcp-server
Project-URL: Repository, https://github.com/DeepAgentLabs/mcp-server
Project-URL: Issues, https://github.com/DeepAgentLabs/mcp-server/issues
Author: DeepAgentLabs
License: MIT
Keywords: agentic-ai,chaos-engineering,llm,mcp,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: referencing<1,>=0.35
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: fakeredis[lua]<3,>=2.23; extra == 'dev'
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: moto[dynamodb]<6,>=5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Requires-Dist: types-jsonschema>=4.23; extra == 'dev'
Provides-Extra: http
Requires-Dist: boto3<2,>=1.34; extra == 'http'
Requires-Dist: redis<7,>=5; extra == 'http'
Requires-Dist: starlette>=0.37; extra == 'http'
Requires-Dist: uvicorn>=0.30; extra == 'http'
Description-Content-Type: text/markdown

# deep-agentic-core-mcp

`deep-agentic-core-mcp` is the shared MCP server layer for the DeepAgentLabs
ecosystem. It is designed to expose a single MCP interface that combines:

- `agenticlens` style workflow inspection, profiling, and analysis
- `agentic-chaos` style resilience testing and fault-injection workflows
- `agentic-sidecar` style supervision-readiness and module-surface discovery
- future `agenticops-control-tower` style operator-facing control-plane access

It sits above the **AI Operations Workflow Specification**, exposing a unified
MCP-native control surface over the shared operational model used by the
reference implementations.

The goal is one MCP server, one package, and one registry identity rather than
separate MCP servers for each product surface.

<!-- mcp-name: io.github.DeepAgentLabs/deep-agentic-core-mcp -->

## Connect and use

Start with the [user and developer guide](docs/user-guide.md) for hosted signup,
MCP client connection, workflow analysis, evaluation reports, and local chaos/
Sidecar capabilities. Run [the Python workflow example](examples/hosted_workflow.py)
to send an exported workflow to the hosted service. The guide documents current
integration availability and distinguishes implemented tools from future runtime work.

## Idea

This project is the control plane between LLM hosts and the existing Python
libraries:

- `agenticlens` remains the core profiling and analysis engine
- `agentic-chaos` remains the core chaos and resilience engine
- `agentic-sidecar` remains the core decision-supervision and governance engine
- `agenticops-control-tower` remains the future operator-facing control plane
- the `AI Operations Workflow Specification` remains the shared data contract
- `deep-agentic-core-mcp` becomes the MCP-native interface that hosts can call

That means MCP clients can connect once and access observability, chaos,
sidecar discovery, and later Control Tower-aligned operations surfaces through
one server.

## What This Server Should Eventually Do

Planned capability areas:

- profile an agentic workflow and return structured telemetry summaries
- analyze workflow artifacts and surface optimization recommendations
- run controlled chaos experiments against target workflows
- expose sidecar readiness and scaffold inventory while the upstream runtime
  is still under construction
- eventually expose Control Tower inventory and operator-facing control
  surfaces once that sibling package ships them
- compare normal versus chaos runs
- expose shared resources such as workflow schemas, run metadata, and saved
  reports

## Design Principles

- One MCP identity: publish a single server to the MCP Registry
- Python-first: package and publish through PyPI
- Thin orchestration layer: reuse `agenticlens`, `agentic-chaos`, and
  `agentic-sidecar` instead of re-implementing their logic
- Local-first: work well as a stdio MCP server for developer workflows —
  this matters because `chaos.run_experiment` executes real code (see
  [SECURITY.md](SECURITY.md)), so this server is meant for trusted,
  local/stdio use; authenticated HTTP deployments disable code execution
- Dual transport, one tool surface: the optional Streamable HTTP transport
  (below) reuses stdio tools/resources/prompts, with remote script execution
  excluded

## MCP Surface (current, `0.3.0`)

- `core.health` — rich diagnostics: adapter availability/version, loaded
  tool/resource/prompt counts, workspace root, recent successful calls
- `core.version` — server package version
- `core.verify` — checks agenticlens/agentic-chaos/agentic-sidecar/ai-operations-spec
  connectivity and reports readiness
- `core.session_state` — inspect what the active session has accumulated
- `lens.analyze_workflow` — run AgenticLens recommendations against a
  workflow artifact
- `lens.report_summary` — render a Markdown workflow report
- `lens.compare_runs` — compare baseline/candidate trace runs for
  regressions
- `lens.slo_summary` — apply release-gate style SLO thresholds to an
  evaluation report
- `lens.audit_report` — case-by-case evaluation detail, optionally with HTML
- `chaos.list_faults` — list the supported fault types
- `chaos.run_experiment` — run a workspace-sandboxed target script under
  selected faults ([executes real code — see `SECURITY.md`](SECURITY.md))
- `sidecar.status` — report whether `agentic-sidecar` is connected and
  whether its runtime is implemented yet (added in `0.3.0`)
- `sidecar.module_inventory` — inspect the current scaffolded sidecar
  modules, framework adapters, and integration placeholders (added in `0.3.0`)
- `spec.validate_artifact` — validate a workflow/run artifact against the AI
  Operations v0.4 draft

Sequential tool calls can share context via an optional `session_id`
argument, backed by an in-memory session store — see `ROADMAP.md` Phase 2.

See [ROADMAP.md](ROADMAP.md) for what's shipped per phase and what's still
open, and [docs/tools.md](docs/tools.md) for full input schemas and
per-tool metadata (generated from `tools/registry.py`, run `make docs` to
refresh it after changing that file).

## Local vs. remote install modes

Container definitions are grouped under [deploy/docker](deploy/docker/README.md).

- **Local:** `pip install deep-agentic-core-mcp`, then run
  `deep-agentic-core-mcp` over stdio. Local session behavior is unchanged.
- **Self-hosted multi-user HTTP (`0.3.0`+):** install with
  `pip install 'deep-agentic-core-mcp[http]'`, then run `deep-agentic-core-mcp-http`.
  Provision a unique bearer key per user
  and a Redis URL before startup. Missing configuration prevents startup.
- **Hosted AWS signup:** open [mcp.deepagentlabs.io](https://mcp.deepagentlabs.io)
  to generate a user identity and MCP key; connect your MCP client to
  `https://mcp.deepagentlabs.io/mcp` with its bearer key.
  DynamoDB stores user records and key hashes; keys work immediately and can be
  replaced or revoked through the page. No password or email verification is used.
  Save the key: it cannot be recovered. See [the AWS guide](deploy/aws/README.md).

The HTTP service uses stateless MCP transport at `/mcp` and Redis-backed
workflow sessions scoped to the authenticated user. Users can reuse the same
`session_id` without accessing each other's artifacts. HTTP calls cannot run
`chaos.run_experiment`, even if the local remote-chaos override is set.

See [the remote hosting guide](docs/remote-hosting.md) and `render.yaml` for Render deployment, configuration,
container builds, AWS deployment requirements, client headers, limits, and
credential rotation. `create_app()` also accepts explicit credentials, a
session backend, and allowed hosts/origins for integrations and tests.
`MemorySessionStore` is an explicit development option; the CLI requires Redis.

## Repository Layout

```text
mcp-server/
├── README.md
├── ROADMAP.md
├── pyproject.toml
├── server.json
├── .gitignore
├── docs/
│   ├── architecture.md
│   └── tools.md          # generated - see scripts/generate_tools_doc.py
├── examples/
│   ├── sample_workflow.json
│   └── chaos_target.py
├── scripts/
│   └── generate_tools_doc.py
├── src/
│   └── deep_agentic_core_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── transport_http.py
│       ├── config.py
│       ├── prompts/
│       │   ├── __init__.py
│       │   └── registry.py
│       ├── resources/
│       │   ├── __init__.py
│       │   └── catalog.py
│       ├── schemas/
│       │   ├── __init__.py
│       │   └── tooling.py
│       ├── services/
│       │   ├── __init__.py
│       │   ├── registry.py
│       │   └── session.py
│       ├── adapters/
│       │   ├── __init__.py
│       │   ├── agentic_chaos.py
│       │   ├── agenticlens.py
│       │   ├── agentic_sidecar.py
│       │   └── ai_operations_spec.py
│       └── tools/
│           ├── __init__.py
│           ├── registry.py
│           ├── chaos.py
│           ├── core.py
│           ├── lens.py
│           ├── sidecar.py
│           └── spec.py
└── tests/
    ├── test_degraded_boot.py
    ├── test_imports.py
    ├── test_registry.py
    ├── test_server.py
    └── test_session.py
```

## MCP-Oriented Structure

This repository should have all of the standard layers we expect for a useful
MCP server:

- `tools/` for callable MCP tools and their registration metadata
- `resources/` for readable assets such as fault catalogs, templates, and
  workflow examples
- `prompts/` for reusable prompt templates exposed through the server
- `schemas/` for typed request and response contracts
- `services/` for shared orchestration logic that keeps tool modules thin,
  including the in-memory session store (`services/session.py`)
- `adapters/` for integration boundaries to `agenticlens`, `agentic-chaos`,
  `agentic-sidecar`, and `ai-operations-spec` — each degrades to
  `"available": false` rather than crashing server boot if its sibling repo is
  missing

## Packaging and Publishing Model

One repository supports both the local Python package and the hosted HTTP service.
The stdio entry point remains available without the optional HTTP dependencies.
HTTP transport and signup support are included from `0.3.0`; the earlier
PyPI `0.2.0` release provides local stdio.

| Workflow | Trigger | Result |
|---|---|---|
| `.github/workflows/ci.yml` | Pull request | Tests Python 3.10–3.13 and builds distributions; no AWS deployment |
| `.github/workflows/ci.yml` | Push/merge to `main`, or manual run | Runs tests and package checks; no AWS deployment |
| `.github/workflows/release-pypi.yml` | Push a `v*` version tag | Runs checks, publishes to PyPI, creates the GitHub Release, publishes MCP Registry metadata, and deploys AWS after PyPI succeeds |

A push to `main` does not publish to PyPI or deploy AWS. A version-tag release
deploys the same tagged source to AWS only after PyPI publication succeeds. Package releases use PyPI Trusted Publishing;
AWS deployment uses the dedicated IAM user's GitHub secrets. See
[CONTRIBUTING.md](CONTRIBUTING.md) for releases and
[the AWS CI guide](deploy/aws/CI-CD.md) for deployment setup and limits.

For PyPI-based verification, the `mcp-name` marker above must match the
`name` field in `server.json`.

## What's Next

Phase 2 (session management, rich diagnostics, tool annotations, prompt
registry, `core.verify`) and Phase 3b (Agentic Chaos) are complete as of
`0.2.0`. What's still open (see [ROADMAP.md](ROADMAP.md) for full detail):

- **Phase 3a (AgenticLens)** — provenance verification on
  `lens.analyze_workflow`'s response shape
- **Phase 3d (Agentic Sidecar Discovery)** — now implemented in the current
  development line; richer sidecar control surfaces still depend on upstream
  runtime milestones landing first
- **Phase 3c (AI Operations Specification)** — multi-version schema support
  and conformance-style reporting, both blocked on upstream `ai-operations-spec`
  work landing first
- **Phase 4 (Unified Workflows)** — joined observability + chaos workflows,
  incident/readiness reporting, a higher-level control surface
- **Future Control Tower coordination** — once `agenticops-control-tower`
  ships real control-plane APIs, MCP should expose those operator-facing
  surfaces without reimplementing them here
- **Phase 5/6** — PyPI + MCP Registry publishing, operational intelligence
  features

## Development

A `Makefile` provides shorthand for common tasks:

```bash
make install     # install dev dependencies
make check       # run all quality gates (lint + format + typecheck + test)
make test-cov    # tests with coverage report
make docs        # regenerate docs/tools.md from tools/registry.py
make docs-check  # fail if docs/tools.md is out of date
make help        # list all available targets
```

## Notes

This scaffold assumes the intended GitHub namespace is
`io.github.deepagentlabs/deep-agentic-core-mcp`. If the final publishing
account or org changes, update:

- the `mcp-name` marker in this README
- `server.json`
- any repository URLs in `pyproject.toml`
