{"id":47684179,"url":"https://github.com/blendsdk/codeops-mcp","last_synced_at":"2026-04-24T02:04:37.833Z","repository":{"id":338642609,"uuid":"1158527229","full_name":"blendsdk/codeops-mcp","owner":"blendsdk","description":"MCP (Model Context Protocol) server providing AI coding agents with universal, language-agnostic development rules.","archived":false,"fork":false,"pushed_at":"2026-03-27T00:41:29.000Z","size":218,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-29T16:08:24.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blendsdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/agents.md","dco":null,"cla":null}},"created_at":"2026-02-15T14:23:17.000Z","updated_at":"2026-03-27T00:41:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blendsdk/codeops-mcp","commit_stats":null,"previous_names":["blendsdk/codeops-mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/blendsdk/codeops-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fcodeops-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fcodeops-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fcodeops-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fcodeops-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blendsdk","download_url":"https://codeload.github.com/blendsdk/codeops-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blendsdk%2Fcodeops-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-02T14:28:54.430Z","updated_at":"2026-04-24T02:04:37.827Z","avatar_url":"https://github.com/blendsdk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codeops-mcp\n\nMCP (Model Context Protocol) server providing AI coding agents with universal, language-agnostic development rules.\n\n## What It Does\n\n**codeops-mcp** bundles 10 curated rule documents that teach AI agents how to code, test, plan, commit, gather requirements, reverse-engineer codebases, create technical documentation, upgrade outdated artifacts, and behave — across any programming language and project type. It exposes these rules via 5 MCP tools.\n\n### Rule Documents\n\n| Rule                     | Description                                                                          |\n| ------------------------ | ------------------------------------------------------------------------------------ |\n| **code**                 | 30 coding standards: DRY, testing, documentation, architecture, type safety          |\n| **testing**              | Test commands, workflows, coverage requirements, debugging strategies                |\n| **git-commands**         | Git commit protocols (`gitcm`/`gitcmp`), message format, push workflow               |\n| **make_plan**            | Complete protocol for creating and executing multi-document implementation plans      |\n| **requirements**         | Requirements gathering \u0026 documentation protocol (`make_requirements`)                |\n| **retro_requirements**   | Reverse-engineer an existing codebase into structured requirements                   |\n| **techdocs**             | Technical architecture documentation protocol (`make_techdocs`)                      |\n| **upgrade_plan**         | Upgrade outdated plans and requirements to current standards                          |\n| **agents**               | Mandatory AI agent behavior: compliance, context management, multi-session execution |\n| **project-template**     | Template for `.clinerules/project.md` — project-specific toolchain configuration     |\n\n### MCP Tools\n\n| Tool              | Description                                                                  |\n| ----------------- | ---------------------------------------------------------------------------- |\n| `get_rule`        | Get any rule document by name (supports aliases like \"git\", \"test\", \"retro\") |\n| `list_rules`      | List all available rules grouped by category                                 |\n| `search_rules`    | Full-text search across all rules with TF-IDF ranking                        |\n| `analyze_project` | **Killer feature** — Scan a project directory and auto-generate `project.md` |\n| `get_setup_guide` | Step-by-step guide for setting up CodeOps in a project                       |\n\n## Installation\n\n```bash\n# Global install\nnpm install -g codeops-mcp\n\n# Or with yarn\nyarn global add codeops-mcp\n```\n\n## MCP Configuration\n\nAdd to your MCP client configuration (e.g., Cline, Claude Desktop):\n\n```json\n{\n    \"mcpServers\": {\n        \"codeops\": {\n            \"command\": \"codeops-mcp\"\n        }\n    }\n}\n```\n\n### Custom docs path\n\n```json\n{\n    \"mcpServers\": {\n        \"codeops\": {\n            \"command\": \"codeops-mcp\",\n            \"args\": [\"/path/to/custom/docs\"]\n        }\n    }\n}\n```\n\nOr via environment variable:\n\n```json\n{\n    \"mcpServers\": {\n        \"codeops\": {\n            \"command\": \"codeops-mcp\",\n            \"env\": {\n                \"CODEOPS_DOCS_PATH\": \"/path/to/custom/docs\"\n            }\n        }\n    }\n}\n```\n\n## How It Works\n\nThe two-layer architecture:\n\n1. **Layer 1: Universal rules** (bundled in this package) — Language-agnostic standards for coding, testing, git, planning, and requirements\n2. **Layer 2: Project-specific config** (`.clinerules/project.md` in your project) — Toolchain, commands, conventions\n\nAll generic rules reference `project.md` for project-specific settings like build commands, test commands, package manager, etc.\n\n### Quick Setup\n\n1. Run `analyze_project(\"/path/to/your/project\")` to auto-detect your toolchain\n2. Save the output to `.clinerules/project.md` in your project\n3. The AI agent automatically applies universal rules using your project's settings\n\n---\n\n## Usage Guide\n\n### Trigger Keywords\n\ncodeops-mcp defines **trigger keywords** — when you type these phrases, the AI agent executes sophisticated multi-step protocols:\n\n| Keyword | What It Does |\n|---------|-------------|\n| `make_plan` | Creates a detailed multi-document implementation plan for a feature |\n| `exec_plan [name]` | Executes an existing plan step by step |\n| `make_requirements` | Discovers, structures, and documents project requirements |\n| `add_requirement` | Adds a new requirement to an existing requirements set |\n| `review_requirements` | Health-checks existing requirements for gaps and inconsistencies |\n| `retro_requirements` | Reverse-engineers an existing codebase into structured requirements |\n| `make_techdocs` | Creates VitePress-compatible technical architecture documentation |\n| `review_techdocs` | Reviews and updates existing technical documentation |\n| `upgrade_plan [name]` | Upgrades an outdated plan to current CodeOps standards |\n| `upgrade_requirements` | Upgrades outdated requirements to current CodeOps standards |\n| `gitcm` | Stages all changes and commits with a detailed conventional commit message |\n| `gitcmp` | Same as `gitcm` plus rebase and push |\n\n### Workflow Overview\n\nThe protocols form a complete development pipeline:\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│  REVERSE PATH (existing codebase → requirements → rebuild)       │\n│                                                                  │\n│  retro_requirements → make_requirements → make_plan → exec_plan  │\n└──────────────────────────────────────────────────────────────────┘\n\n┌──────────────────────────────────────────────────────────────────┐\n│  FORWARD PATH (new project → requirements → implementation)      │\n│                                                                  │\n│  make_requirements → make_plan → exec_plan                       │\n└──────────────────────────────────────────────────────────────────┘\n\n┌──────────────────────────────────────────────────────────────────┐\n│  QUICK PATH (add a feature to existing codebase)                 │\n│                                                                  │\n│  make_plan → exec_plan                                           │\n└──────────────────────────────────────────────────────────────────┘\n\n┌──────────────────────────────────────────────────────────────────┐\n│  UPGRADE PATH (bring outdated artifacts to current standards)     │\n│                                                                  │\n│  upgrade_plan [feature] / upgrade_requirements                    │\n└──────────────────────────────────────────────────────────────────┘\n```\n\nYou can use any part of the pipeline independently — they're designed to work together but none requires the others.\n\n---\n\n### Coding Standards \u0026 Testing\n\nThe agent automatically loads coding standards and testing rules at the start of every task. These enforce:\n\n- **30 coding rules**: DRY, single responsibility, documentation, type safety, 500-line file limit\n- **Testing workflow**: Write tests first, run verification before every commit\n- **Test coverage**: Unit, integration, and end-to-end tests required\n\nYou don't need to do anything — just have codeops-mcp installed and the agent follows these rules automatically.\n\n---\n\n### Planning \u0026 Execution (`make_plan` / `exec_plan`)\n\nCreate and execute structured implementation plans for features of any size.\n\n**Creating a plan:**\n\n```\nUser: make_plan\n\nAgent: What feature would you like to plan?\n\nUser: Add JWT authentication to our API\n\nAgent: [Asks clarifying questions, analyzes codebase, then creates:]\n  plans/jwt-auth/\n  ├── 00-index.md\n  ├── 01-requirements.md\n  ├── 02-current-state.md\n  ├── 03-auth-middleware.md\n  ├── 04-token-service.md\n  ├── 07-testing-strategy.md\n  └── 99-execution-plan.md\n```\n\n**Executing a plan:**\n\n```\nUser: exec_plan jwt-auth\n\nAgent: [Reads the execution plan, implements tasks one by one,\n        runs verification after each task, updates progress,\n        asks about commits after each verified task]\n```\n\n**Commit modes for `exec_plan`:**\n\n| Flag | Behavior |\n|------|----------|\n| *(default)* | Ask before each commit |\n| `--no-commit` | Never commit — you handle git yourself |\n| `--auto-commit` | Automatically commit and push after each task |\n\n---\n\n### Requirements Engineering (`make_requirements`)\n\nTransform a rough project idea into formal requirement documents through guided discovery.\n\n**Example:**\n\n```\nUser: I want to build a university lab management SaaS. Researchers book lab rooms,\nethics committee approves studies, participants sign up on a public page.\nBuilt with Node, TypeScript, PostgreSQL.\n\nmake_requirements\n\nAgent: [Conducts multi-turn discovery interview]\n  - Maps stakeholders and user types\n  - Analyzes comparable systems (suggests features you haven't thought of)\n  - Walks through user journeys to find hidden requirements\n  - Explores \"what happens when...\" edge cases\n  - Produces formal requirement documents:\n\n  requirements/\n  ├── README.md              # Index, glossary, dependency graph\n  ├── RD-01-scaffolding.md   # Project setup\n  ├── RD-02-data-model.md    # Database schema\n  ├── RD-03-auth.md          # Authentication \u0026 RBAC\n  ├── RD-04-lab-booking.md   # Core booking functionality\n  ├── ...\n  └── RD-12-deployment.md    # Production deployment\n```\n\nEach RD document can then be fed into `make_plan` for implementation:\n\n```\nUser: make_plan\nAgent: I found requirement documents. Which RD would you like to implement?\nUser: RD-04-lab-booking.md\nAgent: [Creates implementation plan based on the requirement document]\n```\n\n**Additional keywords:**\n- `add_requirement` — Add a new RD to an existing set\n- `review_requirements` — Run a health check on all requirements (gaps, inconsistencies, scope creep)\n\n---\n\n### Reverse Requirements Engineering (`retro_requirements`)\n\nAnalyze an existing codebase and produce a reconstruction brief — detailed enough to rebuild the entire application.\n\n**Example:**\n\n```\nUser: retro_requirements\n\nAgent: [Systematically analyzes the codebase in 10 phases:]\n  Phase 0: Reconnaissance — manifests, directory structure, tech stack\n  Phase 1: Structural Analysis — layers, modules, entry points, patterns\n  Phase 2: Data Model — entities, relationships, constraints\n  Phase 3: API Surface — endpoints, CLI commands, public interfaces\n  Phase 4: Behavior Catalog — features translated to requirement statements\n  Phase 5: Business Rules — validation, authorization, domain logic\n  Phase 6: Cross-Cutting — auth, errors, logging, caching\n  Phase 7: Integrations — external APIs, databases, services\n  Phase 8: Gaps \u0026 Debt — TODOs, missing tests, security gaps\n  Phase 9: Synthesis — produces the reconstruction brief\n\nOutput:\n  requirements/_retro/\n  ├── 00-project-profile.md\n  ├── 01-architecture-analysis.md\n  ├── ...\n  ├── 08-gaps-and-debt.md\n  └── 09-reconstruction-brief.md   ← Feed this to make_requirements\n```\n\n**Scope control for large codebases:**\n\n```\nretro_requirements --scope src/auth          # Analyze only the auth module\nretro_requirements --continue                # Resume an interrupted session\n```\n\nThe reconstruction brief is designed as input for `make_requirements`, completing the full reverse → forward pipeline.\n\n---\n\n### Version Stamping \u0026 Upgrade Protocol (`upgrade_plan` / `upgrade_requirements`)\n\nPlans 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.\n\n**How it works:**\n\n- Plans created with `make_plan` include a `\u003e **CodeOps Version**: X.Y.Z` stamp\n- When you run `exec_plan`, the agent detects outdated or pre-versioning plans and suggests upgrading\n- The upgrade is non-destructive — all user-authored content (technical specs, scope decisions, task states) is preserved\n\n**Upgrading a plan:**\n\n```\nUser: upgrade_plan jwt-auth\n\nAgent: [Reads all plan documents, compares against current templates]\n\n  Upgrade Report: jwt-auth\n  Current Version: 1.5.0 (or \"none — pre-versioning\")\n  Target Version: 1.7.0\n\n  Will Be Added: commit mode flags, security checklist, techdocs step\n  Will Be Updated: session protocol, success criteria\n  Will Be Preserved: all technical specs, task states, scope decisions\n\n  Proceed with upgrade?\n```\n\n**Upgrading requirements:**\n\n```\nUser: upgrade_requirements\n\nAgent: [Reads all RD documents, compares against current templates,\n        adds missing sections like security considerations]\n```\n\n---\n\n### Technical Architecture Documentation (`make_techdocs`)\n\nGenerate and maintain VitePress-compatible technical architecture documentation from your codebase.\n\n```\nUser: make_techdocs\n\nAgent: [Analyzes codebase architecture and produces:]\n  docs/\n  ├── index.md                  # Home page with techdocs: true frontmatter\n  ├── architecture/\n  │   ├── overview.md           # System overview and diagrams\n  │   ├── data-model.md         # Entity relationships\n  │   └── api-design.md         # API surface documentation\n  └── decisions/\n      └── ADR-001-*.md          # Architecture Decision Records\n```\n\nDocumentation is automatically maintained during plan execution — the agent checks for architectural changes after each phase and updates docs accordingly.\n\n---\n\n### Git Workflow (`gitcm` / `gitcmp`)\n\nSafe, structured git commits with detailed conventional commit messages.\n\n```\nUser: gitcm\n\nAgent: [Stages all changes, writes a detailed commit message to a temp file,\n        commits using git commit -F, cleans up]\n\nResult:\n  feat(auth): add JWT token refresh endpoint\n\n  - Add POST /api/auth/refresh endpoint\n  - Implement token rotation with refresh token family tracking\n  - Add rate limiting (5 refreshes per minute per user)\n  - Tests added for all edge cases\n```\n\n```\nUser: gitcmp\n\nAgent: [Same as gitcm, plus rebase and push. Reports conflicts if any.]\n```\n\n**Key safety rules:**\n- Commit messages are ALWAYS written to a file (never inline `-m` flag)\n- Verification (build + test) runs before every commit\n- Conflicts are reported to the user — never auto-resolved\n\n---\n\n### Project Configuration (`analyze_project`)\n\nAuto-detect your project's toolchain and generate a configuration file:\n\n```\nUser: analyze_project /path/to/my/project\n\nAgent: [Reads package.json/Cargo.toml/go.mod/pyproject.toml, scans directory\n        structure, detects language, framework, test runner, build tools]\n\nOutput: A complete .clinerules/project.md with:\n  - Build, test, and verify commands\n  - Directory layout\n  - Coding conventions\n  - Git conventions\n  - Cross-references to all rule documents\n```\n\n**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.\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nyarn install\n\n# Build\nyarn build\n\n# Run tests (107 tests across 4 test files)\nyarn test\n\n# Watch mode\nyarn test:watch\n```\n\n## Architecture\n\n```\nsrc/\n├── index.ts              # MCP server entry point\n├── config.ts             # Configuration resolution\n├── types/\n│   └── index.ts          # Type definitions \u0026 constants\n├── store/\n│   ├── rule-store.ts     # In-memory document store\n│   └── search-engine.ts  # TF-IDF search engine\n├── tools/\n│   ├── get-rule.ts       # Get rule by name\n│   ├── list-rules.ts     # List all rules\n│   ├── search-rules.ts   # Full-text search\n│   ├── analyze-project.ts # Project analysis \u0026 project.md generation\n│   └── get-setup-guide.ts # Setup instructions\n└── __tests__/\n    ├── store/            # Store \u0026 search engine tests\n    └── tools/            # Tool integration tests\ndocs/                     # 10 bundled rule markdown files\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fcodeops-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblendsdk%2Fcodeops-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblendsdk%2Fcodeops-mcp/lists"}