Enterprise MCP Service Bus — Reference Implementation
Executable implementation of the architecture described in ../README.md
(reference architecture). For the complete technical reference of what exists and how it works,
see 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 |
Integrating with or extending the RI — what exists, how it works, what was validated. |
docs/How-To.md |
Running the RI — installation, tests, local stack, publishing a capability, registering a client. |
docs/interfaces/ |
Exact contracts per interface (Gateway, identity, PDP, Registry, downstream identity, auditing, approval, agent runtime). |
docs/Assumptions.md |
Evaluating/adapting the RI — what was assumed and why. |
docs/Production-Recommendations.md |
Evaluating/adapting the RI — what changes for real production. |
../docs/adr/ |
Individual architectural decisions (ADR-001 through ADR-025). |
Quickstart (without Docker)
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 for the complete step-by-step, including how to install OPA
without Docker and bring up the services directly on the host.
Quickstart (Docker)
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 for the available profiles
(core, identity, observability) and what each one adds.
Structure
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.