AI Eng Ops With MCP

AI Engineering Operations Handbook

Accelerate engineering velocity with AI-driven workflows, intelligent code reviews, and best-practice automation

This handbook empowers engineering teams to scale their operations using AI agents guided by structured markdown files and the Model Context Protocol (MCP). Whether you're a startup building your first product or an enterprise maintaining complex systems, this toolkit helps you deliver high-quality code faster with AI-assisted engineering workflows.

✨ Features

• 📝 Markdown-Driven Engineering Workflows: Define and standardize engineering processes using simple, version-controlled markdown files
• 🧠 Model Context Protocol (MCP) Integration: Leverage MCP to customize AI behavior for engineering-specific tasks and ensure contextually-aware code generation
• 🎯 Process-Driven AI Operations: Multi-step engineering execution with built-in code reviews, testing checkpoints, and quality gates
• 📋 Cursor Rules Integration: Enforce consistent AI behavior through project-specific rules and engineering best practices
• 🔄 Dynamic Context Switching: Seamlessly transition between different engineering domains (frontend, backend, DevOps, security)
• ⚡ Real-time Documentation: Keep technical documentation, runbooks, and architecture decisions automatically updated

🚀 How It Works

1. 📁 Set Up Your Repository: Clone this repository and organize your engineering-specific markdown files
2. 🏷️ Define Context and Standards: Use MCP to tag documents and establish AI behavior patterns for code generation and reviews
3. 🤖 Generate Code & Documentation: Let AI create production-ready code, tests, and technical documentation that align with your team's standards
4. 🔧 Iterate and Refine: Continuously improve your templates and processes based on AI output and team feedback

💡 Use Cases

AI-Powered Code Reviews

Your team submits a pull request. The AI automatically reviews code against your team's standards, checks for security vulnerabilities, suggests improvements, and ensures consistency with existing patterns—turning every PR into a learning opportunity.

Automated Test Generation

Connect your test framework to MCP. When you write new features, the AI generates comprehensive test suites including unit tests, integration tests, and edge cases based on your team's testing standards and coverage requirements.

Intelligent Incident Response

When production issues occur, the AI accesses your runbooks, recent changes, and monitoring data via MCP. It generates incident reports, suggests remediation steps, and documents post-mortems following your team's established processes.

Architecture Decision Records (ADRs)

Every significant technical decision gets automatically documented. The AI helps draft ADRs by pulling context from code, discussions, and existing decisions, ensuring nothing gets lost as teams scale.

Documentation That Stays Current

Technical documentation that actually reflects reality. The AI analyzes code changes and automatically updates relevant documentation, API specs, and onboarding guides—no more stale docs.

🛠️ Getting Started

Understanding Cursor v1 and MCP for Engineering

Cursor v1 represents a revolutionary leap in AI-powered development environments. At its core is the Model Context Protocol (MCP)—an open standard developed by Anthropic that standardizes how AI applications provide context and tools to Large Language Models.

Why MCP is a Game-Changer for Engineering Operations

Most AI coding assistants today are powerful but isolated—they don't have access to your codebase structure, deployment pipelines, test suites, or monitoring systems. MCP solves this fundamental problem by acting as a "universal connector" that allows AI to seamlessly access and interact with your engineering ecosystem.

The Traditional Problem: Before MCP, connecting AI to each engineering tool required custom integrations. Want your AI to access CI/CD pipelines? Custom code. Pull metrics from monitoring? Another integration. Read deployment runbooks? Yet another connector.

The MCP Solution: As explained by Anthropic, MCP "provides a universal, open standard for connecting AI systems with data sources, replacing fragmented integrations with a single protocol." Think of MCP as USB-C for AI applications—one standardized way to connect to everything.

The Power of Markdown + MCP: Engineering Context in Action

This handbook leverages a revolutionary approach: structured markdown files + MCP integration. Here's why this combination is transformative for engineering teams:

1. Layered Engineering Context Architecture

Your engineering context lives in multiple layers:

• Static Context: Coding standards, architecture patterns, tech stack guidelines (markdown files)
• Dynamic Context: Real-time test results, deployment status, monitoring metrics (MCP servers)
• Interactive Tools: Ability to run tests, deploy code, create tickets, review PRs (MCP tools)

2. Intelligent Context Blending

When you ask AI to "implement a new API endpoint," the system automatically:

# AI's Context Awareness Process:
1. Reads coding-standards.md (style and patterns)
2. Accesses architecture-decisions.md (system design principles)
3. Queries test results via MCP (current test coverage)
4. Pulls recent changes via MCP (avoiding conflicts)
5. Generates code following team patterns
6. Creates tests matching your suite structure
7. Can submit PR via MCP (if desired)

