codeops-mcp

MCP (Model Context Protocol) server providing AI coding agents with universal, language-agnostic development rules.

What It Does

codeops-mcp bundles 13 curated rule documents that teach AI agents how to code, test, plan, commit, gather requirements, reverse-engineer codebases, create technical documentation, upgrade outdated artifacts, disambiguate designs, run preflight reviews, track feature-set roadmaps, and behave — across any programming language and project type. It exposes these rules via 5 MCP tools.

Rule Documents

Rule	Description
code	30 coding standards: DRY, testing, documentation, architecture, type safety
testing	Test commands, workflows, coverage requirements, debugging strategies
git-commands	Git commit protocols (gitcm/gitcmp), message format, push workflow
make_plan	Complete protocol for creating and executing multi-document implementation plans
requirements	Requirements gathering & documentation protocol (make_requirements)
retro_requirements	Reverse-engineer an existing codebase into structured requirements
techdocs	Technical architecture documentation protocol (make_techdocs)
upgrade_plan	Upgrade outdated plans and requirements to current standards
grill_me	Deep disambiguation protocol — relentless interview before planning or requirements
preflight	Multi-dimensional quality audit for plans, requirements, and artifacts (preflight)
roadmap	Live roadmap tracking every RD/plan across a feature-set lifecycle (make_roadmap)
agents	Mandatory AI agent behavior: compliance, context management, multi-session execution
project-template	Template for .clinerules/project.md — project-specific toolchain configuration

MCP Tools

Tool	Description
get_rule	Get any rule document by name (supports aliases like "git", "test", "retro")
list_rules	List all available rules grouped by category
search_rules	Full-text search across all rules with TF-IDF ranking
analyze_project	Killer feature — Scan a project directory and auto-generate project.md
get_setup_guide	Step-by-step guide for setting up CodeOps in a project

Installation

# Global install
npm install -g codeops-mcp

# Or with yarn
yarn global add codeops-mcp

MCP Configuration

Add to your MCP client configuration (e.g., Cline, Claude Desktop):

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp"
        }
    }
}

Custom docs path

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp",
            "args": ["/path/to/custom/docs"]
        }
    }
}

Or via environment variable:

{
    "mcpServers": {
        "codeops": {
            "command": "codeops-mcp",
            "env": {
                "CODEOPS_DOCS_PATH": "/path/to/custom/docs"
            }
        }
    }
}

How It Works

The two-layer architecture:

1. Layer 1: Universal rules (bundled in this package) — Language-agnostic standards for coding, testing, git, planning, and requirements
2. Layer 2: Project-specific config (.clinerules/project.md in your project) — Toolchain, commands, conventions

All generic rules reference project.md for project-specific settings like build commands, test commands, package manager, etc.

Quick Setup

1. Run analyze_project("/path/to/your/project") to auto-detect your toolchain
2. Save the output to .clinerules/project.md in your project
3. The AI agent automatically applies universal rules using your project's settings

---

Usage Guide

Trigger Keywords

codeops-mcp defines trigger keywords — when you type these phrases, the AI agent executes sophisticated multi-step protocols:

Keyword	What It Does
make_plan	Creates a detailed multi-document implementation plan for a feature
exec_plan [name]	Executes an existing plan step by step
make_requirements	Discovers, structures, and documents project requirements
add_requirement	Adds a new requirement to an existing requirements set
review_requirements	Health-checks existing requirements for gaps and inconsistencies
retro_requirements	Reverse-engineers an existing codebase into structured requirements
make_techdocs	Creates VitePress-compatible technical architecture documentation
review_techdocs	Reviews and updates existing technical documentation
upgrade_plan [name]	Upgrades an outdated plan to current CodeOps standards
upgrade_requirements	Upgrades outdated requirements to current CodeOps standards
grill_me	Relentless interview to eliminate ambiguity before planning or requirements
preflight <artifact>	Multi-dimensional quality audit — iterates until artifact passes clean
gitcm	Stages all changes and commits with a detailed conventional commit message
gitcmp	Same as gitcm plus rebase and push

Workflow Overview

