agent-comms-mcp 0.1.0__tar.gz

agent_comms_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redesign Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_comms_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: agent-comms-mcp
+Version: 0.1.0
+Summary: MCP service for permissioned, structured agent-to-agent communications
+Author-email: Redesign Health <tech@redesignhealth.com>
+License: MIT
+Project-URL: Homepage, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Repository, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Issues, https://github.com/redesignhealth/agent-comms-mcp/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: alembic==1.18.5
+Requires-Dist: asyncpg==0.31.0
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: greenlet==3.5.4
+Requires-Dist: httpx==0.28.1
+Requires-Dist: py-key-value-aio[filetree]==0.4.5
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: sqlalchemy[asyncio]==2.0.51
+Requires-Dist: structlog==25.5.0
+Dynamic: license-file
+
+# agent-comms-mcp
+
+MCP service for **permissioned, structured agent-to-agent communications**.
+First use case: a user's main agent delegates to a dedicated EA agent, which
+communicates with other people's EA agents to negotiate availability (including
+judgment, not just calendar overlap). Communications are scoped and structured
+— no free text initially. See [`docs/DESIGN.md`](docs/DESIGN.md) for the full
+spec (data model, permission model, message schemas). EA agent logic lives
+elsewhere — this repo is only the comms layer.
+
+## Layout
+
+```
+main.py              # FastMCP server, observability + scope-enforcement middleware
+auth.py              # Okta OIDCProxy (humans) + agent-jwt JWTVerifier (agents) via MultiAuth
+scopes.py            # TOOL_SCOPES catalog + fail-closed scope helpers
+identity.py          # Issuer-gated JWT identity resolution (anti-impersonation guards)
+observability.py     # structlog JSON events (tool_call, scope_denial, auth_flow, ...)
+providers/comms.py   # Comms provider sub-server — the MCP tools (see below)
+models.py            # SQLAlchemy 2.x async ORM models (agents, conversations,
+                      #   participants, messages, audit_log — DESIGN.md §5)
+db.py                # Async engine/session factory (DATABASE_URL, fail-fast)
+schemas.py           # Pydantic message-payload schemas (all registered message types)
+state_machine.py     # Conversation/participant state transitions (DESIGN.md §4, §6)
+service.py           # Domain/service layer: membership rules, uniform denials, audit
+exceptions.py        # Service-layer exception shapes (mapped to ToolError in providers/comms.py)
+migrations/          # Alembic migrations (async env.py); run `alembic upgrade head`
+tests/               # pytest suite (composition, scope fail-closed, domain logic, schema)
+```
+
+## Domain layer
+
+The comms board is five Postgres tables — `agents`, `conversations`,
+`participants`, `messages`, `audit_log` — with `messages` and
+`audit_log` append-only. An agent self-provisions via `comms_register`,
+then either starts a conversation (adding named targets as `invited`) or
+gets invited into one. A target only gains message-history read/write
+access after calling `comms_accept` (`invited → active`); declining
+(`comms_decline_invite`) is terminal and grants nothing. Task coordination
+uses task message types (`task_assign`, `task_report`, `task_complete`,
+`task_decline`, `task_cancel`) within ordinary conversations — task state
+lives on `conversations.state`, not a separate table. Conversation types
+(`open`, `internal`, `asymmetric`) gate admission by ownership; message
+types gate boundary crossing via the `boundary_safe` flag — see
+[`docs/DESIGN.md`](docs/DESIGN.md) §4–§9 for full details.
+
+## MCP tool surface
+
+All tools below are mounted under the `comms` namespace (e.g. `whoami` in
+`providers/comms.py` is exposed as `comms_whoami`) and enrolled in the
+fail-closed `scopes.TOOL_SCOPES` registry. Source of truth:
+`providers/comms.py`.
+
+| Tool | Scope | Purpose |
+|---|---|---|
+| `comms_whoami` | `comms:read` | Return the caller's identity, issuer, caller type, and scopes |
+| `comms_register` | `comms:write` | Idempotently self-provision (or re-bind) the caller's board `Agent` row |
+| `comms_list_agents` | `comms:read` | Paginated board directory |
+| `comms_start_conversation` | `comms:write` | Open a conversation with N target agents and post the seq-1 message |
+| `comms_post_message` | `comms:write` | Post a typed, schema-validated message to an active conversation |
+| `comms_get_conversation` | `comms:read` | Combined read: conversation + participants + messages since a seq; advances the caller's read cursor |
+| `comms_inbox` | `comms:read` | Active conversations with unread messages, plus pending invites |
+| `comms_list_conversations` | `comms:read` | Paginated list, filterable by role/type/state; newest-first |
+| `comms_accept` | `comms:write` | Flip the caller's participant status `invited → active`, granting history read + posting rights |
+| `comms_decline_invite` | `comms:write` | Decline a pending invite — terminal, no access is ever granted |
+| `comms_invite` | `comms:write` | Invite another board agent into an active conversation (as `invited`) |
+| `comms_leave` | `comms:write` | Leave a conversation the caller is currently `active` in |
+
+## Auth model
+
+Both humans and machines POST to the same `/mcp` endpoint; FastMCP
+`MultiAuth` routes them (`/health` is unauthenticated):
+
+- **Humans** (Claude Code / Claude Desktop / browser): Okta OIDC via FastMCP
+  `OIDCProxy`. Identity claims (email) are available to tools via
+  `get_access_token().claims`. Interactive callers bypass per-tool scope
+  checks.
+- **Agents / services**: HS256 Bearer JWT with `iss="agent-jwt"`, `sub`, and
+  `scopes` claims, verified by a `JWTVerifier` keyed to `AGENT_JWT_SECRET`.
+  Every tool call is then gated by the `TOOL_SCOPES` catalog in `scopes.py`
+  — **fail-closed**: a tool without a registry entry rejects every agent
+  call, denial messages are uniform (anti-enumeration), and each denial emits
+  a structured `scope_denial` log event.
+
+When adding a tool, enroll its mounted name (`comms_<tool>`) in
+`TOOL_SCOPES` in the same PR — `tests/test_main.py` fails otherwise.
+
+## Local development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                      # install deps from uv.lock
+
+# Start Postgres, apply migrations, then run the tests (see "Database /
+# migrations" below for why the port is 55432, not 5432)
+docker compose up -d postgres
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head
+uv run pytest                # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy .                # strict type check
+
+# Run the server (needs real Okta + secret config)
+cp .env.example .env         # fill in values; .env is gitignored
+uv run python main.py        # http://127.0.0.1:8080/mcp
+
+# Or the full stack (server + Postgres) in Docker
+docker compose up --build
+```
+
+Tests never touch the network: the Okta OIDC discovery call is patched out
+in every test module that imports `main` (see `tests/test_main.py`'s
+`_OIDC_PATCH`), so `uv run pytest` needs no real Okta tenant, issuer
+reachability, or credentials — only a reachable Postgres for the
+real-database tests (below), which skip cleanly if it's absent.
+
+### Database / migrations
+
+Postgres is provisioned by `docker-compose.yml`, mapped to **host port
+55432** (container-internal port stays the standard 5432). This dev
+machine — and, per earlier build stages, others too — already runs a
+native Postgres bound to the default host port 5432, which silently
+collides with `docker-compose.yml`'s old `5432:5432` mapping (you'd connect
+to the wrong database with no error). Moving the compose Postgres's
+*host-side* port to 55432 sidesteps this permanently; nothing about the
+container's internal networking changes, so the `agent-comms-mcp`
+service's own `DATABASE_URL` (which reaches `postgres` by service name on
+the internal port 5432) is unaffected.
+
+After starting Postgres, apply migrations before running the service or
+the real-database tests:
+
+```bash
+docker compose up -d postgres      # start Postgres only (host port 55432)
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head        # create/upgrade the 5-table schema
+```
+
+If you still hit a conflict (e.g. something else is bound to 55432), check
+with `lsof -i :55432` and either free the port or change the host-side
+number in `docker-compose.yml`'s `ports:` mapping for the `postgres`
+service (updating `DATABASE_URL` to match) — a single fixed alternate port
+is enough here, so there's no compose-override or env-var indirection.
+
+To generate a new migration after changing `models.py`:
+
+```bash
+uv run alembic revision --autogenerate -m "<description>"
+```
+
+`tests/test_db_models.py` (and the other real-database test modules) run
+against this same real Postgres instance (no mocking, per the RH standard)
+and skip gracefully with a clear reason if they can't connect.
+
+Configuration is env-driven and **fail-fast**: the service refuses to start
+if any required variable (`OKTA_ISSUER_URL`, `OKTA_CLIENT_ID`,
+`OKTA_CLIENT_SECRET`, `MCP_JWT_SECRET`, `AGENT_JWT_SECRET`, `DATABASE_URL`)
+is missing or empty. See `.env.example` for the full list. No secrets are committed
+anywhere in this repo.
+
+## Observability
+
+Structured JSON logs via `structlog` to stdout. Events follow the schema in
+`observability.py` (`tool_call`, `user_active`, `auth_flow`, `auth_rejected`,
+`scope_denial`). Message content and attacker-controlled claim values are
+never logged.
+
+## Deployment
+
+The service is a standard Python HTTP process backed by PostgreSQL. The
+included `Dockerfile` and `docker-compose.yml` cover local and self-hosted
+deployments.
+
+**Quick start (Docker Compose):**
+
+```bash
+cp .env.example .env   # fill in real values
+docker compose up --build
+```
+
+**Required environment variables** (see `.env.example`):
+
+| Variable | Purpose |
+|---|---|
+| `OKTA_ISSUER_URL` | Okta OIDC issuer URL for interactive callers |
+| `OKTA_CLIENT_ID` | Okta app client ID |
+| `OKTA_CLIENT_SECRET` | Okta app client secret |
+| `MCP_JWT_SECRET` | Signing secret for FastMCP's internal OAuth JWTs |
+| `AGENT_JWT_SECRET` | Shared HS256 secret for agent JWT verification |
+| `DATABASE_URL` | PostgreSQL connection string |
+
+`entrypoint.sh` runs `alembic upgrade head` automatically on every container
+start, so migrations apply before the server accepts traffic.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_comms_mcp-0.1.0/README.md

@@ -0,0 +1,198 @@
+# agent-comms-mcp
+
+MCP service for **permissioned, structured agent-to-agent communications**.
+First use case: a user's main agent delegates to a dedicated EA agent, which
+communicates with other people's EA agents to negotiate availability (including
+judgment, not just calendar overlap). Communications are scoped and structured
+— no free text initially. See [`docs/DESIGN.md`](docs/DESIGN.md) for the full
+spec (data model, permission model, message schemas). EA agent logic lives
+elsewhere — this repo is only the comms layer.
+
+## Layout
+
+```
+main.py              # FastMCP server, observability + scope-enforcement middleware
+auth.py              # Okta OIDCProxy (humans) + agent-jwt JWTVerifier (agents) via MultiAuth
+scopes.py            # TOOL_SCOPES catalog + fail-closed scope helpers
+identity.py          # Issuer-gated JWT identity resolution (anti-impersonation guards)
+observability.py     # structlog JSON events (tool_call, scope_denial, auth_flow, ...)
+providers/comms.py   # Comms provider sub-server — the MCP tools (see below)
+models.py            # SQLAlchemy 2.x async ORM models (agents, conversations,
+                      #   participants, messages, audit_log — DESIGN.md §5)
+db.py                # Async engine/session factory (DATABASE_URL, fail-fast)
+schemas.py           # Pydantic message-payload schemas (all registered message types)
+state_machine.py     # Conversation/participant state transitions (DESIGN.md §4, §6)
+service.py           # Domain/service layer: membership rules, uniform denials, audit
+exceptions.py        # Service-layer exception shapes (mapped to ToolError in providers/comms.py)
+migrations/          # Alembic migrations (async env.py); run `alembic upgrade head`
+tests/               # pytest suite (composition, scope fail-closed, domain logic, schema)
+```
+
+## Domain layer
+
+The comms board is five Postgres tables — `agents`, `conversations`,
+`participants`, `messages`, `audit_log` — with `messages` and
+`audit_log` append-only. An agent self-provisions via `comms_register`,
+then either starts a conversation (adding named targets as `invited`) or
+gets invited into one. A target only gains message-history read/write
+access after calling `comms_accept` (`invited → active`); declining
+(`comms_decline_invite`) is terminal and grants nothing. Task coordination
+uses task message types (`task_assign`, `task_report`, `task_complete`,
+`task_decline`, `task_cancel`) within ordinary conversations — task state
+lives on `conversations.state`, not a separate table. Conversation types
+(`open`, `internal`, `asymmetric`) gate admission by ownership; message
+types gate boundary crossing via the `boundary_safe` flag — see
+[`docs/DESIGN.md`](docs/DESIGN.md) §4–§9 for full details.
+
+## MCP tool surface
+
+All tools below are mounted under the `comms` namespace (e.g. `whoami` in
+`providers/comms.py` is exposed as `comms_whoami`) and enrolled in the
+fail-closed `scopes.TOOL_SCOPES` registry. Source of truth:
+`providers/comms.py`.
+
+| Tool | Scope | Purpose |
+|---|---|---|
+| `comms_whoami` | `comms:read` | Return the caller's identity, issuer, caller type, and scopes |
+| `comms_register` | `comms:write` | Idempotently self-provision (or re-bind) the caller's board `Agent` row |
+| `comms_list_agents` | `comms:read` | Paginated board directory |
+| `comms_start_conversation` | `comms:write` | Open a conversation with N target agents and post the seq-1 message |
+| `comms_post_message` | `comms:write` | Post a typed, schema-validated message to an active conversation |
+| `comms_get_conversation` | `comms:read` | Combined read: conversation + participants + messages since a seq; advances the caller's read cursor |
+| `comms_inbox` | `comms:read` | Active conversations with unread messages, plus pending invites |
+| `comms_list_conversations` | `comms:read` | Paginated list, filterable by role/type/state; newest-first |
+| `comms_accept` | `comms:write` | Flip the caller's participant status `invited → active`, granting history read + posting rights |
+| `comms_decline_invite` | `comms:write` | Decline a pending invite — terminal, no access is ever granted |
+| `comms_invite` | `comms:write` | Invite another board agent into an active conversation (as `invited`) |
+| `comms_leave` | `comms:write` | Leave a conversation the caller is currently `active` in |
+
+## Auth model
+
+Both humans and machines POST to the same `/mcp` endpoint; FastMCP
+`MultiAuth` routes them (`/health` is unauthenticated):
+
+- **Humans** (Claude Code / Claude Desktop / browser): Okta OIDC via FastMCP
+  `OIDCProxy`. Identity claims (email) are available to tools via
+  `get_access_token().claims`. Interactive callers bypass per-tool scope
+  checks.
+- **Agents / services**: HS256 Bearer JWT with `iss="agent-jwt"`, `sub`, and
+  `scopes` claims, verified by a `JWTVerifier` keyed to `AGENT_JWT_SECRET`.
+  Every tool call is then gated by the `TOOL_SCOPES` catalog in `scopes.py`
+  — **fail-closed**: a tool without a registry entry rejects every agent
+  call, denial messages are uniform (anti-enumeration), and each denial emits
+  a structured `scope_denial` log event.
+
+When adding a tool, enroll its mounted name (`comms_<tool>`) in
+`TOOL_SCOPES` in the same PR — `tests/test_main.py` fails otherwise.
+
+## Local development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                      # install deps from uv.lock
+
+# Start Postgres, apply migrations, then run the tests (see "Database /
+# migrations" below for why the port is 55432, not 5432)
+docker compose up -d postgres
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head
+uv run pytest                # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy .                # strict type check
+
+# Run the server (needs real Okta + secret config)
+cp .env.example .env         # fill in values; .env is gitignored
+uv run python main.py        # http://127.0.0.1:8080/mcp
+
+# Or the full stack (server + Postgres) in Docker
+docker compose up --build
+```
+
+Tests never touch the network: the Okta OIDC discovery call is patched out
+in every test module that imports `main` (see `tests/test_main.py`'s
+`_OIDC_PATCH`), so `uv run pytest` needs no real Okta tenant, issuer
+reachability, or credentials — only a reachable Postgres for the
+real-database tests (below), which skip cleanly if it's absent.
+
+### Database / migrations
+
+Postgres is provisioned by `docker-compose.yml`, mapped to **host port
+55432** (container-internal port stays the standard 5432). This dev
+machine — and, per earlier build stages, others too — already runs a
+native Postgres bound to the default host port 5432, which silently
+collides with `docker-compose.yml`'s old `5432:5432` mapping (you'd connect
+to the wrong database with no error). Moving the compose Postgres's
+*host-side* port to 55432 sidesteps this permanently; nothing about the
+container's internal networking changes, so the `agent-comms-mcp`
+service's own `DATABASE_URL` (which reaches `postgres` by service name on
+the internal port 5432) is unaffected.
+
+After starting Postgres, apply migrations before running the service or
+the real-database tests:
+
+```bash
+docker compose up -d postgres      # start Postgres only (host port 55432)
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head        # create/upgrade the 5-table schema
+```
+
+If you still hit a conflict (e.g. something else is bound to 55432), check
+with `lsof -i :55432` and either free the port or change the host-side
+number in `docker-compose.yml`'s `ports:` mapping for the `postgres`
+service (updating `DATABASE_URL` to match) — a single fixed alternate port
+is enough here, so there's no compose-override or env-var indirection.
+
+To generate a new migration after changing `models.py`:
+
+```bash
+uv run alembic revision --autogenerate -m "<description>"
+```
+
+`tests/test_db_models.py` (and the other real-database test modules) run
+against this same real Postgres instance (no mocking, per the RH standard)
+and skip gracefully with a clear reason if they can't connect.
+
+Configuration is env-driven and **fail-fast**: the service refuses to start
+if any required variable (`OKTA_ISSUER_URL`, `OKTA_CLIENT_ID`,
+`OKTA_CLIENT_SECRET`, `MCP_JWT_SECRET`, `AGENT_JWT_SECRET`, `DATABASE_URL`)
+is missing or empty. See `.env.example` for the full list. No secrets are committed
+anywhere in this repo.
+
+## Observability
+
+Structured JSON logs via `structlog` to stdout. Events follow the schema in
+`observability.py` (`tool_call`, `user_active`, `auth_flow`, `auth_rejected`,
+`scope_denial`). Message content and attacker-controlled claim values are
+never logged.
+
+## Deployment
+
+The service is a standard Python HTTP process backed by PostgreSQL. The
+included `Dockerfile` and `docker-compose.yml` cover local and self-hosted
+deployments.
+
+**Quick start (Docker Compose):**
+
+```bash
+cp .env.example .env   # fill in real values
+docker compose up --build
+```
+
+**Required environment variables** (see `.env.example`):
+
+| Variable | Purpose |
+|---|---|
+| `OKTA_ISSUER_URL` | Okta OIDC issuer URL for interactive callers |
+| `OKTA_CLIENT_ID` | Okta app client ID |
+| `OKTA_CLIENT_SECRET` | Okta app client secret |
+| `MCP_JWT_SECRET` | Signing secret for FastMCP's internal OAuth JWTs |
+| `AGENT_JWT_SECRET` | Shared HS256 secret for agent JWT verification |
+| `DATABASE_URL` | PostgreSQL connection string |
+
+`entrypoint.sh` runs `alembic upgrade head` automatically on every container
+start, so migrations apply before the server accepts traffic.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

