Codeops MCP

代码操作mcp

MCP（模型上下文协议）服务器为AI编码代理提供通用的、与语言无关的开发规则。

它的作用

代码操作mcp 捆绑了12个精心策划的规则文档，教人工智能代理如何编码、测试、计划、提交、收集需求、逆向工程代码库、创建技术文档、升级过时的工件、消除设计歧义、运行飞行前审查以及跨任何编程语言和项目类型的行为。它通过5个MCP工具公开这些规则。

规则文档

MCP工具

安装

# Global install
npm install -g codeops-mcp

# Or with yarn
yarn global add codeops-mcp

MCP配置

添加到您的MCP客户端配置中（例如Cline、Claude Desktop）：

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

自定义文档路径

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

或者通过环境变量：

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

运作原理

双层架构：

1. 第1层：通用规则 （捆绑在这个包中）——编码、测试、git、规划和需求的语言无关标准
2. 第二层：项目特定配置 (.clinerules/project.md 在您的项目中）——工具链、命令、约定

所有通用规则参考 project.md 用于项目特定的设置，如构建命令、测试命令、包管理器等。

快速设置

1. 跑 analyze_project("/path/to/your/project") 自动检测您的工具链
2. 将输出保存到 .clinerules/project.md 在您的项目中
3. AI代理使用项目的设置自动应用通用规则

______________________________________________________________________

使用指南

触发器关键字

codeops mcp定义 触发器关键字 --当你键入这些短语时，AI代理会执行复杂的多步骤协议：

工作流概述

这些协议形成了一个完整的开发管道：

┌──────────────────────────────────────────────────────────────────┐
│  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)                     │
└──────────────────────────────────────────────────────────────────┘

您可以独立使用管道的任何部分——它们被设计为协同工作，但不需要其他部分。

______________________________________________________________________

编码标准和测试

代理在每个任务开始时自动加载编码标准和测试规则。这些强制执行：

• 30条编码规则：干燥、单一责任、文件、类型安全、500行文件限制
• 测试工作流程：首先编写测试，在每次提交之前运行验证
• 测试覆盖率：需要单元、集成和端到端测试

您不需要做任何事情——只需安装codeops mcp，代理就会自动遵循这些规则。

______________________________________________________________________

规划与执行(make_plan / exec_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

执行计划：

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]

提交模式 exec_plan:

______________________________________________________________________

需求工程(make_requirements)

通过引导发现将粗略的项目想法转化为正式的需求文档。

例子：

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

然后，每个RD文档都可以输入 make_plan 实施：

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]

其他关键字：

• add_requirement --将新RD添加到现有集合中
• review_requirements --对所有需求（差距、不一致、范围蔓延）进行健康检查

______________________________________________________________________

逆向需求工程(retro_requirements)

分析现有的代码库，并制作一份重建简报——足够详细，可以重建整个应用程序。

例子：

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

大型代码库的作用域控制：

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

重建简报旨在作为以下内容的输入 make_requirements，完成完全相反的操作→ 正向管道。

______________________________________________________________________

版本标记和升级协议(upgrade_plan / upgrade_requirements)

使用codeops mcp创建的计划和需求会自动标记codeops版本。当规则演变时，之前创建的计划可能会过时。升级协议使它们达到了当前的标准。

它是如何工作的：

• 使用创建的计划 make_plan 包括a > **CodeOps Version**: X.Y.Z 邮票
• 当你奔跑时 exec_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?

升级要求：

User: upgrade_requirements

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

______________________________________________________________________

技术架构文档(make_techdocs)

从您的代码库生成和维护与VitePress兼容的技术架构文档。

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

文档在计划执行过程中会自动维护——代理在每个阶段后检查架构更改，并相应地更新文档。

______________________________________________________________________

Git工作流(gitcm / gitcmp)

安全、结构化的git提交，带有详细的常规提交消息。

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.]

关键安全规则：

• 提交消息始终写入文件（从不内联 -m 旗帜）
• 每次提交前都会运行验证（构建+测试）
• 冲突会报告给用户——从不自动解决

______________________________________________________________________

深度消除分歧(grill_me)

通过结构化、无情的面试，在计划或收集需求之前消除歧义。

示例——独立：

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

示例——作为规划的前缀：

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]

别名： grill-me, grill, disambiguate, deep-dive, interview

______________________________________________________________________

飞行前回顾(preflight)

对任何计划、需求集或工件进行严格的多维质量审计，以实际代码库为基础。

例子：

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.

范围变体：

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

别名： pre-flight, pre_flight, flight-check, quality-audit, review-gate, audit

______________________________________________________________________

项目配置(analyze_project)

自动检测项目的工具链并生成配置文件：

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

增量更新： 如果 .clinerules/project.md 已经存在， analyze_project 将新扫描与现有文件合并——自动检测部分被刷新，而用户自定义部分（编码约定、特殊规则）被逐字保留。

______________________________________________________________________

发展

# Install dependencies
yarn install

# Build
yarn build

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

# Watch mode
yarn test:watch

建筑

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/                     # 12 bundled rule markdown files

许可证

麻省理工学院