feat: add optional ai and mcp automation

docs/reference/ai-mcp-automation.md

@@ -0,0 +1,69 @@
+# AI and MCP Automation
+
+Milestone 16 adds optional automation surfaces that are safe by default:
+
+- AI assistance is disabled until `ai.enabled=true`.
+- MCP access is disabled until `mcp.enabled=true`.
+- MCP requires scoped API tokens with `mcp:read`.
+- Provider secrets are not stored in DMARQ settings.
+- Safe context redacts secret-like key/value fragments, bearer tokens, long
+  opaque values, and email local-parts in strict mode.
+- Action tools produce reviewable proposals first. Confirmation is audited, and
+  the current implementation does not apply DNS or other external changes.
+
+## Settings
+
+| Key | Default | Purpose |
+| --- | --- | --- |
+| `ai.enabled` | `false` | Enables AI assistance endpoints |
+| `ai.provider` | `template` | `template`, `local`, or `remote` provider mode |
+| `ai.model` | empty | Optional model name |
+| `ai.remote_base_url` | empty | Optional remote provider URL |
+| `ai.redaction_mode` | `strict` | `strict` or `balanced` safe-context redaction |
+| `ai.action_tools_enabled` | `false` | Allows proposal confirmation records |
+| `mcp.enabled` | `false` | Enables the read-only MCP endpoint |
+
+Use 1Password or another deployment secret injector for provider credentials.
+Do not put provider API keys into DMARQ settings.
+
+## Safe Context
+
+`GET /api/v1/ai/domains/{domain}/context` builds the payload that model or
+agent surfaces are allowed to inspect. It includes:
+
+- domain summary counts
+- recent report metadata
+- top sending sources
+- evidence links to the UI
+- redaction metadata
+
+The payload deliberately excludes raw report XML, mailbox credentials, OAuth
+tokens, notification target URLs, and original forensic message content.
+
+## MCP
+
+`POST /api/v1/mcp` accepts minimal JSON-RPC requests for:
+
+- `initialize`
+- `tools/list`
+- `tools/call`
+
+The current tools are read-only:
+
+- `list_domains`
+- `domain_summary`
+- `action_proposals`
+
+Create a token with the `mcp:read` scope and send it through `X-API-Key`.
+
+## Audit
+
+DMARQ records sanitized workspace audit events for:
+
+- `ai.summary_generated`
+- `ai.action_proposals_generated`
+- `ai.action_proposal_confirmed`
+- `mcp.tool_called`
+
+Audit details are sanitized with the same secret-field redaction used for other
+workspace audit logs.

docs/reference/api.md

@@ -61,6 +61,7 @@ through the `/public` path and avoid UI-specific payloads.
 | `GET /public/domains/{domain_id}/reports` | `reports:read` | Recent DMARC aggregate report summaries |
 | `GET /public/domains/{domain_id}/posture` | `posture:read` | Evidence-first posture dashboard payload |
 | `GET /public/tls-reports/summary` | `tls-reports:read` | SMTP TLS report trends and failure groups |
+| `POST /mcp` | `mcp:read` | Read-only MCP-style JSON-RPC tool endpoint |
 
 Successful public API calls update the token's last-used timestamp, source IP,
 and usage count for auditing.
@@ -214,6 +215,86 @@ Request:
 Updates workspace retention controls and writes a sanitized
 `workspace.retention_updated` audit event.
 
+### Optional AI Assistance
+
+AI assistance endpoints require administrator access and remain disabled until
+`ai.enabled=true` is set in Settings.
+
+#### Read AI Configuration
+
+```text
+GET /ai/config
+```
+
+Returns provider mode, model name, whether a remote base URL is configured,
+redaction mode, action-tool state, MCP state, and data-handling guarantees. Raw
+provider credentials are not stored or returned.
+
+#### Build Safe Context
+
+```text
+GET /ai/domains/{domain}/context
+```
+
+Returns a redacted context payload for a domain. The payload includes summary
+counts, recent reports, top sources, evidence links, and the redaction rules
+that were applied.
+
+#### Build Evidence Summary
+
+```text
+GET /ai/domains/{domain}/summary
+```
+
+Returns a deterministic evidence-first summary and remediation plan. Each
+recommendation includes evidence links back to the underlying DMARC data.
+
+#### Build Action Proposals
+
+```text
+GET /ai/domains/{domain}/action-proposals
+```
+
+Returns reproducible proposal artifacts. Proposal generation is read-only and
+does not apply DNS or configuration changes.
+
+#### Confirm Proposal
+
+```text
+POST /ai/domains/{domain}/action-proposals/confirm
+```
+
+Requires `ai.action_tools_enabled=true` and a `confirmation_text` equal to the
+proposal ID. Confirmation is written to the workspace audit log. The current
+implementation records human confirmation but does not apply external changes.
+
+### MCP Endpoint
+
+The MCP endpoint is disabled until `mcp.enabled=true` is set. It requires a
+scoped API token with `mcp:read`.
+
+```text
+POST /mcp
+```
+
+Supported JSON-RPC methods:
+
+| Method | Purpose |
+| --- | --- |
+| `initialize` | Return server capabilities |
+| `tools/list` | List read-only tool metadata |
+| `tools/call` | Call a read-only tool |
+
+Available tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `list_domains` | List monitored domains and aggregate counts |
+| `domain_summary` | Return an evidence-first summary for one domain |
+| `action_proposals` | Return reviewable remediation proposals without applying changes |
+
+Every successful tool call is audited as `mcp.tool_called`.
+
 ### Domains
 
 #### List Domains

docs/reference/workspaces.md

@@ -59,6 +59,8 @@ Current audit coverage includes:
 - notification and forensic setting changes
 - webhook creation, update, disable, and test actions
 - manual DKIM selector add/remove actions
+- AI summary generation, action proposal generation/confirmation, and MCP
+  read-only tool calls
 
 Audit details redact secret-like fields such as passwords, OAuth tokens, API
 keys, and webhook signing secrets.