pr-narrator-mcp: Instructions file for Codex

AGENTS.md — Coding Agent Instructions for pr-narrator-mcp

Project Summary

pr-narrator-mcp is an MCP (Model Context Protocol) server that generates commit messages, PR titles, PR descriptions, and related content from git repository state. It is published to npm as pr-narrator-mcp and runs as a CLI tool via npx pr-narrator-mcp.

• Runtime: Node.js >=18, TypeScript 5.3+, ESM ("type": "module")
• Dependencies: @modelcontextprotocol/sdk ^1.26.0, simple-git ^3.22.0, zod ^3.22.4
• Build: tsup (ESM output, single entry src/index.ts, target node18)
• Test: Vitest with globals, v8 coverage, Node environment
• Lint: ESLint with @typescript-eslint/recommended-requiring-type-checking + Prettier
• CI: GitHub Actions on Node 18/20/22 matrix

---

Build & Test Commands

npm install            # Install dependencies
npm run typecheck      # tsc --noEmit (run FIRST — must pass before test/build)
npm run test:run       # vitest run (single pass)
npm test               # vitest (watch mode)
npm run test:coverage  # vitest with v8 coverage
npm run build          # tsup → dist/
npm run lint           # eslint src/ test/
npm run lint:fix       # eslint --fix
npm run format         # prettier --write
npm run format:check   # prettier --check

Validation order: npm run typecheck → npm run test:run → npm run build → npm run lint

CI runs this matrix on Node 18, 20, and 22. Always verify your changes pass on Node 18 (the minimum).

---

Project Layout

src/
├── index.ts                        # MCP server entry, tool registration, stdio transport
├── config/
│   ├── schema.ts                   # Zod config schemas, defaults, type exports
│   └── loader.ts                   # Config loading from MCP env vars
├── tools/                          # One file per MCP tool (10 tools total)
│   ├── get-config.ts
│   ├── analyze-git-changes.ts
│   ├── generate-commit-message.ts
│   ├── validate-commit-message.ts
│   ├── extract-tickets.ts
│   ├── generate-pr-title.ts
│   ├── generate-pr-description.ts
│   ├── generate-pr.ts
│   ├── get-pr-template.ts
│   └── generate-changelog.ts
└── utils/
    ├── git.ts                      # Git operations via simple-git, path validation, branch detection
    └── formatters.ts               # String formatting, prefix handling, file categorization

test/                               # Mirrors src/ structure
├── config/
│   └── loader.test.ts
├── tools/
│   └── *.test.ts                   # One test file per tool
└── utils/
    ├── formatters.test.ts
    └── git.test.ts