3. Version-Controlled Engineering Knowledge

Unlike traditional documentation, your engineering context is:

• Version-controlled: Track changes to standards and patterns over time
• Collaborative: Teams can contribute and review updates via PRs
• Portable: Works across different AI platforms and tools
• Transparent: See exactly what context influenced AI code generation

4. Scalable Context Management

As noted by industry experts, "MCP transforms AI from a passive tool into an active business driver." Your markdown files provide the foundation, while MCP connections enable real-time adaptation and action across your entire engineering stack.

🔄 Process-Driven AI Engineering Operations

One of the core principles of this handbook is intentional, multi-step AI execution. Instead of asking AI to complete complex engineering tasks in a single prompt, we break operations into structured, reviewable steps that ensure quality and maintain human oversight.

Why Process Matters in AI Engineering

Single-Step AI Problems:

• Lacks checkpoints for code quality control
• Difficult to iterate and improve incrementally
• Hard to maintain consistency across team members
• No built-in review mechanisms
• All-or-nothing outcomes increase risk

Multi-Step AI Benefits:

• Built-in quality gates and code reviews
• Iterative improvement at each stage
• Consistent execution across team members
• Clear audit trails and decision points
• Fail-safe mechanisms and rollback points

Example: Feature Development Process

Instead of "implement user authentication," we use this structured approach:

## Multi-Step Feature Development Process

1. **📝 Feature Brief**: Generate brief in `/briefs/` folder with requirements and acceptance criteria
2. **🏗️ Architecture Review**: Analyze existing patterns and design approach
3. **📋 Implementation Plan**: Create detailed plan with steps and dependencies
4. **💻 Code Implementation**: Write code iteratively, following team standards
5. **🧪 Test Creation**: Generate comprehensive test suite (unit, integration, e2e)
6. **🔍 Code Review**: Self-review against standards before peer review
7. **👥 Peer Review**: Submit PR with complete context and documentation
8. **✅ CI/CD Validation**: Ensure all checks pass (tests, linting, security scans)
9. **🚀 Deployment**: Deploy to staging for final validation
10. **📊 Monitoring**: Verify metrics and performance post-deployment

This process ensures each feature is thoroughly planned, tested, reviewed, and monitored before reaching production.

📋 Cursor Rules: Enforcing Engineering Process Discipline

Cursor Rules are powerful instructions that control how AI behaves in your development environment. Think of them as persistent training for your AI assistant that ensures consistent, process-driven engineering operations.

What Are Cursor Rules?

Cursor Rules are custom instructions stored in three levels:

1. Global Rules (Cursor Settings > Rules for AI): Universal guidelines applied to all projects
2. Project Rules (.cursor/rules/*.mdc): Repository-specific rules shared with your team
3. Legacy Rules (.cursorrules): Deprecated but still supported project-level rules

These rules ensure your AI assistant follows your established engineering processes and maintains quality standards across all code generation and review interactions.

How Cursor Rules Work

According to Cursor's documentation, "Large language models do not retain memory between completions. Rules solve this by providing persistent, reusable context at the prompt level." When a rule is applied, its contents are included at the start of the model context, giving the AI consistent guidance for generating code, interpreting edits, or helping with workflows.

Example Process-Enforcing Cursor Rules

Here's how we use Cursor Rules to enforce our multi-step engineering process:

# Engineering Process Rules

## Multi-Step Execution Required
When implementing any feature or fixing bugs:

1. ALWAYS start by creating a brief or issue analysis in `/briefs/` folder
2. NEVER write code without understanding existing patterns first
3. ALWAYS create tests alongside code (TDD when possible)
4. MUST include review checkpoints before merging
5. REQUIRE passing CI/CD pipeline before deployment

## Code Quality Standards
- Every function must have tests with >80% coverage
- Follow team coding standards (reference coding-standards.md)
- Include error handling and logging
- Write self-documenting code with clear names
- Update documentation for public APIs

## Process Violations
If asked to skip steps:
- Explain why the full process is important
- Offer to complete abbreviated version with clear limitations
- Document any shortcuts taken for future review

Benefits of Rules-Enforced Processes

Consistency Across Team Members:

• Junior and senior engineers get same quality guidance
• Processes are followed even when team members are busy or distracted
• New hires quickly learn and follow established workflows

Quality Assurance:

• Built-in checkpoints prevent low-quality code
• Testing requirements ensure reliability
• Review steps catch errors before production

Audit Trail and Compliance:

• Clear documentation of process steps taken
• Easy to identify where quality issues originated
• Meets compliance requirements for regulated industries

Setting Up Process-Driven Rules

Global Engineering Rules (Apply to all projects):

# Engineering Process Discipline Rules

## Multi-Step Approach Required
- Break complex tasks into 3-10 sequential steps
- Create deliverables at each major checkpoint  
- Always include testing and review stages
- Document assumptions and architectural decisions

## Quality Gates
- Write tests before or alongside code
- Review existing patterns before implementing
- Run linters and formatters before committing
- Get code review approval before merging

Project-Specific Process Rules (.cursor/rules/code-review.mdc):

---
description: Code review process for all pull requests
alwaysApply: true
---

# Code Review Process

When reviewing code:

1. Brief analysis in `/briefs/[pr-number]-review.md`
2. Security vulnerability check
3. Performance impact assessment
4. Test coverage verification
5. Documentation completeness check
6. Suggest improvements with context
7. Approve with conditions if needed

Never approve code without:
- Passing CI/CD pipeline
- Adequate test coverage
- Security scan approval
- Documentation updates

Reference coding-standards.md and architecture-decisions.md for consistency.

This systematic approach ensures that AI engineering operations are deliberate, reviewable, and consistently high-quality—transforming AI from a quick-answer tool into a reliable engineering process engine.

MCP Architecture in Cursor

Cursor's MCP implementation uses a client/server model with three key components:

• MCP Host: Cursor IDE itself, containing orchestration logic
• MCP Client:可 Converts user requests into structured formats the protocol can process
• MCP Server: External services (GitHub, CI/CD, monitoring) that provide context to the AI

Cursor supports three transport types for MCP servers:

Prerequisites

• Cursor IDE with MCP support (latest version)
• Git for version control
• Node.js/Python (for custom MCP server development)
• Basic familiarity with markdown syntax and JSON configuration

Quick Start

1. Clone and Set Up Repository

git clone https://github.com/your-username/ai-eng-ops-handbook.git
cd ai-eng-ops-handbook

2. Configure MCP Servers in Cursor

One-Click Installation (Recommended):

1. Open Cursor Settings → Features → MCP
2. Browse the curated MCP server collection
3. Install popular servers with OAuth support for instant authentication

Manual Configuration: Create MCP configuration files based on your needs:

Project-Specific (.cursor/mcp.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://..."
      }
    }
  }
}

Global Configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "web-search": {
      "command": "npx",
      "args": ["-y", "@smithery/cli", "run", "@mzxrai/mcp-webresearch", "--config", "{}"]
    },
    "slack": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token"
      }
    }
  }
}

3. Set Up Your Engineering Context

Create Template Structure:

ai-eng-ops-handbook/
├── templates/
│   ├── code-review/
│   ├── testing/
│   ├── deployment/
│   └── documentation/
├── contexts/
│   ├── engineering/
│   ├── infrastructure/
│   ├── security/
│   └── standards/
└── .cursor/
    └── mcp.json

Define Coding Standards (contexts/standards/coding-standards.md):

# Coding Standards

## Style Guide
- Use TypeScript for new projects
- Follow ESLint and Prettier configurations
- Maximum function length: 50 lines
- Maximum file length: 300 lines

## Naming Conventions
- Variables: camelCase
- Functions: camelCase with verb prefix
- Classes: PascalCase
- Constants: UPPER_SNAKE_CASE

## Key Patterns
- Prefer composition over inheritance
- Use dependency injection for testability
- Implement error boundaries for resilience

4. Set Up Process-Driven Rules

Configure Cursor Rules to enforce quality processes:

Global Rules (Cursor Settings > Rules for AI):

# Engineering Operations Process Rules

## Multi-Step Execution Required
- Break complex tasks into sequential, reviewable steps
- Always create briefs in /briefs/ folder before implementation
- Complete design phase before writing code
- Include review checkpoints and approval gates
- Document all architectural decisions

## Quality Standards
- Minimum 80% test coverage for new code
- All code must pass linting and formatting checks
- Security scans must pass before merging
- Documentation updated for public APIs

Project Rules (.cursor/rules/*.mdc): The handbook includes modular process rules organized by engineering domains:

• general-operations.mdc: Universal standards (always applied)
• code-review.mdc: PR reviews, code quality checks, security audits
• testing.mdc: Test generation, coverage requirements, TDD workflows
• deployment.mdc: CI/CD workflows, release processes, rollback procedures
• incident-response.mdc: On-call procedures, debugging workflows, post-mortems

This modular approach ensures only relevant rules load based on your current work context, maximizing efficiency while maintaining process discipline.

5. Using MCP in Cursor

Once configured, Cursor's Composer Agent will automatically use MCP tools when relevant. You can:

• Let AI decide: The agent automatically selects appropriate tools
• Explicit requests: "Use the GitHub API to check PR status..."
• Tool management: Enable/disable specific MCP tools in settings

Example Workflow:

# In Cursor Chat
Implement user authentication endpoint with JWT, 
following our security standards and existing API patterns.

# AI will automatically:
1. Access coding-standards.md (style and patterns)
2. Pull security requirements via MCP
3. Check existing API patterns via GitHub MCP
4. Generate code following team standards
5. Create tests matching your suite structure
6. Update API documentation

6. Advanced Configuration

Environment Variables for secure API management:

# .env file
GITHUB_TOKEN=ghp_xyz
DATABASE_URL=postgresql://...
SLACK_BOT_TOKEN=xoxb-123
CI_API_KEY=secret_xyz

Custom Engineering MCP Server (Example in TypeScript):

// engineering-context-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "engineering-context",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "get_code_metrics",
    description: "Retrieve code quality metrics from SonarQube",
    inputSchema: {
      type: "object",
      properties: {
        project: { type: "string" }
      }
    }
  }]
}));

// Tool implementation...

Testing Your Setup

1. Verify MCP Connection: Check Cursor Settings → Features → MCP to see active servers
2. Test Tool Access: In Cursor Chat, ask "What MCP tools are available?"
3. Generate Sample Code: Request AI to create code using your engineering context
4. Iterate and Refine: Adjust templates and configurations based on AI output quality

Next Steps

• Explore the MCP server directory for additional integrations
• Set up webhooks for real-time context updates from CI/CD systems
• Create custom MCP servers for proprietary engineering systems
• Implement automated code review workflows using MCP-driven AI

🔧 Fork & Customize: Your Engineering Blueprint

This handbook is designed as a starting point and blueprint that you'll fork and customize for your specific engineering needs. The goal is to demonstrate how much more powerful AI becomes when it's given rich, structured context about how your engineering team operates.

Why Fork This Handbook?

AI + Context = Engineering Velocity: The engineering teams that will thrive in the AI-native future are those that can provide their AI systems with deep, structured understanding of their codebases, patterns, and processes. This isn't just about having better prompts—it's about creating AI that truly understands your engineering practices.

Step 1: Fork and Personalize

1. Fork the Repository

   # Fork on GitHub, then clone your version
   git clone https://github.com/your-username/ai-eng-ops-handbook.git
   cd ai-eng-ops-handbook
   
   # Make it yours
   git remote add upstream https://github.com/original-repo/ai-eng-ops-handbook.git

1. Customize the Core Identity

   # Update project references
   find . -name "*.md" -exec sed -i 's/ai-eng-ops-handbook/your-team-eng-handbook/g' {} +

Step 2: Define Your Engineering Context

Replace the template files with your actual engineering context:

Coding Standards (contexts/standards/coding-standards.md)

# [Your Team] Coding Standards

## Language & Framework Preferences
- [Your primary languages and versions]
- [Framework choices and rationale]
- [Library preferences and avoided packages]

## Code Style
- [Your linting rules and formatters]
- [Naming conventions specific to your domain]
- [File organization patterns]

## Architecture Patterns
- [Design patterns you favor]
- [Anti-patterns to avoid]
- [SOLID principles application]

Architecture Decisions (contexts/architecture/decisions.md)

# Architecture Decision Records

## ADR-001: Microservices vs Monolith
- **Status**: Accepted
- **Context**: [Why this decision was needed]
- **Decision**: [What you chose]
- **Consequences**: [Impact and trade-offs]

Engineering Processes (contexts/engineering/processes/)

Create files for your specific engineering processes:

• code-review-process.md
• deployment-workflow.md
• incident-response.md
• testing-strategy.md

Step 3: Connect Your Engineering Tools

Customize the MCP configuration for your specific tools:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    },
    "jenkins": {
      "command": "npx", 
      "args": ["-y", "jenkins-mcp-server"],
      "env": {
        "JENKINS_URL": "https://ci.yourcompany.com",
        "JENKINS_API_TOKEN": "your-token"
      }
    },
    "datadog": {
      "command": "npx",
      "args": ["-y", "datadog-mcp-server"],
      "env": {
        "DATADOG_API_KEY": "your-key"
      }
    }
  }
}

Step 4: Domain-Specific Customization

For Backend Teams

# Backend-Specific Templates
├── templates/
│   ├── api-endpoint.md
│   ├── database-migration.md
│   ├── service-integration.md
│   └── error-handling.md
├── contexts/
│   ├── api-design.md
│   ├── database-patterns.md
│   └── service-architecture.md

For Frontend Teams

# Frontend-Specific Templates
├── templates/
│   ├── component-development.md
│   ├── state-management.md
│   ├── accessibility-checklist.md
│   └── performance-optimization.md
├── contexts/
│   ├── design-system.md
│   ├── ui-patterns.md
│   └── browser-compatibility.md

For DevOps Teams

# DevOps-Specific Templates
├── templates/
│   ├── infrastructure-as-code.md
│   ├── deployment-pipeline.md
│   ├── monitoring-setup.md
│   └── security-hardening.md
├── contexts/
│   ├── infrastructure.md
│   ├── ci-cd-standards.md
│   └── monitoring-strategies.md

Step 5: Create Custom MCP Servers

Build MCP servers for your proprietary systems:

// custom-engineering-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const server = new Server({
  name: "your-company-engineering",
  version: "1.0.0"
});

// Tool to get current build status
server.tool("get_build_status", 
  "Retrieve current CI/CD build status", 
  {
    project: z.string(),
    branch: z.string().optional()
  },
  async (params) => {
    const status = await getBuildStatus(params.project, params.branch);
    return {
      content: [{ type: "text", text: JSON.stringify(status, null, 2) }]
    };
  }
);

// Resource for real-time engineering metrics
server.resource("engineering://metrics", 
  async () => {
    const metrics = await getEngineeringMetrics();
    return `# Engineering Metrics\n\n${metrics}`;
  }
);

Step 6: Implement AI-Driven Workflows

Create automated workflows that demonstrate AI's engineering value:

Automated Code Review

# Workflow: PR Review Automation
1. AI receives PR notification via MCP integration
2. Reads coding standards and patterns from markdown files
3. Analyzes code changes via GitHub MCP
4. Checks test coverage via CI/CD MCP
5. Generates review comments following team standards
6. Suggests improvements with code examples

Intelligent Test Generation

# Workflow: Test Suite Generation
1. AI analyzes new code changes via MCP
2. Reads testing strategy and patterns from markdown
3. Checks existing test coverage via CI/CD MCP
4. Generates comprehensive test suite
5. Ensures tests follow team patterns and standards
6. Submits tests as part of PR

Step 7: Measure AI Impact

Track how AI transformation affects your engineering velocity:

# AI Impact Metrics
## Before AI Implementation
- Time to implement feature: X hours
- Code review time: Y minutes
- Test coverage: Z%
- Documentation currency: W%

## After AI + Context Implementation  
- Time to implement feature: X/3 hours
- Code review time: Y/2 minutes
- Test coverage: 85%+
- Documentation currency: 95%+

The Future-Ready Engineering Team

By customizing this handbook for your engineering team, you're not just implementing AI tools—you're creating an AI-native engineering foundation. This approach:

• Scales with your team: Add new context files as you grow
• Evolves with AI: Works across different AI models and platforms
• Preserves institutional knowledge: Your engineering wisdom is captured and leveraged
• Enables consistent AI behavior: All AI interactions reflect your engineering reality

The engineering teams that invest in structured context today will have AI systems that truly understand and amplify their engineering practices tomorrow. Your customized handbook becomes the foundation for AI that doesn't just assist—it authentically represents and advances your engineering excellence.

📚 Project Structure

ai-eng-ops-handbook/
├── templates/           # Reusable markdown templates
│   ├── code-review/    # Code review checklists and standards
│   ├── testing/        # Test templates and strategies
│   ├── deployment/     # Deployment workflows and runbooks
│   └── documentation/ # Documentation templates
├── contexts/           # Engineering-specific context files
│   ├── engineering/   # Engineering practices and patterns
│   ├── infrastructure/ # Infrastructure and DevOps context
│   ├── security/       # Security standards and practices
│   └── standards/      # Coding standards and conventions
├── examples/           # Sample implementations
│   ├── automated-testing/
│   ├── ci-cd-pipeline/
│   ├── code-review-workflow/
│   └── incident-management/
├── briefs/             # Feature briefs and issue analysis
├── docs/               # Documentation and guides
└── README.md           # This file

🤝 Contributing

We welcome contributions from the engineering community! Whether you're fixing bugs, adding features, or sharing new engineering templates, your input helps make this project better for everyone.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Code of Conduct and check existing issues before contributing.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🌟 Why This Matters

In an era where AI is transforming how we build software, the ability to systematically guide AI behavior through structured context is becoming a competitive advantage. This project bridges the gap between raw AI capability and practical engineering application, giving you the tools to scale your engineering operations intelligently.

Built for the AI-native engineering teams of tomorrow.

*Have questions or want to share how you're using this project? Open an issue or start a discussion—we'd love to hear from you!*