feat(mcp): add WS-MCP-001 contributor server foundation

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/CHUNK_MAP.md

@@ -0,0 +1,31 @@
+# Chunk Map: WS-MCP-001 - Workstream Contributor MCP Server
+
+## Rule
+
+Only one chunk may be active at a time. Do not begin a follow-up MCP chunk until
+the current chunk is implemented, verified, reviewed, merged by explicit human
+approval, recorded by merge-memory automation, and stopped.
+
+## Chunks
+
+| Chunk | Title | Risk | Status |
+|---|---|---:|---|
+| `WS-MCP-001-01` | Contributor MCP Foundation | L1 | Ready for PR |
+| `WS-MCP-001-02` | Replace Temporary Gateway And Close Conformance | L1 | Proposed after backend APIs exist |
+
+## Dependency order
+
+```text
+WS-MCP-001-01
+-> WS-MCP-001-02
+```
+
+`WS-MCP-001-02` covers authoritative project/task lists, contributions,
+contributor claim/release/submission, review resources/tools, and the remaining
+Sections 18 and 20 evidence. It is not limited to review and contribution APIs.
+
+## Stop condition
+
+After `WS-MCP-001-01` merges and automated merge memory records it, stop. Do not
+start `WS-MCP-001-02` without a separate explicit start signal and available
+backend API contracts.

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/DISCOVERY.md

@@ -0,0 +1,84 @@
+# Discovery: WS-MCP-001 - Workstream Contributor MCP Server
+
+## Current branch and base
+
+- Branch: `oxvictor/ws-mcp-001-01-contributor-mcp-foundation`
+- Latest inspected upstream main: `f18b620`
+- Fork remote: `fork https://github.com/ChuloWay/workstream.git`
+
+## Available backend API surface
+
+Current FastAPI routers expose:
+
+- auth and actor profile routes;
+- authorization routes;
+- project, guide, setup, and policy routes;
+- task lifecycle, task context, submission, and audit routes;
+- pre-submit checker and checker-run routes.
+
+Current backend APIs can support MCP task-by-id, locked task context,
+submission requirements, pre-submit check, submission listing, and checker-run
+reads. The MCP uses only those compatible calls.
+
+The current task claim route leaves work in `claimed` while WS-MCP-001 exposes
+one task-claim operation and cannot expose the separate start route. The current
+task release route is operator-scoped, not contributor-scoped. Submission
+creation does not provide the durable request-idempotency contract required by
+the MCP. The HTTP gateway must fail closed for all three until compatible
+contributor APIs exist.
+
+## Missing backend API surface for WS-MCP-001
+
+No backend route currently exposes:
+
+- contributor project list for `workstream://me/projects`;
+- contributor task list for `workstream://tasks` or
+  `workstream://projects/{project_id}/tasks`;
+- contribution record reads;
+- current review, review context, review claim, review release, or review
+  decision APIs.
+
+Additionally, no current backend API provides an atomic contributor
+claim-to-work transition, contributor task release, or durable request replay
+for submission creation.
+
+The maintainer approved using a simple temporary service layer for unavailable
+APIs so MCP tool and resource shape can be implemented and tested now.
+
+## WS-MCP-001 baseline findings
+
+The maintainer-provided PDF is the approved public-behavior baseline. It
+requires exactly seven resource types, seven tools, zero prompts, no queue or
+event/subscription surface, the same logical surface over STDIO and Streamable
+HTTP, current Workstream authorization on every operation, and retry-safe
+mutations.
+
+Sections 18 and 20 make conformance and acceptance conditional on evidence that
+is broader than this foundation chunk. Current gaps include:
+
+- authoritative production completion of both contributor journeys;
+- Submitter, Reviewer, Both, and revoked-access behavior through the MCP boundary;
+- initial submission, revision, identical-revision, and all Task Status outcomes;
+- concurrent task/review claims against current Workstream truth;
+- end-to-end equivalence over both STDIO and Streamable HTTP;
+- an MCP Inspector/client capture of discovery and both journeys.
+
+The in-memory scenario gateway and MCP client test exercise stable shapes and
+happy paths while APIs are missing. They are not evidence that the production
+server has passed the complete WS-MCP-001 conformance or acceptance gate.
+
+## Repo process findings
+
+No `CONTRIBUTING.md`, Husky directory, commitlint config, or package manifest is
+present. The active contribution standard is defined by `AGENTS.md`,
+`.github/pull_request_template.md`, `.agent-loop/policies/`, and CI gates.
+
+Every PR must add exactly one schema-v2 merge intent under
+`.agent-loop/merge-intents/`.
+
+## Design constraints
+
+- Workstream APIs and auth remain authoritative.
+- MCP tool inputs must never carry bearer tokens.
+- STDIO diagnostics must not write secrets to stdout.
+- The temporary service must not become production truth.

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/INTENT.md

