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

{
  "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.

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

{
  "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.