                ███████╗███╗   ██╗ ██████╗    ███████╗████████╗██████╗ ███████╗
                ██╔════╝████╗  ██║██╔════╝    ██╔════╝╚══██╔══╝██╔══██╗██╔════╝
                █████╗  ██╔██╗ ██║██║  ███╗   ███████╗   ██║   ██║  ██║███████╗
                ██╔══╝  ██║╚██╗██║██║   ██║   ╚════██║   ██║   ██║  ██║╚════██║
                ███████╗██║ ╚████║╚██████╔╝██╗███████║   ██║   ██████╔╝███████║
                ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝╚══════╝   ╚═╝   ╚═════╝ ╚══════╝

                          ⚡ Engineering Standards MCP Server ⚡

                          Your engineering brain, exported as a protocol.

Good engineering habits shouldn't live in your head — they should be encoded, shareable, and enforceable.

     ┌──────────────┐          ┌──────────────────┐          ┌──────────────┐
     │              │  query   │                  │  read    │  ◆ git       │
     │  Claude Code ├─────────►│  MCP Server      ├─────────►│  ◆ reviews   │
     │  / Desktop   │          │  (this thing)    │          │  ◆ PRs       │
     │              │◄─────────┤                  │◄─────────┤  ◆ testing   │
     │              │ response │                  │ standard │  ◆ rails     │
     │              │          │                  │          │  ◆ frontend  │
     │              │          │                  │          │  ◆ deploy    │
     │              │          │                  │          │  ◆ incidents │
     │              │          │                  │          │  ◆ observe   │
     │              │          │                  │          │  ◆ api       │
     │              │          │                  │          │  ◆ database  │
     │              │          │                  │          │  ◆ ADRs      │
     │              │          │                  │          │  ◆ debt      │
     │              │          │                  │          │  ◆ staff     │
     └──────────────┘          └──────────────────┘          └──────────────┘
      YOU + AI                  Protocol Layer                 Standards DB

🛠️ Tools

Tool	Description
`get_standard`	Retrieve a specific engineering standard (14 available — see Standards Included below)
`review_branch_name`	Check if a branch name follows conventions
`review_commit_message`	Check if a commit message follows conventions
`staff_engineer_review`	Get the staff engineer thinking checklist for a given phase of work

📚 Standards Included

General

Standard	Key	Covers
Git Conventions	`git`	Branch naming, commits, rebase workflow, commit hygiene
Code Review	`code_review`	Tone, structure, what to look for, giving and receiving feedback
PR Standards	`pr`	Size, description, pre-merge checklist, hotfix protocol
Staff Engineer Checklist	`staff_engineer`	Thinking prompts for each phase of work

Rails

Standard	Key	Covers
Rails Standards	`rails`	Architecture, security, performance, migrations, Hotwire, deployment
Testing Philosophy	`testing`	Rails/RSpec strategy, FactoryBot, system specs, N+1 detection, CI integration

Frontend

Standard	Key	Covers
Frontend Standards	`frontend`	TypeScript, components, accessibility, state management, performance, testing, security

Operations

Standard	Key	Covers
Deployment Standards	`deployment`	Three-phase migration strategy, strong_migrations, zero-downtime deploys, rollback strategy
Incident Response	`incident_response`	Severity levels, incident commander, postmortems, on-call, game days
Observability	`observability`	Structured logging, metrics (RED/USE), alerting, SLIs/SLOs, dashboards, tracing

Architecture

Standard	Key	Covers
API Design	`api_design`	REST conventions, versioning, error format, pagination, idempotency
Database Design	`database_design`	PostgreSQL/Rails, indexing, constraints, partitioning, connection management
Architecture Decision Records	`architecture_decisions`	ADR template, when to write them, lifecycle, ADR vs RFC
Technical Debt	`technical_debt`	Classification, severity, when to pay it down, prevention, metrics

🤖 Companion Agents

The MCP provides the what (your team's standards). These agents provide the how (code generation and implementation).

From awesome-claude-code-subagents:

Agent	Role
rails-expert	Rails 7.x/8.x implementation, version-aware patterns, Hotwire, deployment
frontend-developer	React, Vue, Angular — TypeScript, accessibility, component architecture

When the MCP returns a standard, it includes a reference to the relevant agent. Claude Code can then delegate implementation to that agent automatically.

⚙️ Setup

1. Install

git clone https://github.com/rajgurung/claude-engineering-standards.git
cd claude-engineering-standards
npm install
npm run build

2. Register

Add to your MCP settings file:

Client	Config file
Claude Code	`~/.claude/.mcp.json` (or project-level)
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "engineering-standards": {
      "command": "node",
      "args": ["/absolute/path/to/engineering-standards-mcp/build/index.js"]
    }
  }
}

📋 Wiring It Into Your Projects

Once the MCP is registered, add a CLAUDE.md to your project root so Claude Code knows to consult it:

## Engineering Standards

This project follows team engineering standards via the engineering-standards MCP server.

### Before writing code
- Call `get_standard("rails")` for architecture and conventions
- Call `get_standard("testing")` for test strategy
- Call `get_standard("api_design")` before building or modifying API endpoints
- Call `get_standard("database_design")` before schema changes
- Call `get_standard("deployment")` before any migration or deploy work

### Before committing
- Call `review_branch_name` to validate your branch name
- Call `review_commit_message` to validate your commit message

### Before opening a PR
- Call `staff_engineer_review` with phase `before_pr`
- Call `get_standard("code_review")` for review expectations

### During incidents
- Call `get_standard("incident_response")` for severity levels and response protocol
- Call `get_standard("observability")` for debugging and monitoring guidance

### Implementation
- Use the rails-expert agent for Rails code generation
- Use the frontend-developer agent for frontend work

Adapt this to your stack — remove what doesn't apply, add project-specific rules. The CLAUDE.md stays small because the standards live in the MCP, not in every repo.

🎨 Customising

The standards are plain markdown files in src/standards/. Edit them to match your team's conventions, then rebuild:

src/standards/
├── git-conventions.md           ← branch naming, commits
├── code-review.md               ← review tone & structure
├── pr-standards.md              ← PR size, checklists
├── staff-engineer-checklist.md  ← thinking prompts
├── testing-philosophy.md        ← test strategy (Rails/RSpec)
├── rails-standards.md           ← Rails conventions + rails-expert agent
├── frontend-standards.md        ← Frontend conventions + frontend-developer agent
├── deployment-standards.md      ← Safe deploys, migrations, rollback strategy
├── incident-response.md         ← Severity levels, postmortems, on-call
├── observability.md             ← Logging, metrics, alerting, SLIs/SLOs
├── api-design.md                ← REST conventions, versioning, error format
├── database-design.md           ← PostgreSQL/Rails, indexing, partitioning
├── architecture-decisions.md    ← ADR template and lifecycle
└── technical-debt.md            ← Classification, prioritisation, prevention

npm run build

🧑‍💻 Development

npm run dev    # Watch mode — recompiles on change
npm run build  # One-off build
npm start      # Run the server

📄 License

MIT

engineering-standards