@@ -0,0 +1,57 @@
+# Intent: WS-MCP-001 - Workstream Contributor MCP Server
+
+## Human-level goal
+
+Expose the approved contributor-facing Workstream MCP surface so MCP clients can
+help Submitters and Reviewers work through governed Workstream journeys without
+duplicating Workstream state, authorization, or lifecycle rules.
+
+## Why now
+
+The maintainer approved starting MCP work against the APIs that exist today and
+using a small temporary service layer for required MCP surfaces that are not
+yet implemented by the backend.
+
+## Success state
+
+This foundation chunk succeeds when the repository contains a contributor MCP
+server package that:
+
+- publishes only the WS-MCP-001 v0.1 resources and tools;
+- forwards authenticated contributor requests to Workstream APIs where they
+  exist;
+- isolates unavailable review, contribution, and task-list surfaces, plus
+  lifecycle calls whose current routes cannot meet the MCP contract, behind a
+  temporary replaceable test service;
+- preserves existing Workstream auth and lifecycle authority.
+
+This chunk does not by itself satisfy the WS-MCP-001 Sections 18 and 20
+conformance and acceptance gates. Those gates require authoritative production
+journeys and transport, authorization, retry, concurrency, and demonstration
+evidence after the missing Workstream APIs exist.
+
+## Non-goals
+
+- No Admin, Operator, Project Manager, Finance, or Audit MCP capabilities.
+- No MCP-owned identity, role, grant, session, workflow, queue, review, or
+  contribution database.
+- No direct database access.
+- No frontend implementation.
+- No production dependency on the temporary service layer.
+
+## Business/product/engineering context
+
+Workstream is Flow's task evaluation and contribution infrastructure. The MCP
+server is a contributor protocol adapter over that infrastructure, not a new
+workflow engine.
+
+## Human judgment required
+
+Maintainers must confirm the temporary service layer remains acceptable until
+contributor-list, lifecycle, review, and contribution APIs land, and must
+explicitly approve the foundation PR for merge. Full WS-MCP-001 acceptance
+must not be claimed from test-fixture behavior alone.
+
+## Initial risk class
+
+L1

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/PLAN.md

@@ -0,0 +1,95 @@
+# Plan: WS-MCP-001 - Workstream Contributor MCP Server
+
+## Proposed approach
+
+Create a separate Python MCP server package in this repository. Keep the public
+MCP catalogue closed to the approved WS-MCP-001 v0.1 surface and route all
+available product behavior through the existing Workstream HTTP API.
+
+Unavailable contributor project/task lists, contributions, review surfaces, and
+incompatible contributor lifecycle actions are represented by a temporary
+scenario gateway that is explicit, deterministic, test-injected, and
+replaceable. The HTTP gateway must fail closed for any existing route whose
+actor scope, lifecycle semantics, or idempotency guarantees do not satisfy
+WS-MCP-001.
+
+## Design chosen
+
+- `workstream_mcp.server` owns MCP registration.
+- `workstream_mcp.gateway` defines the contributor gateway interface.
+- `workstream_mcp.http_gateway` calls only semantically compatible Workstream
+  HTTP APIs and fails closed for incompatible lifecycle routes.
+- `workstream_mcp.scenario_gateway` supplies temporary deterministic behavior
+  only where APIs are unavailable.
+- `workstream_mcp.auth` owns token propagation and redaction helpers.
+- `workstream_mcp.schemas` owns stable resource/tool metadata and request
+  shapes.
+- CI runs the MCP package lint and tests in a separate workflow job.
+
+## Alternatives considered
+
+### Direct database access
+
+Rejected because MCP must not bypass Workstream authorization or lifecycle
+services.
+
+### Generic `call_api` MCP tool
+
+Rejected because WS-MCP-001 requires a closed contributor-facing catalogue with
+stable tool names and schemas.
+
+### Blocking until review and contribution APIs exist
+
+Rejected because the maintainer approved a temporary service layer to avoid
+blocking current MCP work.
+
+## Boundaries preserved
+
+- Auth/session: the same issuer bearer token is forwarded to Workstream.
+- Permission/policy: Workstream authorization remains authoritative.
+- Payment/execution: MCP does not calculate contribution, compensation, or
+  payment state.
+- Persistence/data: MCP adds no database or durable business state.
+- Presentation/API: no frontend work.
+- CI/deployment: additive MCP checks only; no existing workflow or gate
+  weakening.
+
+## Specification acceptance boundary
+
+This chunk establishes the closed public catalogue, boundary architecture,
+stable schemas, safe production degradation, and temporary protocol fixtures.
+It is PR-ready as a foundation chunk, but it is not a claim that WS-MCP-001 v0.1
+has passed the complete conformance or acceptance gates in Sections 18 and 20.
+
+Full acceptance remains dependent on authoritative backend APIs and evidence
+for role variants and revocation, initial and revised submissions, all status
+outcomes, concurrent claims, retry behavior, STDIO/Streamable HTTP equivalence,
+and an Inspector/client demonstration.
+
+## Rollout/migration strategy
+
+Land the MCP package as an additive contributor adapter. When Workstream adds
+review, contribution, list, atomic contributor claim/release, and durably
+idempotent submission APIs, replace temporary scenario-gateway methods with
+real HTTP gateway calls without changing the MCP public catalogue.
+
+## Verification strategy
+
+Use focused MCP tests for catalogue closure, token safety, HTTP API path
+mapping, temporary Submitter/Reviewer happy paths, actor-scoped leases and
+replay, safe error envelopes, protocol registration, and the absence of
+subscriptions/events. Run repository gate scripts before PR. Record remaining
+WS-MCP-001 conformance cases as follow-up evidence rather than treating the
+temporary fixture as production proof.
+
+## Review strategy
+
+Required reviewers: senior engineering, QA/test, security/auth, product/ops,
+architecture, CI integrity, docs, reuse/dedup, and test delta.
+
+## Sequencing
+
+`WS-MCP-001-01` installs the contributor MCP foundation. A later explicit chunk
+replaces every temporary method with authoritative project/task list,
+contribution, contributor lifecycle, and review API calls, then closes the
+remaining Sections 18 and 20 evidence.

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/RISKS.md