agent_comms_mcp-0.1.0/agent_comms_mcp.egg-info/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: agent-comms-mcp
+Version: 0.1.0
+Summary: MCP service for permissioned, structured agent-to-agent communications
+Author-email: Redesign Health <tech@redesignhealth.com>
+License: MIT
+Project-URL: Homepage, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Repository, https://github.com/redesignhealth/agent-comms-mcp
+Project-URL: Issues, https://github.com/redesignhealth/agent-comms-mcp/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: alembic==1.18.5
+Requires-Dist: asyncpg==0.31.0
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: greenlet==3.5.4
+Requires-Dist: httpx==0.28.1
+Requires-Dist: py-key-value-aio[filetree]==0.4.5
+Requires-Dist: pydantic==2.12.5
+Requires-Dist: sqlalchemy[asyncio]==2.0.51
+Requires-Dist: structlog==25.5.0
+Dynamic: license-file
+
+# agent-comms-mcp
+
+MCP service for **permissioned, structured agent-to-agent communications**.
+First use case: a user's main agent delegates to a dedicated EA agent, which
+communicates with other people's EA agents to negotiate availability (including
+judgment, not just calendar overlap). Communications are scoped and structured
+— no free text initially. See [`docs/DESIGN.md`](docs/DESIGN.md) for the full
+spec (data model, permission model, message schemas). EA agent logic lives
+elsewhere — this repo is only the comms layer.
+
+## Layout
+
+```
+main.py              # FastMCP server, observability + scope-enforcement middleware
+auth.py              # Okta OIDCProxy (humans) + agent-jwt JWTVerifier (agents) via MultiAuth
+scopes.py            # TOOL_SCOPES catalog + fail-closed scope helpers
+identity.py          # Issuer-gated JWT identity resolution (anti-impersonation guards)
+observability.py     # structlog JSON events (tool_call, scope_denial, auth_flow, ...)
+providers/comms.py   # Comms provider sub-server — the MCP tools (see below)
+models.py            # SQLAlchemy 2.x async ORM models (agents, conversations,
+                      #   participants, messages, audit_log — DESIGN.md §5)
+db.py                # Async engine/session factory (DATABASE_URL, fail-fast)
+schemas.py           # Pydantic message-payload schemas (all registered message types)
+state_machine.py     # Conversation/participant state transitions (DESIGN.md §4, §6)
+service.py           # Domain/service layer: membership rules, uniform denials, audit
+exceptions.py        # Service-layer exception shapes (mapped to ToolError in providers/comms.py)
+migrations/          # Alembic migrations (async env.py); run `alembic upgrade head`
+tests/               # pytest suite (composition, scope fail-closed, domain logic, schema)
+```
+
+## Domain layer
+
+The comms board is five Postgres tables — `agents`, `conversations`,
+`participants`, `messages`, `audit_log` — with `messages` and
+`audit_log` append-only. An agent self-provisions via `comms_register`,
+then either starts a conversation (adding named targets as `invited`) or
+gets invited into one. A target only gains message-history read/write
+access after calling `comms_accept` (`invited → active`); declining
+(`comms_decline_invite`) is terminal and grants nothing. Task coordination
+uses task message types (`task_assign`, `task_report`, `task_complete`,
+`task_decline`, `task_cancel`) within ordinary conversations — task state
+lives on `conversations.state`, not a separate table. Conversation types
+(`open`, `internal`, `asymmetric`) gate admission by ownership; message
+types gate boundary crossing via the `boundary_safe` flag — see
+[`docs/DESIGN.md`](docs/DESIGN.md) §4–§9 for full details.
+
+## MCP tool surface
+
+All tools below are mounted under the `comms` namespace (e.g. `whoami` in
+`providers/comms.py` is exposed as `comms_whoami`) and enrolled in the
+fail-closed `scopes.TOOL_SCOPES` registry. Source of truth:
+`providers/comms.py`.
+
+| Tool | Scope | Purpose |
+|---|---|---|
+| `comms_whoami` | `comms:read` | Return the caller's identity, issuer, caller type, and scopes |
+| `comms_register` | `comms:write` | Idempotently self-provision (or re-bind) the caller's board `Agent` row |
+| `comms_list_agents` | `comms:read` | Paginated board directory |
+| `comms_start_conversation` | `comms:write` | Open a conversation with N target agents and post the seq-1 message |
+| `comms_post_message` | `comms:write` | Post a typed, schema-validated message to an active conversation |
+| `comms_get_conversation` | `comms:read` | Combined read: conversation + participants + messages since a seq; advances the caller's read cursor |
+| `comms_inbox` | `comms:read` | Active conversations with unread messages, plus pending invites |
+| `comms_list_conversations` | `comms:read` | Paginated list, filterable by role/type/state; newest-first |
+| `comms_accept` | `comms:write` | Flip the caller's participant status `invited → active`, granting history read + posting rights |
+| `comms_decline_invite` | `comms:write` | Decline a pending invite — terminal, no access is ever granted |
+| `comms_invite` | `comms:write` | Invite another board agent into an active conversation (as `invited`) |
+| `comms_leave` | `comms:write` | Leave a conversation the caller is currently `active` in |
+
+## Auth model
+
+Both humans and machines POST to the same `/mcp` endpoint; FastMCP
+`MultiAuth` routes them (`/health` is unauthenticated):
+
+- **Humans** (Claude Code / Claude Desktop / browser): Okta OIDC via FastMCP
+  `OIDCProxy`. Identity claims (email) are available to tools via
+  `get_access_token().claims`. Interactive callers bypass per-tool scope
+  checks.
+- **Agents / services**: HS256 Bearer JWT with `iss="agent-jwt"`, `sub`, and
+  `scopes` claims, verified by a `JWTVerifier` keyed to `AGENT_JWT_SECRET`.
+  Every tool call is then gated by the `TOOL_SCOPES` catalog in `scopes.py`
+  — **fail-closed**: a tool without a registry entry rejects every agent
+  call, denial messages are uniform (anti-enumeration), and each denial emits
+  a structured `scope_denial` log event.
+
+When adding a tool, enroll its mounted name (`comms_<tool>`) in
+`TOOL_SCOPES` in the same PR — `tests/test_main.py` fails otherwise.
+
+## Local development
+
+Requires [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync                      # install deps from uv.lock
+
+# Start Postgres, apply migrations, then run the tests (see "Database /
+# migrations" below for why the port is 55432, not 5432)
+docker compose up -d postgres
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head
+uv run pytest                # tests
+uv run ruff check . && uv run ruff format --check .
+uv run mypy .                # strict type check
+
+# Run the server (needs real Okta + secret config)
+cp .env.example .env         # fill in values; .env is gitignored
+uv run python main.py        # http://127.0.0.1:8080/mcp
+
+# Or the full stack (server + Postgres) in Docker
+docker compose up --build
+```
+
+Tests never touch the network: the Okta OIDC discovery call is patched out
+in every test module that imports `main` (see `tests/test_main.py`'s
+`_OIDC_PATCH`), so `uv run pytest` needs no real Okta tenant, issuer
+reachability, or credentials — only a reachable Postgres for the
+real-database tests (below), which skip cleanly if it's absent.
+
+### Database / migrations
+
+Postgres is provisioned by `docker-compose.yml`, mapped to **host port
+55432** (container-internal port stays the standard 5432). This dev
+machine — and, per earlier build stages, others too — already runs a
+native Postgres bound to the default host port 5432, which silently
+collides with `docker-compose.yml`'s old `5432:5432` mapping (you'd connect
+to the wrong database with no error). Moving the compose Postgres's
+*host-side* port to 55432 sidesteps this permanently; nothing about the
+container's internal networking changes, so the `agent-comms-mcp`
+service's own `DATABASE_URL` (which reaches `postgres` by service name on
+the internal port 5432) is unaffected.
+
+After starting Postgres, apply migrations before running the service or
+the real-database tests:
+
+```bash
+docker compose up -d postgres      # start Postgres only (host port 55432)
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/agent_comms
+uv run alembic upgrade head        # create/upgrade the 5-table schema
+```
+
+If you still hit a conflict (e.g. something else is bound to 55432), check
+with `lsof -i :55432` and either free the port or change the host-side
+number in `docker-compose.yml`'s `ports:` mapping for the `postgres`
+service (updating `DATABASE_URL` to match) — a single fixed alternate port
+is enough here, so there's no compose-override or env-var indirection.
+
+To generate a new migration after changing `models.py`:
+
+```bash
+uv run alembic revision --autogenerate -m "<description>"
+```
+
+`tests/test_db_models.py` (and the other real-database test modules) run
+against this same real Postgres instance (no mocking, per the RH standard)
+and skip gracefully with a clear reason if they can't connect.
+
+Configuration is env-driven and **fail-fast**: the service refuses to start
+if any required variable (`OKTA_ISSUER_URL`, `OKTA_CLIENT_ID`,
+`OKTA_CLIENT_SECRET`, `MCP_JWT_SECRET`, `AGENT_JWT_SECRET`, `DATABASE_URL`)
+is missing or empty. See `.env.example` for the full list. No secrets are committed
+anywhere in this repo.
+
+## Observability
+
+Structured JSON logs via `structlog` to stdout. Events follow the schema in
+`observability.py` (`tool_call`, `user_active`, `auth_flow`, `auth_rejected`,
+`scope_denial`). Message content and attacker-controlled claim values are
+never logged.
+
+## Deployment
+
+The service is a standard Python HTTP process backed by PostgreSQL. The
+included `Dockerfile` and `docker-compose.yml` cover local and self-hosted
+deployments.
+
+**Quick start (Docker Compose):**
+
+```bash
+cp .env.example .env   # fill in real values
+docker compose up --build
+```
+
+**Required environment variables** (see `.env.example`):
+
+| Variable | Purpose |
+|---|---|
+| `OKTA_ISSUER_URL` | Okta OIDC issuer URL for interactive callers |
+| `OKTA_CLIENT_ID` | Okta app client ID |
+| `OKTA_CLIENT_SECRET` | Okta app client secret |
+| `MCP_JWT_SECRET` | Signing secret for FastMCP's internal OAuth JWTs |
+| `AGENT_JWT_SECRET` | Shared HS256 secret for agent JWT verification |
+| `DATABASE_URL` | PostgreSQL connection string |
+
+`entrypoint.sh` runs `alembic upgrade head` automatically on every container
+start, so migrations apply before the server accepts traffic.
+
+## License
+
+MIT — see [LICENSE](LICENSE).