|
| 1 | +# Generated Project Configuration |
| 2 | + |
| 3 | +> **Auto-generated by `analyze_project`** (deep analysis) |
| 4 | +> **Project:** codeops-mcp |
| 5 | +> **Type:** library |
| 6 | +
|
| 7 | +--- |
| 8 | + |
| 9 | +## 🚨 MANDATORY: Load CodeOps Rules Before Any Work |
| 10 | + |
| 11 | +**Before ANY planning or implementation, the AI agent MUST load these rules |
| 12 | +using the codeops-mcp tools:** |
| 13 | + |
| 14 | +1. `get_rule("agents")` — Load agent behavior rules **(REQUIRED FIRST)** |
| 15 | +2. `get_rule("code")` — Load coding standards |
| 16 | +3. `get_rule("testing")` — Load testing workflows |
| 17 | +4. `get_rule("git-commands")` — Load git commit protocols |
| 18 | + |
| 19 | +These rules are **mandatory** and must be consulted before every task. |
| 20 | +**Do NOT skip this step. Do NOT proceed without reading these documents.** |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## Project Overview |
| 25 | + |
| 26 | +- **Name:** codeops-mcp |
| 27 | +- **Description:** MCP (Model Context Protocol) server providing AI coding agents with universal, language-agnostic development rules. Includes coding standards, testing workflows, git conventions, plan creation/execution protocols, and intelligent project analysis for auto-generating project configurations. |
| 28 | +- **Type:** library (MCP server, published to npm) |
| 29 | +- **Author:** blendsdk |
| 30 | +- **License:** MIT |
| 31 | +- **Node Engine:** >=18.0.0 |
| 32 | +- **Module System:** ESM (`"type": "module"`) |
| 33 | + |
| 34 | +## Toolchain |
| 35 | + |
| 36 | +- **Language(s):** TypeScript (ES2022 target, Node16 module resolution) |
| 37 | +- **Framework(s):** MCP SDK (`@modelcontextprotocol/sdk`) |
| 38 | +- **Package Manager:** yarn (v1, lockfile: `yarn.lock`) |
| 39 | +- **Test Framework:** Vitest (v2.x, `vitest run`) |
| 40 | +- **Build:** `tsc` (TypeScript compiler, outputs to `dist/`) |
| 41 | +- **Release:** semantic-release (with changelog, git, github, npm plugins) |
| 42 | +- **TypeScript Config:** Strict mode enabled (`strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns`, `noFallthroughCasesInSwitch`) |
| 43 | + |
| 44 | +**Manifest files found:** package.json, tsconfig.json, vitest.config.ts, .releaserc.json, yarn.lock |
| 45 | + |
| 46 | +## Commands |
| 47 | + |
| 48 | +All commands assume execution from the project root. Prefix all shell commands with `clear &&`. |
| 49 | + |
| 50 | +### Build |
| 51 | + |
| 52 | +```bash |
| 53 | +clear && yarn build |
| 54 | +``` |
| 55 | + |
| 56 | +### Test |
| 57 | + |
| 58 | +```bash |
| 59 | +# Run all tests (106 tests across 4 test files) |
| 60 | +clear && yarn test |
| 61 | + |
| 62 | +# Run tests in watch mode |
| 63 | +clear && yarn test:watch |
| 64 | + |
| 65 | +# Run tests with coverage |
| 66 | +clear && yarn test:coverage |
| 67 | +``` |
| 68 | + |
| 69 | +### Verify (before commit) |
| 70 | + |
| 71 | +```bash |
| 72 | +# Full verification — run this before any git commit |
| 73 | +clear && yarn build && yarn test |
| 74 | +``` |
| 75 | + |
| 76 | +### Other Commands |
| 77 | + |
| 78 | +```bash |
| 79 | +# Watch mode (recompile on change) |
| 80 | +clear && yarn watch |
| 81 | + |
| 82 | +# Start the server |
| 83 | +clear && yarn start |
| 84 | + |
| 85 | +# Clean dist/ |
| 86 | +clear && yarn clean |
| 87 | + |
| 88 | +# Update all dependencies |
| 89 | +clear && yarn ncu |
| 90 | +``` |
| 91 | + |
| 92 | +## Project Structure |
| 93 | + |
| 94 | +### Type: Single repository |
| 95 | + |
| 96 | +### Directory Layout |
| 97 | + |
| 98 | +``` |
| 99 | +docs/ # Rule markdown documents (6 files, shipped with npm package) |
| 100 | + agents.md # AI agent behavior rules |
| 101 | + code.md # Coding standards (DRY, architecture, type safety) |
| 102 | + git-commands.md # Git commit protocols (gitcm/gitcmp) |
| 103 | + make_plan.md # Plan creation, execution protocol & implementation plan formatting |
| 104 | + project-template.md # Project configuration template |
| 105 | + testing.md # Testing standards & workflows |
| 106 | +src/ # TypeScript source code |
| 107 | + index.ts # Main entry point — MCP server bootstrap |
| 108 | + config.ts # Configuration resolution (CLI/env/defaults) |
| 109 | + types/ # Type definitions |
| 110 | + index.ts # All interfaces, types, constants, and metadata |
| 111 | + store/ # Data layer |
| 112 | + rule-store.ts # In-memory document store with O(1) lookup + fuzzy matching |
| 113 | + search-engine.ts # TF-IDF search engine with field weighting |
| 114 | + tools/ # MCP tool implementations (5 tools) |
| 115 | + get-rule.ts # get_rule — Retrieve a rule document by name/alias |
| 116 | + list-rules.ts # list_rules — List all rules grouped by category |
| 117 | + search-rules.ts # search_rules — Full-text search across rules |
| 118 | + analyze-project.ts # analyze_project — Scan project + generate/merge project.md |
| 119 | + get-setup-guide.ts # get_setup_guide — Setup instructions for new projects |
| 120 | + __tests__/ # Test files (Vitest) |
| 121 | + store/ # Store layer tests |
| 122 | + rule-store.test.ts |
| 123 | + search-engine.test.ts |
| 124 | + tools/ # Tool layer tests |
| 125 | + tools-setup.ts # Shared test fixture (lazy-loaded store + engine) |
| 126 | + core-tools.test.ts # Tests for get_rule, list_rules, search_rules, get_setup_guide |
| 127 | + analyze-project-merge.test.ts # Tests for analyze_project + merge engine |
| 128 | +dist/ # Compiled output (git-ignored) |
| 129 | +``` |
| 130 | + |
| 131 | +### Architecture Layers |
| 132 | + |
| 133 | +``` |
| 134 | +┌─────────────────────────────────────────┐ |
| 135 | +│ MCP Protocol (stdio transport) │ |
| 136 | +│ index.ts — Server + tool dispatcher │ |
| 137 | +├─────────────────────────────────────────┤ |
| 138 | +│ Tools Layer (5 pure functions) │ |
| 139 | +│ get-rule, list-rules, search-rules, │ |
| 140 | +│ analyze-project, get-setup-guide │ |
| 141 | +├─────────────────────────────────────────┤ |
| 142 | +│ Store Layer │ |
| 143 | +│ RuleStore (in-memory Map<id, doc>) │ |
| 144 | +│ SearchEngine (TF-IDF inverted index) │ |
| 145 | +├─────────────────────────────────────────┤ |
| 146 | +│ Types Layer │ |
| 147 | +│ Interfaces, constants, metadata │ |
| 148 | +├─────────────────────────────────────────┤ |
| 149 | +│ Config Layer │ |
| 150 | +│ CLI args → env vars → bundled defaults │ |
| 151 | +└─────────────────────────────────────────┘ |
| 152 | +``` |
| 153 | + |
| 154 | +## Coding Conventions |
| 155 | + |
| 156 | +### Naming |
| 157 | + |
| 158 | +- **Files:** kebab-case (e.g., `rule-store.ts`, `get-rule.ts`, `analyze-project.ts`) |
| 159 | +- **Exception:** `make_plan` uses underscore in ID (matches the doc filename `make_plan.md`) |
| 160 | +- **Classes:** PascalCase (e.g., `RuleStore`, `SearchEngine`, `StdioServerTransport`) |
| 161 | +- **Functions/Methods:** camelCase (e.g., `getRule`, `findByName`, `resolveConfig`, `analyzeProject`) |
| 162 | +- **Interfaces/Types:** PascalCase (e.g., `RuleDocument`, `SearchResult`, `ProjectAnalysis`, `ServerConfig`) |
| 163 | +- **Constants:** UPPER_SNAKE_CASE (e.g., `STOP_WORDS`, `FIELD_WEIGHTS`, `AUTO_UPDATE_SECTIONS`, `RULE_METADATA`) |
| 164 | +- **Inline constants (objects):** UPPER_SNAKE_CASE (e.g., `TOOL_DEFINITIONS`, `CATEGORY_INFO`) |
| 165 | +- **Module-scoped privates:** camelCase (e.g., `cachedStore`, `cachedEngine`) |
| 166 | +- **Test fixtures:** UPPER_SNAKE_CASE prefixed with `FIXTURE_` or `SAMPLE_` (e.g., `FIXTURE_FULL_PROJECT_MD`, `SAMPLE_ANALYSIS`) |
| 167 | + |
| 168 | +### Code Style |
| 169 | + |
| 170 | +- **Module format:** ESM with `.js` import extensions (required by Node16 resolution) |
| 171 | +- **Imports:** Type-only imports use `import type { ... }` syntax |
| 172 | +- **JSDoc:** Every exported function, class, and interface has JSDoc comments with `@param`, `@returns`, `@module` tags |
| 173 | +- **Section separators:** `// ============` comment blocks separate logical sections within files |
| 174 | +- **Error handling:** Errors caught and returned as formatted markdown strings (`**Error:** message`), never thrown to caller |
| 175 | +- **Console output:** All log output goes to `stderr` (stdout reserved for MCP protocol) |
| 176 | +- **Access modifiers:** Class members use `protected` for internal/overridable, `public` for API surface |
| 177 | +- **Const assertions:** `as const` used for object literals that define fixed shapes (e.g., `FIELD_WEIGHTS`, `type: 'object' as const`) |
| 178 | + |
| 179 | +### Patterns |
| 180 | + |
| 181 | +- **Pure function tools:** Each tool is a standalone exported function taking (store/engine, args) → string |
| 182 | +- **Formatter pattern:** Private `format*()` functions handle all markdown output generation |
| 183 | +- **Lazy caching:** Test setup uses lazy singleton pattern (`cachedStore ?? build()`) |
| 184 | +- **Mutation-in-place:** Project analysis functions mutate the `analysis` object directly (passed by reference) |
| 185 | +- **Strategy pattern:** Merge engine uses `SectionMergeStrategy` classification (`auto-update`, `preserve`, `static`) |
| 186 | +- **Fuzzy matching chain:** RuleStore.findByName tries 5 strategies in priority order (exact → alias → case-insensitive → partial → title) |
| 187 | + |
| 188 | +## Git & Commit Conventions |
| 189 | + |
| 190 | +### Commit Scope |
| 191 | + |
| 192 | +``` |
| 193 | +# Use module/feature as scope: |
| 194 | +# feat(tools): add new MCP tool |
| 195 | +# fix(store): correct fuzzy matching |
| 196 | +# test(merge): add merge engine tests |
| 197 | +# refactor(types): reorganize interfaces |
| 198 | +# docs(rules): update coding standards |
| 199 | +
|
| 200 | +# Common scopes: tools, store, types, config, docs, merge, search, rules |
| 201 | +``` |
| 202 | + |
| 203 | +### Branch Strategy |
| 204 | + |
| 205 | +- **Main branch:** `master` (used by semantic-release, see `.releaserc.json`) |
| 206 | +- **Feature branches:** `feature/[name]` |
| 207 | +- **Release:** Automated via semantic-release on `master` branch |
| 208 | + |
| 209 | +### Release Process |
| 210 | + |
| 211 | +- **Automated:** semantic-release handles versioning, changelog, npm publish, and GitHub releases |
| 212 | +- **Commit convention:** Conventional Commits (feat, fix, chore, etc.) |
| 213 | +- **Version:** Currently `1.2.0` |
| 214 | +- **Published files:** `dist/`, `docs/`, `README.md`, `LICENSE` |
| 215 | +- **Binary:** `codeops-mcp` CLI command (from `dist/index.js`) |
| 216 | + |
| 217 | +## Special Rules (Project-Specific) |
| 218 | + |
| 219 | +``` |
| 220 | +1. The docs/ directory contains the core rule documents that are SHIPPED with the npm |
| 221 | + package. Changes to docs/ files affect ALL users of codeops-mcp. Treat them as public API. |
| 222 | +
|
| 223 | +2. stdout is RESERVED for MCP protocol communication. All logging MUST go to stderr |
| 224 | + (use console.error, not console.log, except for --version output). |
| 225 | +
|
| 226 | +3. Tool functions return formatted markdown strings — they never throw errors. |
| 227 | + All error conditions are returned as "**Error:** message" formatted strings. |
| 228 | +
|
| 229 | +4. The analyze_project tool has TWO paths: |
| 230 | + - Fresh generation: No existing .clinerules/project.md → generate from scratch |
| 231 | + - Incremental merge: Existing file found → parse sections, merge with fresh scan, |
| 232 | + preserve user customizations (Coding Conventions, Git Conventions, Special Rules), |
| 233 | + update auto-detectable sections (Toolchain, Commands, Structure) |
| 234 | +
|
| 235 | +5. Tests use the REAL docs/ directory for integration testing (not mocks). |
| 236 | + The test setup (tools-setup.ts) uses lazy caching to avoid repeated file I/O. |
| 237 | +
|
| 238 | +6. Import paths MUST include .js extension (e.g., './config.js', '../types/index.js') |
| 239 | + because of Node16 module resolution with ESM. |
| 240 | +
|
| 241 | +7. The 6 rule document IDs are hardcoded in RULE_METADATA and RULE_ALIASES in types/index.ts. |
| 242 | + Adding a new rule document requires updating both maps. |
| 243 | +
|
| 244 | +8. All test files live under src/__tests__/ mirroring the src/ structure. |
| 245 | + Test files are excluded from TypeScript compilation (tsconfig.json exclude). |
| 246 | +``` |
| 247 | + |
| 248 | +## Test Structure |
| 249 | + |
| 250 | +``` |
| 251 | +4 test files, 106 total tests: |
| 252 | +
|
| 253 | +src/__tests__/store/rule-store.test.ts — 21 tests (loading, lookup, fuzzy matching, categories, metadata) |
| 254 | +src/__tests__/store/search-engine.test.ts — 12 tests (indexing, search, scoring, filtering, excerpts) |
| 255 | +src/__tests__/tools/core-tools.test.ts — 28 tests (get_rule, list_rules, search_rules, get_setup_guide) |
| 256 | +src/__tests__/tools/analyze-project-merge.test.ts — 45 tests (parser, classifier, merge engine, integration) |
| 257 | +
|
| 258 | +Test style: |
| 259 | +- Integration tests using real docs/ directory |
| 260 | +- Temp directory tests for filesystem operations (mkdtemp + cleanup) |
| 261 | +- Fixture constants for merge tests (FIXTURE_FULL_PROJECT_MD, SAMPLE_ANALYSIS, etc.) |
| 262 | +- beforeAll for shared setup, beforeEach/afterEach for temp dirs |
| 263 | +``` |
| 264 | + |
| 265 | +## Cross-References |
| 266 | + |
| 267 | +The generic rule files that read this `project.md`: |
| 268 | + |
| 269 | +- **make_plan.md** — Uses verify command, file paths, commit scope, task file path patterns |
| 270 | +- **code.md** — Uses language conventions, architecture rules |
| 271 | +- **testing.md** — Uses test commands, test locations, test framework |
| 272 | +- **git-commands.md** — Uses commit scope, verify command |
| 273 | +- **agents.md** — Uses shell commands, verify command |
0 commit comments