@@ -0,0 +1,12 @@
+# Risks: WS-MCP-001 - Workstream Contributor MCP Server
+
+| Risk | Severity | Mitigation |
+|---|---:|---|
+| MCP accidentally becomes a second workflow engine | High | Keep handlers thin and route behavior through `ContributorGateway`; no direct database access. |
+| Temporary review/contribution service leaks into production use | High | Make scenario gateway opt-in and label it temporary in code, tests, and docs. |
+| Tokens appear in tool inputs, resource URIs, logs, or results | High | Centralize token context and add redaction/token-safety tests. |
+| MCP catalogue expands beyond WS-MCP-001 v0.1 | Medium | Test exact resource/tool names and zero prompts. |
+| Backend unavailable APIs force schema churn later | Medium | Keep stable MCP schemas and replace only gateway methods when APIs land. |
+| Existing lifecycle routes have incompatible actor scope, state transitions, or idempotency | High | Fail closed in the production HTTP gateway; use a test-injected scenario fixture only for foundation contract testing until compatible APIs land. |
+| Streamable HTTP is exposed to an untrusted browser origin | High | Use FastMCP transport-security host/origin allowlists and disable SSE transport. |
+| Temporary happy-path tests are mistaken for full WS-MCP-001 conformance | High | State explicitly that Sections 18 and 20 remain open until authoritative APIs, both transports, role/revocation cases, concurrency, retries, and the Inspector/client demonstration are proven. |

.agent-loop/initiatives/WS-MCP-001-contributor-mcp-server/STATUS.md

@@ -0,0 +1,42 @@
+# Status: WS-MCP-001 - Workstream Contributor MCP Server
+
+## Current status
+
+`WS-MCP-001-01` addressed all current maintainer and CodeRabbit MCP-scope
+findings and received final review results through reconciled head `f5b519c`.
+It is open as
+[PR #149](https://github.com/Flow-Research/workstream/pull/149)
+from branch
+`oxvictor/ws-mcp-001-01-contributor-mcp-foundation`.
+
+This status means the foundation chunk is PR-ready. It does not mean the full
+WS-MCP-001 Sections 18 and 20 conformance and acceptance gates are complete.
+
+## Active implementation chunk
+
+`WS-MCP-001-01` - Contributor MCP Foundation.
+
+## Current implementation branch
+
+`oxvictor/ws-mcp-001-01-contributor-mcp-foundation`
+
+## Chunk status
+
+| Chunk | Status | Branch | PR | Notes |
+|---|---|---|---:|---|
+| `WS-MCP-001-01` | Final review ready to push | `oxvictor/ws-mcp-001-01-contributor-mcp-foundation` | [#149](https://github.com/Flow-Research/workstream/pull/149) | Current `main` at `5a8a924` is integrated as `f5b519c` without MCP-file changes; 113 MCP tests pass at 95.27 percent coverage. GitHub checks remain pending after push. |
+| `WS-MCP-001-02` | Proposed | - | - | Replace every temporary method with authoritative APIs and close the remaining Sections 18 and 20 evidence. |
+
+## Blockers
+
+Production completion is blocked on compatible Workstream APIs. Review,
+contribution, and contributor-list APIs are unavailable on current main; the
+current task claim, release, and submission routes also do not meet the MCP's
+actor, lifecycle, or durable-idempotency contract. The production HTTP gateway
+returns a structured unavailable result for those surfaces. The bounded
+scenario gateway is test-injected only and is not a production fallback.
+
+Full WS-MCP-001 acceptance also remains blocked on authoritative role and
+revocation cases, initial/revision/status outcomes, concurrent retry behavior,
+STDIO/Streamable HTTP equivalence, and the required Inspector/client
+demonstration.