The protocols form a complete development pipeline:

┌──────────────────────────────────────────────────────────────────┐
│  REVERSE PATH (existing codebase → requirements → rebuild)       │
│                                                                  │
│  retro_requirements → make_requirements → make_plan → exec_plan  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  FORWARD PATH (new project → requirements → implementation)      │
│                                                                  │
│  make_requirements → make_plan → exec_plan                       │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  QUICK PATH (add a feature to existing codebase)                 │
│                                                                  │
│  make_plan → exec_plan                                           │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  UPGRADE PATH (bring outdated artifacts to current standards)     │
│                                                                  │
│  upgrade_plan [feature] / upgrade_requirements                    │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  DISAMBIGUATION PATH (eliminate ambiguity before any work)        │
│                                                                  │
│  grill_me → make_plan → exec_plan                                │
│  grill_me → make_requirements → make_plan → exec_plan            │
│  grill_me (standalone deep-dive)                                  │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  QUALITY GATE (review artifacts before execution)                 │
│                                                                  │
│  make_plan → preflight [feature] → exec_plan                     │
│  make_requirements → preflight requirements → make_plan           │
│  preflight (standalone audit of any artifact)                     │
└──────────────────────────────────────────────────────────────────┘

You can use any part of the pipeline independently — they're designed to work together but none requires the others.

---

Coding Standards & Testing

The agent automatically loads coding standards and testing rules at the start of every task. These enforce:

• 30 coding rules: DRY, single responsibility, documentation, type safety, 500-line file limit
• Testing workflow: Write tests first, run verification before every commit
• Test coverage: Unit, integration, and end-to-end tests required

You don't need to do anything — just have codeops-mcp installed and the agent follows these rules automatically.

---

Planning & Execution (make_plan / exec_plan)

Create and execute structured implementation plans for features of any size.

Creating a plan:

User: make_plan

Agent: What feature would you like to plan?

User: Add JWT authentication to our API

Agent: [Asks clarifying questions, analyzes codebase, then creates:]
  plans/jwt-auth/
  ├── 00-index.md
  ├── 01-requirements.md
  ├── 02-current-state.md
  ├── 03-auth-middleware.md
  ├── 04-token-service.md
  ├── 07-testing-strategy.md
  └── 99-execution-plan.md

Executing a plan:

User: exec_plan jwt-auth

Agent: [Reads the execution plan, implements tasks one by one,
        runs verification after each task, updates progress,
        asks about commits after each verified task]

Commit modes for exec_plan:

Flag	Behavior
(default)	Ask before each commit
--no-commit	Never commit — you handle git yourself
--auto-commit	Automatically commit and push after each task

---

Requirements Engineering (make_requirements)

Transform a rough project idea into formal requirement documents through guided discovery.

Example:

User: I want to build a university lab management SaaS. Researchers book lab rooms,
ethics committee approves studies, participants sign up on a public page.
Built with Node, TypeScript, PostgreSQL.

make_requirements

