# Refactoring MCP — PRD

This project turns the Refactoring MCP prompt and governance specification templates into a dedicated MCP server so teams can host structured prompt generation via HTTP and automation scripts.

## 1. MCP Server Goal

- **What is this project?**  
  A dedicated MCP server (built on `@modelcontextprotocol/sdk`) that exposes MCP tools for generating protocol and governance prompt payloads following the Refactoring MCP standards.
- **What problem does it solve?**  
  Documentation-only templates are hard to integrate; this MCP server exposes prompt builders via HTTP so downstream automation and review tooling can consume the specs.
- **Who is the primary user?**  
  Platform engineers, MCP reviewers, or automation scripts needing consistent refactoring governance messaging via MCP workflows.

## 2. Success Definition

- **How do we know this project is successful?**  
  The npm package publishes, the MCP server starts, and prompts can be generated and stored via the `refactoring_mcp_*` tools.
- **What measurable outcome must be achieved?**  
  `npm test` succeeds, `npm start` (or `refactoring-mcp`) brings the MCP service online, and at least one prompt record can be created through the MCP tools.
- **What does failure look like?**  
  Prompt definitions remain stuck in Markdown without API access, or the automated validation/tests do not run.

## 3. Core MCP Server Action

- **What is the single most important action a user performs?**  
  Start the MCP server (via `npm start` or `refactoring-mcp`), host the API, and POST a protocol/governance prompt definition for downstream tooling.
- **What moment should make the user say “this works”?**  
  A successful `POST /api/prompts` followed by a `GET /api/prompts/:id` that returns the prompt text and metadata.

## 4. Non-Goals

- **What will this project NOT attempt to do?**  
  It does not persist prompts beyond in-memory, support authentication, or orchestrate remote agents.
- **What features are explicitly out of scope?**  
  Any persistent database, full LLM orchestration, or advanced scheduling can be deferred to future MCPs.

## 5. Constraints

- **Time constraints:** Keep the MVP lean for npm publishing—no long-running refactors.
- **Scope constraints:** Single MCP server (Express + prompt builders) without sprawling CLI features.
- **Resource constraints:** Only trusted dependencies (Express, built-in Node modules) are permitted.

## Validation Check

- **Can the project goal be explained in one sentence?** Yes — “Expose Refactoring MCP prompts via an Express API and CLI for automation-ready tooling.”
- **Can success be evaluated without subjective judgment?** Yes — endpoints respond successfully and tests pass.

## 6. MCP Server Usage

### Installation

- `npm install -g refactoring-mcp` (or `npm install refactoring-mcp` for local use).

### Run (stdio)

- `refactoring-mcp` or `npm start` boots the MCP server on port 3000 by default.
- Use `--port <number>` (or `-p`) or set the `PORT` env var to change the listening port.

### Example MCP Client Config

```json
{
  "command": "npx",
  "args": ["-y", "refactoring-mcp"]
}
```

### Tools

- `service_status` → return service metadata (name, version, uptime, timestamp).
- `refactoring_mcp_list_documents` → list the guidance documents that describe this MCP.
- `refactoring_mcp_get_document` → fetch a specific guidance document by key.
- `refactoring_mcp_get_bundle` → download all guidance documents in one bundle.
- `refactoring_mcp_generate_prompt` → build a protocol or governance prompt, validate the schema, and store the payload.
- `refactoring_mcp_list_prompts` → inspect saved prompt metadata and timestamps.
- `refactoring_mcp_get_prompt` → retrieve a stored prompt by `id`.

### Documents

- `spec` → `docs/spec-prompts.md` (protocol & governance spec templates).
- `trd` → `TRD.md` (technical boundaries for the MCP server).
- `mcp_server` → `docs/mcp-server.md` (server responsibilities and customization steps).
- `agents` → `examples/AGENTS.md` (agent instructions tied to this MCP).
- `trd_questions` → `prompts/trd.questions.md` (prompt template for drafting the TRD).

### Tool Overview

- `service_status` keeps MCP agents aware of the running version and uptime of the server.
- `refactoring_mcp_*` tools encapsulate prompt generation, doc discovery, and persisted prompt storage so other agents can consume the MCP output.

### MCP Server Runtime

- `refactoring-mcp` (installed globally) or `npm start` starts the MCP server so agents can access prompt specs.
- Override the port with `--port`, `-p`, or the `PORT` environment variable.

### Testing & Validation

- `npm test` runs `tsc` (build) and then `node --test ./dist/test/*.test.js`, covering the prompt builders, store, and validators.