# sdlc-workflow-mcp

A standalone stdio [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a
bounded, fictional-data slice of the SDLC workflow tools for local Copilot use.

> **Provenance:** extracted from [`Tingsum26/sdlc-agent-platform`](https://github.com/Tingsum26/sdlc-agent-platform)
> at the `seven-repo-split-baseline` tag (commit `bf48e15`), source path `apps/workflow-mcp`.
> This repository is one slice of the seven-repository split described in the platform BOM
> ([`docs/platform-bom.yaml`](docs/platform-bom.yaml)).

## What this is

- A TypeScript MCP server (`stdio` transport) that proxies a bounded set of workflow tools to a
  local Workflow Service over HTTP.
- All fixtures are fictional (`example.invalid`, `REPO_A`, `DEMO-123`, `EPIC-DEMO-1`, fictional
  identities). There is no model client, no credentials, and no real company data in this slice.

## What this is not (registered gap)

The full approved tool catalog in the platform BOM is larger than this slice. This repository
registers only the subset implemented in the `apps/workflow-mcp` vertical slice at split time
(workflow tasks, internal-readiness, epic/ticket/repo-task, change-request, and journey tools).
Remaining catalog tools are tracked in the originating platform BOM and its migration map, not here.

## Tool catalog

42 tools are registered, grouped below. Per-tool source endpoints and local-derivation fallbacks
are documented in [`docs/tool-catalog.md`](docs/tool-catalog.md).

**workflow** (task, ticket, epic, decision, artifact, and Jira-projection operations):

`workflow_list_my_tasks`, `workflow_get_task_context`, `workflow_get_task_audit`,
`workflow_claim_task`, `workflow_submit_artifact`, `workflow_request_approval`,
`workflow_complete_task`, `workflow_get_identity`, `workflow_validate_pod_roster`,
`workflow_import_pod_roster`, `workflow_get_integration_diagnostics`, `workflow_analyze_journey`,
`workflow_get_next_internal_validation`, `workflow_epic_create`, `workflow_epic_activate`,
`workflow_epic_attach_ticket`, `workflow_ticket_advance`, `workflow_ticket_add_repo_task`,
`advance_repo_task`, `workflow_epic_add_dependency`, `workflow_epic_create_change_request`,
`workflow_epic_approve_change_request`, `workflow_task_skip`, `workflow_epic_resume`,
`workflow_epic_join`, `workflow_get_related_artifacts`, `workflow_submit_decision`,
`workflow_assign_work`, `workflow_report_blocker`, `workflow_record_manual_e2e`,
`workflow_record_accessibility_result`, `workflow_record_tagging_result`,
`workflow_prepare_jira_projection`.

**onboarding-context** (repository/journey onboarding, context scan, graphs, freshness, staleness):

`workflow_get_freshness`, `workflow_onboard_repository`, `workflow_onboard_journey`,
`workflow_sync_onboarding_artifact`, `workflow_scan_repository_context`,
`workflow_analyze_http_dependencies`, `workflow_get_repository_graph`,
`workflow_get_journey_graph`, `workflow_mark_context_stale`.

## Prerequisites

- Node.js >= 20.19.0
- pnpm

## Build and test

```sh
pnpm install
pnpm build
pnpm test
```

## Starting the stdio server

The server requires a Workflow Service URL and speaks MCP over stdio:

```sh
pnpm install
pnpm build
WORKFLOW_SERVICE_URL=http://127.0.0.1:8080 node dist/index.js
```

Environment variables:

| Variable                 | Required | Description                                                             |
| ------------------------ | -------- | ----------------------------------------------------------------------- |
| `WORKFLOW_SERVICE_URL`   | yes      | Base URL of the local Workflow Service (e.g. `http://127.0.0.1:8080`).  |
| `WORKFLOW_DEMO_USER`     | no       | Demo identity; allowed only when the service host is loopback.          |

On startup failure or missing configuration, the server writes a structured JSON diagnostic to
`stderr` and exits with code `2`.

## Layout

- `src/` — MCP server, API client, diagnostics, and tool registration.
- `test/` — vitest suite covering tool discovery, correlation IDs, audit visibility, safe error
  mapping, cancellation, and stderr redaction.