Agent: [Conducts multi-turn discovery interview]
  - Maps stakeholders and user types
  - Analyzes comparable systems (suggests features you haven't thought of)
  - Walks through user journeys to find hidden requirements
  - Explores "what happens when..." edge cases
  - Produces formal requirement documents:

  requirements/
  ├── README.md              # Index, glossary, dependency graph
  ├── RD-01-scaffolding.md   # Project setup
  ├── RD-02-data-model.md    # Database schema
  ├── RD-03-auth.md          # Authentication & RBAC
  ├── RD-04-lab-booking.md   # Core booking functionality
  ├── ...
  └── RD-12-deployment.md    # Production deployment

Each RD document can then be fed into make_plan for implementation:

User: make_plan
Agent: I found requirement documents. Which RD would you like to implement?
User: RD-04-lab-booking.md
Agent: [Creates implementation plan based on the requirement document]

Additional keywords:

• add_requirement — Add a new RD to an existing set
• review_requirements — Run a health check on all requirements (gaps, inconsistencies, scope creep)

---

Reverse Requirements Engineering (retro_requirements)

Analyze an existing codebase and produce a reconstruction brief — detailed enough to rebuild the entire application.

Example:

User: retro_requirements

Agent: [Systematically analyzes the codebase in 10 phases:]
  Phase 0: Reconnaissance — manifests, directory structure, tech stack
  Phase 1: Structural Analysis — layers, modules, entry points, patterns
  Phase 2: Data Model — entities, relationships, constraints
  Phase 3: API Surface — endpoints, CLI commands, public interfaces
  Phase 4: Behavior Catalog — features translated to requirement statements
  Phase 5: Business Rules — validation, authorization, domain logic
  Phase 6: Cross-Cutting — auth, errors, logging, caching
  Phase 7: Integrations — external APIs, databases, services
  Phase 8: Gaps & Debt — TODOs, missing tests, security gaps
  Phase 9: Synthesis — produces the reconstruction brief

Output:
  requirements/_retro/
  ├── 00-project-profile.md
  ├── 01-architecture-analysis.md
  ├── ...
  ├── 08-gaps-and-debt.md
  └── 09-reconstruction-brief.md   ← Feed this to make_requirements

Scope control for large codebases:

retro_requirements --scope src/auth          # Analyze only the auth module
retro_requirements --continue                # Resume an interrupted session

The reconstruction brief is designed as input for make_requirements, completing the full reverse → forward pipeline.

---

Version Stamping & Upgrade Protocol (upgrade_plan / upgrade_requirements)

Plans and requirements created with codeops-mcp are automatically stamped with the CodeOps version. When rules evolve, previously created plans may become outdated. The upgrade protocol brings them up to current standards.

How it works:

• Plans created with make_plan include a > **CodeOps Version**: X.Y.Z stamp
• When you run exec_plan, the agent detects outdated or pre-versioning plans and suggests upgrading
• The upgrade is non-destructive — all user-authored content (technical specs, scope decisions, task states) is preserved

Upgrading a plan:

User: upgrade_plan jwt-auth

Agent: [Reads all plan documents, compares against current templates]

  Upgrade Report: jwt-auth
  Current Version: 1.5.0 (or "none — pre-versioning")
  Target Version: 1.7.0

  Will Be Added: commit mode flags, security checklist, techdocs step
  Will Be Updated: session protocol, success criteria
  Will Be Preserved: all technical specs, task states, scope decisions

  Proceed with upgrade?

Upgrading requirements:

User: upgrade_requirements

Agent: [Reads all RD documents, compares against current templates,
        adds missing sections like security considerations]

---

Technical Architecture Documentation (make_techdocs)

Generate and maintain VitePress-compatible technical architecture documentation from your codebase.

User: make_techdocs

Agent: [Analyzes codebase architecture and produces:]
  docs/
  ├── index.md                  # Home page with techdocs: true frontmatter
  ├── architecture/
  │   ├── overview.md           # System overview and diagrams
  │   ├── data-model.md         # Entity relationships
  │   └── api-design.md         # API surface documentation
  └── decisions/
      └── ADR-001-*.md          # Architecture Decision Records

Documentation is automatically maintained during plan execution — the agent checks for architectural changes after each phase and updates docs accordingly.

---

Git Workflow (gitcm / gitcmp)

Safe, structured git commits with detailed conventional commit messages.

User: gitcm

Agent: [Stages all changes, writes a detailed commit message to a temp file,
        commits using git commit -F, cleans up]

Result:
  feat(auth): add JWT token refresh endpoint

  - Add POST /api/auth/refresh endpoint
  - Implement token rotation with refresh token family tracking
  - Add rate limiting (5 refreshes per minute per user)
  - Tests added for all edge cases

User: gitcmp

Agent: [Same as gitcm, plus rebase and push. Reports conflicts if any.]

Key safety rules:

• Commit messages are ALWAYS written to a file (never inline -m flag)
• Verification (build + test) runs before every commit
• Conflicts are reported to the user — never auto-resolved

---

Deep Disambiguation (grill_me)

Eliminate ambiguity before planning or requirements gathering through a structured, relentless interview.

Example — standalone:

User: grill_me

I want to add a caching layer to my API

Agent: [Identifies the design tree — major decision branches:]
  1. What are you caching? (responses, queries, computed values)
  2. Cache backend? (Redis, in-memory, CDN)
  3. Invalidation strategy? (TTL, event-driven, manual)
  4. Cache key design? (naming convention, namespacing)

Agent: [Walks each branch one decision at a time:]
  "For Branch 1, we need to decide: what exactly are you caching?"
  → User answers
  "You said database queries. That implies [consequence]. Is that OK?"
  → Drills deeper into sub-decisions
  → Surfaces assumptions: "I'm now assuming X, Y, Z. Correct?"
  → Moves to next branch only when current one is fully resolved

Output: A shared understanding summary with all decisions, assumptions,
        constraints, and deferrals — ready for make_plan or make_requirements

Example — as a prefix to planning:

User: grill_me

I want to add webhook support to our notification system.
Once we're aligned, let's make_plan.

Agent: [Runs full grill-me protocol on webhooks — retry strategy,
        payload format, authentication, rate limiting, failure handling,
        deduplication — resolving every ambiguity]

Agent: [Transitions to make_plan with Phase 1.1 already complete]

Aliases: grill-me, grill, disambiguate, deep-dive, interview

---

Preflight Review (preflight)

Run a rigorous multi-dimensional quality audit on any plan, requirement set, or artifact — grounded in the actual codebase.

Example:

User: preflight jwt-auth

Agent: [Reads all plan documents in plans/jwt-auth/, then systematically audits:]

  Dimension 1: Codebase Grounding
    — Verifies every file reference, import, and component actually exists
    — Checks that assumed patterns match what the code actually uses

  Dimension 2: Completeness & Coverage
    — Finds missing error handling, edge cases, rollback steps

  Dimension 3: Internal Consistency
    — Cross-checks claims between documents for contradictions

  Dimension 4: Feasibility & Risk
    — Identifies technical risks, dependency conflicts, performance concerns

  Dimension 5: Clarity & Actionability
    — Flags vague language, ambiguous terms, missing acceptance criteria

Output: Findings report with severity ratings, options analysis for each
        finding, and recommendations. Iterates until clean pass.

Scope variants:

preflight requirements              # Audit all requirement documents
preflight requirements RD-03        # Audit a specific requirement document
preflight jwt-auth 03-api-design    # Audit a specific plan document
preflight src/auth/                 # Audit any file or directory
preflight --continue                # Resume an interrupted session

Aliases: pre-flight, pre_flight, flight-check, quality-audit, review-gate, audit

---

Project Configuration (analyze_project)

Auto-detect your project's toolchain and generate a configuration file:

User: analyze_project /path/to/my/project

Agent: [Reads package.json/Cargo.toml/go.mod/pyproject.toml, scans directory
        structure, detects language, framework, test runner, build tools]

Output: A complete .clinerules/project.md with:
  - Build, test, and verify commands
  - Directory layout
  - Coding conventions
  - Git conventions
  - Cross-references to all rule documents

Incremental updates: If .clinerules/project.md already exists, analyze_project merges the fresh scan with your existing file — auto-detectable sections are refreshed while user-customized sections (coding conventions, special rules) are preserved verbatim.

---

Development

# Install dependencies
yarn install

# Build
yarn build

# Run tests (107 tests across 4 test files)
yarn test

# Watch mode
yarn test:watch

Architecture

src/
├── index.ts              # MCP server entry point
├── config.ts             # Configuration resolution
├── types/
│   └── index.ts          # Type definitions & constants
├── store/
│   ├── rule-store.ts     # In-memory document store
│   └── search-engine.ts  # TF-IDF search engine
├── tools/
│   ├── get-rule.ts       # Get rule by name
│   ├── list-rules.ts     # List all rules
│   ├── search-rules.ts   # Full-text search
│   ├── analyze-project.ts # Project analysis & project.md generation
│   └── get-setup-guide.ts # Setup instructions
└── __tests__/
    ├── store/            # Store & search engine tests
    └── tools/            # Tool integration tests
docs/                     # 13 bundled rule markdown files

License

MIT