# mcp-dev-workflow

[![npm](https://img.shields.io/npm/v/@sergiorodas/mcp-dev-workflow.svg)](https://www.npmjs.com/package/@sergiorodas/mcp-dev-workflow)
[![license](https://img.shields.io/npm/l/@sergiorodas/mcp-dev-workflow.svg)](./LICENSE)

An **[MCP](https://modelcontextprotocol.io) server** that gives AI assistants
(Claude, Cursor, …) a set of **deterministic, convention-enforcing tools** to
standardize the development workflow from issue to pull request.

These are the kind of tools an assistant calls to do something *precise* —
generate a branch name, validate a commit, draft a PR body — rather than
free-form generation. Same input, same output, every time.

> Public, runnable distillation of an AI-agent workflow I built to automate the
> Jira issue → PR lifecycle.

---

## Tools

| Tool | What it does |
| --- | --- |
| `branch_name` | Turn `{ type, id, title }` into a convention-following git branch name. |
| `commit_message` | Validate & normalize a [Conventional Commit](https://www.conventionalcommits.org); returns `{ valid, normalized, errors, warnings, parsed }`. |
| `pr_checklist` | Turn a list of commits (and optional changed files) into a Markdown PR body: summary, changes grouped by type, and a checklist. |

Every tool exposes a JSON Schema for both its **input** and its **output**
(structured content), so capable clients get typed results, not just text.

---

## Install

The server runs over stdio and needs no install — point your MCP client at it
via `npx`.

### Claude Desktop

Edit `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/`,
Windows: `%APPDATA%\Claude\`):

```jsonc
{
  "mcpServers": {
    "dev-workflow": {
      "command": "npx",
      "args": ["-y", "@sergiorodas/mcp-dev-workflow"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```jsonc
{
  "mcpServers": {
    "dev-workflow": {
      "command": "npx",
      "args": ["-y", "@sergiorodas/mcp-dev-workflow"]
    }
  }
}
```

Restart the client and the three tools appear. Requires **Node 18+**.

---

## Tool reference

### `branch_name`

Generate a git branch name from a change type, ticket id and title.

| Param | Type | Default | Notes |
| --- | --- | --- | --- |
| `type` | enum | — | `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` |
| `id` | string | — | Ticket id, e.g. `ABC-123`. Case preserved. |
| `title` | string | — | Short title, slugified (lowercased, accents stripped). |
| `separator` | string | `-` | Joins id and slug, and words within the slug. |
| `maxLength` | number | — | Optional cap; the slug is truncated to fit. |

```jsonc
// in:  { "type": "feat", "id": "ABC-123", "title": "Add login" }
// out: "feat/ABC-123-add-login"
```

### `commit_message`

Validate and normalize a Conventional Commit (`type(scope): subject`).

| Param | Type | Default | Notes |
| --- | --- | --- | --- |
| `message` | string | — | Commit message; the first line is the header. |
| `allowedTypes` | string[] | the 11 types above | Override the accepted types. |
| `maxSubjectLength` | number | `72` | Max subject length. |
| `requireScope` | boolean | `false` | Make `(scope)` mandatory. |

Checks the header format, the type, subject length, a trailing period, and hints
at non-imperative mood. Returns `{ valid, normalized, errors, warnings, parsed }`.

```jsonc
// in:  { "message": "feat(auth): added login." }
// out: {
//   "valid": true,
//   "normalized": "feat(auth): added login",
//   "warnings": [
//     "Subject should not end with a period.",
//     "Use the imperative mood in the subject (e.g. 'add' instead of 'added'/'adds')."
//   ],
//   "parsed": { "type": "feat", "scope": "auth", "breaking": false, "subject": "added login" }
// }
```

### `pr_checklist`

Build a Markdown PR body from a list of commits.

| Param | Type | Default | Notes |
| --- | --- | --- | --- |
| `commits` | string[] | — | Commit messages (or just their headers). |
| `changedFiles` | string[] | `[]` | Optional file list to include. |
| `title` | string | — | Optional `# Heading`. |

Groups commits by conventional type, detects breaking changes (`!` or a
`BREAKING CHANGE:` footer), and emits a tests/docs/breaking-changes checklist.

```markdown
## Summary

<!-- Describe what this PR does and why. -->

2 commits across 2 areas.

## Changes

### Features
- add login **(auth)**

### Fixes
- handle null user

## Checklist

- [ ] Tests added or updated
- [ ] Documentation updated
- [x] No breaking changes
- [ ] Self-reviewed the diff
```

---

## Development

This project dogfoods the conventions it preaches.

```bash
npm install
npm run dev        # run the server from source (tsx)
npm run typecheck  # tsc --noEmit
npm test           # vitest
npm run build      # tsup -> dist/
```

Architecture: pure logic lives in [`src/lib/`](./src/lib) as plain,
unit-tested functions with no MCP coupling; [`src/tools/`](./src/tools) wraps
each one in an MCP tool definition with a [zod](https://zod.dev) schema;
[`src/index.ts`](./src/index.ts) registers them on the stdio server.

---

## License

MIT © Sergio Rodas