Enterprise-MCP-Service-Bus/RI/README.en-us.md

# Enterprise MCP Service Bus — Reference Implementation

Executable implementation of the architecture described in [`../README.md`](../README.md)
(reference architecture). For the complete technical reference of what exists and how it works,
see [`docs/AS-BUILT.md`](docs/AS-BUILT.md).

## Status

The entire planned backlog (milestones M0 through M4) is implemented, tested, and validated.
**261 automated tests**: 254 pass with `pytest --forked` (unit + e2e + contract + adversarial),
plus 7 security acceptance tests (`tests/e2e/test_security_acceptance.py`) that require real
Docker and are run separately due to the build+Keycloak cost per run. Production logic with no
mocks in the security and orchestration core: real OPA (subprocess), real Keycloak (Docker),
real LangGraph with a SQLite checkpointer, a real LLM (OpenAI-compatible endpoint), real HTTP
JWKS with real RS256 JWTs, real YAML from `config/`, real SQLite for the Registry.

## Navigation

| Document | For whom |
|---|---|
| [`docs/AS-BUILT.md`](docs/AS-BUILT.md) | Integrating with or extending the RI — what exists, how it works, what was validated. |
| [`docs/How-To.md`](docs/How-To.md) | Running the RI — installation, tests, local stack, publishing a capability, registering a client. |
| [`docs/interfaces/`](docs/interfaces/) | Exact contracts per interface (Gateway, identity, PDP, Registry, downstream identity, auditing, approval, agent runtime). |
| [`docs/Assumptions.md`](docs/Assumptions.md) | Evaluating/adapting the RI — what was assumed and why. |
| [`docs/Production-Recommendations.md`](docs/Production-Recommendations.md) | Evaluating/adapting the RI — what changes for real production. |
| [`../docs/adr/`](../docs/adr/) | Individual architectural decisions (ADR-001 through ADR-025). |

## Quickstart (without Docker)

```bash
make install         # creates .venv and installs the package in editable mode (dev extras included)
make lint             # ruff check + ruff format --check
make typecheck        # mypy --strict
make validate-schemas # validates all YAML under config/ against its Pydantic model
make test             # pytest --forked (unit + e2e + contract + adversarial)
```

`make test` needs the `opa` binary on the PATH (or `OPA_BINARY`) for the tests that exercise the
real PDP — without it, those tests are skipped (`pytest.skip`), not failed. `docker` on the PATH
is required for the same reason for `tests/e2e/test_real_keycloak.py`. See
[`docs/How-To.md`](docs/How-To.md) for the complete step-by-step, including how to install OPA
without Docker and bring up the services directly on the host.

## Quickstart (Docker)

```bash
make up      # == docker compose --profile core up --build   (without IdP)
make down
make logs

# With a real Keycloak:
cp .env.example .env   # uncomment the 3 OIDC_* lines
docker compose --profile core --profile identity up --build
```

See [`docs/How-To.md`](docs/How-To.md#bringing-up-the-local-stack) for the available profiles
(`core`, `identity`, `observability`) and what each one adds.

## Structure

```text
RI/
├── pyproject.toml
├── Makefile
├── docker-compose.yml          # profiles: core (gateway+sales-domain+finance-domain+opa),
│                                # identity (+keycloak), observability (+otel-collector+jaeger)
├── .env.example
├── deploy/
│   ├── docker/Dockerfile
│   ├── keycloak/realm-export.json   # realm "emcp", 3 clients
│   ├── opa/
│   ├── otel/collector-config.yaml
│   └── langfuse/docker-compose.override.yml   # llm-observability profile, opt-in
├── scripts/{export_schemas,validate_config}.py
├── schemas/*.schema.json        # generated by export_schemas.py
├── config/
│   ├── env/{dev,ci}.yaml
│   ├── policies/                          # entitlement.rego, transaction.rego
│   ├── clients/{*.yaml,profiles/*.yaml}   # registrations + client profiles
│   ├── backends/*.yaml                    # endpoint + outbound identity per backend
│   ├── capabilities/{sales,finance}/*.yaml
│   └── orchestrator/identity.yaml
├── src/emcp_bus/
│   ├── common/{config,otel,models,pii_redaction}.py
│   ├── identity/{models,authn,token_verifier,shared_client_lint}.py
│   ├── entitlement/{models,manager}.py
│   ├── registry/{models,store,pipeline,lifecycle,seed}.py
│   ├── pdp/{client,models}.py
│   ├── fabric/{router,adapters/rest_adapter}.py
│   ├── downstream/{models,identity}.py
│   ├── audit/{models,events,sink,correlation,bypass_detection}.py
│   ├── approval/{models,service}.py
│   ├── gateway/{server,cache,canonical_request}.py
│   ├── profile_intelligence/{models,rule_based_provider,governance}.py
│   ├── offering_filter/service.py
│   ├── orchestrator/{decision_context,state,graph,nba_model,decisioning,fallback,hitl_node}.py
│   └── agent_runtime/{dispatcher,identity_resolver,handoff_graph,global_supervisor,channels/*}.py
├── services/example_mcp_servers/
│   ├── sales_domain/server.py    # 6 tools: R1 + R2
│   └── finance_domain/server.py  # invoice.get R1, payment.create R2, payment.execute R3
├── agents/example_agent/
│   ├── agent.py, llm_client.py
│   ├── prompts/{store.py,v1.txt}
│   ├── backends/{sales_agent,finance_agent}/          # Mode A (ADR-024)
│   └── mode_b_orchestrator_driven/{decision_model,orchestrator}.py   # Mode B (ADR-024)
├── docs/
│   ├── AS-BUILT.md
│   ├── How-To.md
│   ├── Assumptions.md
│   ├── Production-Recommendations.md
│   └── interfaces/*.md
└── tests/
    ├── unit/
    ├── e2e/          # walking skeleton, governed gateway, real Keycloak, example agent,
    │                  # security acceptance, multi-agent Mode A, fail-closed
    ├── contract/     # input/output contract of each domain server
    └── adversarial/  # prompt/tool injection, protocol/identity
```

## Pinned Versions

See `pyproject.toml`. Main ones: `mcp` 2.2.0, `pydantic` 2.13.x, `opentelemetry-sdk` 1.44.x,
`uvicorn` 0.52.x, `pyjwt[crypto]` 2.14.x, `ruff` 0.16.x, `mypy` 2.3.x, `pytest` 9.1.x,
`pytest-forked` 1.7.x, `langgraph` 0.6.x + `langgraph-checkpoint-sqlite` 2.x, `hypothesis`
6.1xx.x (dev), `openai` 1.109.x, `python-dotenv` 1.2.x (dev), OPA v1.20.2 (static binary, Rego
v1 default), Keycloak 26.7.3, Langfuse self-hosted 4.35.0, `opentelemetry-collector-contrib`
0.114.0, `jaeger` (all-in-one) 1.62.0. Full record with provenance for each version in
`docs/adr/ADR-018-stack-de-implementacao.md`.