Release v1.0.0 - MCP Sampling & Major Refactor

.agent/rules/claude.md

@@ -0,0 +1,141 @@
+---
+trigger: always_on
+---
+
+# Claude Instructions for code-executor-mcp
+
+> 📚 **Quick Reference:** Type these in chat to load into context:
+> - `@docs/coding-standards.md` - SOLID/DRY/KISS, TDD, best practices
+> - `@docs/release-workflow.md` - Patch/minor/major release steps
+
+## 🚨 CRITICAL: Always Use Code Executor MCP
+
+**MANDATORY:** Use `mcp__code-executor__executeTypescript` + `callMCPTool` for ALL operations:
+- ❌ **DON'T:** Write tool, Read tool, Bash commands for file operations
+- ✅ **DO:** `executeTypescript` with `callMCPTool('mcp__filesystem__write_file', ...)`
+
+**Why this matters:**
+- Single round-trip (discover + execute + verify in one call)
+- Tests the actual MCP we're building (dogfooding)
+- Variables persist across operations (no context switching)
+- Real-world usage pattern that validates our architecture
+
+**Example - File Operations:**
+```typescript
+// ❌ BAD: Using traditional tools
+Write('/tmp/test.json', content);  // Doesn't test our MCP
+
+// ✅ GOOD: Using code-executor MCP
+await mcp__code-executor__executeTypescript({
+  code: `
+    const tools = await discoverMCPTools({ search: ['file'] });
+    const content = JSON.stringify({ test: true }, null, 2);
+    await callMCPTool('mcp__filesystem__write_file', {
+      path: '/tmp/test.json',
+      content
+    });
+    const result = await callMCPTool('mcp__filesystem__read_file', {
+      path: '/tmp/test.json'
+    });
+    console.log('Verified:', JSON.parse(result.content));
+  `,
+  allowedTools: ['mcp__filesystem__*']
+});
+```
+
+**When to use traditional tools:**
+- Reading project source code for review/analysis
+- Git operations (commits, merges, branches)
+- Build/test commands (`npm run build`, `npm test`)
+- Everything else: Use code-executor MCP
+
+## Project Overview
+
+**code-executor-mcp** - Universal MCP server with progressive disclosure | **98% token reduction** (141k → 1.6k)
+
+**Core Concept:** 2 execution tools (`executeTypescript`, `executePython`) call other MCPs on-demand via `callMCPTool('mcp__server__tool', params)`
+
+**Key Features:** Progressive disclosure | AJV schema validation | AsyncLock schema cache | Deno sandbox | Multi-transport (STDIO/HTTP)
+
+## Current State
+
+**Version:** v0.3.1 (pre-1.0 beta) | **Branches:** `main` (stable, PR-only) + `develop` (active) | **Stack:** TypeScript 5.x + Node.js 20+ + @modelcontextprotocol/sdk + AJV + async-lock + Vitest + Deno
+
+**Recent:** Deep validation (AJV) | AsyncLock mutex | 253 tests (98%+ coverage) | Runtime validation primary approach
+
+## Architecture
+
+**Components:** MCP Proxy Server | MCP Client Pool (STDIO/HTTP) | Schema Cache (24h TTL, AsyncLock) | Schema Validator (AJV) | Executors (TypeScript/Deno, Python)
+
+**Key Files:** `package.json` | `CHANGELOG.md` | `RELEASE.md` | `SECURITY.md`
+
+## Development Workflow
+
+**Branch Strategy:** Work on `develop` → PR to `main` → `npm version` → `gh release create` → sync `develop`
+
+**Commands:** `npm test` | `npm run typecheck` | `npm run build` | `npm run lint`
+
+**Standards:** TDD mandatory | 98%+ coverage (validation/caching) | TypeScript strict | SOLID principles | Security first
+
+**Important:** When performing these tasks, reference the relevant docs:
+- **Writing code?** Reference @docs/coding-standards.md for SOLID/DRY/KISS principles, TDD requirements
+- **Creating release?** Reference @docs/release-workflow.md for step-by-step patch/minor/major instructions
+
+## Key Decisions
+
+**AJV:** Industry-standard | Deep recursive validation | Self-documenting errors | Zero maintenance
+**AsyncLock:** Prevents race conditions | Thread-safe cache writes | Production-ready
+**24h TTL:** Schemas rarely change | Reduces network overhead | Stale-on-error resilience
+
+## Common Tasks
+
+**Feature:** `develop` branch → TDD → implement → tests → CHANGELOG → commit → PR
+**Bugfix:** Failing test → fix → verify → CHANGELOG → `fix:` commit
+**Release:** See [Release Workflow](docs/release-workflow.md) for step-by-step instructions (patch/minor/major)
+
+## Testing
+
+**Structure:** Vitest + TypeScript | Mock dependencies | `vi.useFakeTimers()` | Test edge cases
+**Coverage:** Validation 98%+ | Caching 70%+ | Overall 90%+
+**Focus:** ✅ Logic/errors/edge cases/security | ❌ Third-party libs
+
+## Security (ZERO TOLERANCE)
+
+**Validation:** MUST validate all MCP tool calls | Nested objects/arrays recursive | No type coercion | No info leakage
+**Sandbox:** Minimal Deno permissions | Block eval/exec/__import__ | Prevent path traversal | Rate limiting
+**Audit:** Log all executions (timestamp, tool, params hash, status) | NO sensitive data
+
+## Dependencies
+
+**Production:** @modelcontextprotocol/sdk | ajv ^8.17.1 | async-lock ^1.4.1 | zod | ws
+**Development:** vitest | typescript | @types/async-lock
+
+## Troubleshooting
+
+**Fake Timers:** `vi.useFakeTimers()` in `beforeEach` | `vi.advanceTimersByTime()` | `vi.useRealTimers()` in `afterEach`
+**Cache Corruption:** Check AsyncLock | Delete `~/.code-executor/schema-cache.json`
+**Validation:** Check AJV errors | Verify schema | Test minimal params first
+
+## Available Agents (Use Proactively)
+
+- **code-guardian** - Review code quality, SOLID principles, MCP patterns, security (use after implementation)
+- **inquisitor** - Debug complex issues, trace root causes, systematic investigation (use for bugs)
+- **project-librarian** - Explore codebase, find files/functions, understand structure (use before changes)
+- **project-documentarian** - Maintain devlogs, preserve context, JSDoc enhancement (use for documentation)
+- **document-reviewer** - Review documentation quality and completeness (use for docs)
+- **research-specialist** - Fetch latest library docs, research technical questions (use for unknowns)
+
+## Available Slash Commands (Use Proactively)
+
+- **/build** - Build with TypeScript/ESLint enforcement, clean dist/ artifacts
+- **/code-review** - Comprehensive review against MCP server standards, invoke code-guardian
+- **/commit** - Create proper git commits with validation, handle pre-commit hooks
+- **/debug** - Investigate MCP server issues, schema validation, concurrency problems
+- **/fix** - Fix issues at root cause, enforce proper solutions (no quick hacks)
+- **/test** - Execute Vitest tests, focus on validation/caching/security coverage
+- **/compact_FILE** - Consolidate verbose files, remove duplicates, preserve all info
+- **/split-context** - Extract area-specific content into local CLAUDE.md files
+
+## Contact
+
+**Issues:** https://github.com/aberemia24/code-executor-MCP/issues | **Email:** aberemia@gmail.com | **Docs:** https://github.com/aberemia24/code-executor-MCP#readme

.agent/rules/coding-standards.md

@@ -0,0 +1,146 @@
+---
+trigger: always_on
+---
+
+# Code Executor MCP - Coding Standards
+
+**Project:** MCP orchestration server | **Stack:** Node.js 22+ | TypeScript 5.x (strict) | Vitest 4.0 | AJV 8.x | Deno 2.x
+
+## ⚡ ZERO TOLERANCE
+
+Build fails on violations. NO workarounds. **Priority:** Security > Validation > Architecture > Style
+
+## 🔴 CRITICAL RULES
+
+### Security & Validation
+- **AJV validation MANDATORY** - ALL MCP tool calls validated (deep recursive, no bypass)
+- **NO type coercion** - Strict type checking (integer ≠ number)
+- **Sandbox isolation** - Deno permissions minimal, dangerous pattern detection
+- **AsyncLock MANDATORY** - ALL concurrent disk writes (schema cache, audit logs)
+- **Audit everything** - Tool calls, executions, failures with timestamps
+- **NO hardcoded secrets** - Env vars only, validated with Zod
+
+### Architecture
+- **SOLID** - SRP strict | NO God Objects | KISS | DRY pragmatic | YAGNI
+- **NO ANY types** - Use `unknown` + type guards
+- **Progressive disclosure** - Tools loaded on-demand, not upfront
+- **Race condition free** - AsyncLock mutex for all shared resources
+
+### Testing & Quality
+- **TDD MANDATORY** - Business logic and validation (98%+ coverage)
+- **Edge cases first** - Nested objects, concurrent access, TTL expiration
+- **Fake timers** - Use `vi.useFakeTimers()` for time-based tests (NO setTimeout)
+- **Coverage goals** - Validation 98%+ | Caching 70%+ | Overall 90%+
+
+## 🧠 STACK
+
+**Runtime:** Node.js 22+ LTS | **Executors:** Deno 2.x (TS), Python 3.9+ | **Testing:** Vitest 4.0 | **Validation:** AJV 8.x
+**MCP:** @modelcontextprotocol/sdk | **Concurrency:** async-lock | **Transport:** STDIO + HTTP/SSE
+
+## 📋 PATTERNS
+
+### Schema Validation (AJV)
+```typescript
+const result = validator.validate(params, schema);
+if (!result.valid) throw new Error(validator.formatError(toolName, params, schema, result));
+```
+
+### Cache Access (AsyncLock)
+```typescript
+await this.lock.acquire('cache-write', async () => { await fs.writeFile(cachePath, data); });
+```
+
+### MCP Tool Calls (Progressive Disclosure)
+```typescript
+const result = await callMCPTool('mcp__zen__codereview', { step: '...', step_number: 1 });
+```
+
+## 🧪 TESTING
+
+| Component | Coverage | Approach |
+|-----------|----------|----------|
+| Validation | 98%+ | TDD: RED→GREEN→REFACTOR |
+| Caching | 70%+ | Race conditions, TTL, concurrency |
+| Executors | 80%+ | Sandbox escapes, permissions |
+| Security | 95%+ | Input validation, pattern detection |
+
+**Pass rates:** Validation ≥98% | Core ≥90% | Integration ≥80%
+
+### Test Standards
+```typescript
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+vi.advanceTimersByTime(150); // Deterministic time control
+```
+
+## 🚀 BUILD
+
+- **NO suppression** - `ignoreBuildErrors: false` | NO `@ts-ignore`
+- **TypeScript strict** - Full strict mode enabled
+- **Pre-commit** - `npm run lint && npm run typecheck && npm run build && npm test`
+- **Environment** - Node.js v22.x LTS | npm | TypeScript 5.x strict
+
+## 📐 REFERENCE
+
+### Naming
+| Element | Format | Example |
+|---------|--------|---------|
+| Files | kebab-case | `schema-cache.ts` |
+| Classes | PascalCase | `SchemaValidator` |
+| Functions | camelCase | `getToolSchema()` |
+| Constants | UPPER_SNAKE | `DEFAULT_TTL_MS` |
+
+### Commands
+```bash
+npm run lint && npm run typecheck && npm run build && npm test  # Pre-commit
+npm run server     # Start MCP server
+npm test           # Run all tests
+npm run typecheck  # TypeScript check
+```
+
+## 🚫 FORBIDDEN
+
+### Validation
+❌ Skipping AJV validation | ❌ Type coercion | ❌ Shallow validation | ❌ Bypassing schema checks
+
+### Build
+❌ `@ts-ignore` | ❌ `any` types | ❌ `ignoreBuildErrors: true` | ❌ Unvalidated inputs
+
+### Concurrency
+❌ Concurrent writes without mutex | ❌ Shared resource without lock
+
+### Security
+❌ Hardcoded secrets | ❌ Missing sandbox permissions | ❌ Path traversal | ❌ Command injection
+
+### Testing
+❌ `setTimeout` in tests | ❌ Skipping edge cases | ❌ Missing coverage on validation
+
+### Deprecated
+❌ Custom shallow validation | ❌ Wrappers as primary approach | ❌ Unprotected disk writes
+
+## 🔒 SECURITY
+
+### Input Validation
+- **ALL external inputs** validated (MCP calls, env vars, file paths)
+- **Deep recursive** - Nested objects, arrays, constraints, enums
+- **Type strict** - No coercion (integer vs number)
+
+### Sandbox Isolation
+- **Deno minimal permissions** - Read/write/net restricted
+- **Dangerous patterns blocked** - eval, exec, __import__, pickle.loads
+- **Path validation** - No directory traversal
+- **Rate limiting** - 30 req/min default
+
+### Audit Logging
+- **ALL executions** logged (timestamp, tool, params hash, status)
+- **NO sensitive data** in logs
+
+## 📊 METRICS
+
+**Coverage:** Validation 98.27% | Cache 74% | Overall 90%+
+**Token Savings:** 98% (141k → 1.6k tokens)
+**Build:** <30s | **Test:** <60s
+
+---
+
+**Version:** 0.3.1 | **Node.js:** v22.x LTS | **Enforcement:** ESLint + TypeScript strict + pre-commit + CI/CD

.agent/workflows/build.md

@@ -0,0 +1,87 @@
+---
+argument-hint: [clean|production]
+description: Builds code-executor-mcp with strict TypeScript/ESLint enforcement, validates MCP server compilation
+allowed-tools: Bash, BashOutput, KillShell, Read, TodoWrite, Glob
+---
+
+Build "$ARGUMENTS" (default: development)
+
+## 🚨 CRITICAL BUILD LAWS
+
+**Non-Negotiable Rules:**
+
+- 📦 **ZERO TOLERANCE:** TypeScript/ESLint errors WILL fail build
+- 🎯 **Fix FIRST error**, not loudest (root cause analysis)
+- ⚙️ **Type Safety:** Full TypeScript strict mode enforcement
+- 🔧 **Clean Build:** dist/ directory must compile successfully
+
+---
+
+## 🧹 CLEAN (Nuclear Option)
+
+**When to clean:** Corrupted cache, mysterious build failures, or explicit `clean` argument
+
+```bash
+# Remove all build artifacts
+rm -rf dist node_modules/.cache
+
+# Clear schema cache
+rm -rf ~/.code-executor/schema-cache.json
+
+# Reinstall if package.json changed
+npm install
+```
+
+---
+
+## 🏗️ BUILD VALIDATION (MANDATORY SEQUENCE)
+
+**MCP Server compilation chain:**
+
+```
+TypeScript Compilation → Type Checking → Linting → dist/ Output
+```
+
+**Why:** Type safety ensures MCP tool schemas are correctly typed and validated
+
+---
+
+## 🔍 COMMON FAILURES & FIXES
+
+| Error                      | Root Cause                     | Solution                           |
+| -------------------------- | ------------------------------ | ---------------------------------- |
+| `Cannot find module`       | Invalid import path            | Check tsconfig.json paths          |
+| `Type error in executor`   | Schema validation types wrong  | Check AJV types and validators     |
+| `dist/ incomplete`         | Build interrupted              | `rm -rf dist && npm run build`     |
+| `Schema cache error`       | Corrupted cache file           | `rm ~/.code-executor/schema-cache.json` |
+| `@ts-ignore present`       | Type safety bypassed           | FORBIDDEN - Fix type issues        |
+
+---
+
+## ⚡ QUALITY CIRCUIT TRIGGER
+
+### Pre-Build Validation
+
+**ALWAYS run before build:**
+
+```bash
+npm run lint && npm run typecheck && npm run build
+```
+
+### Build Failure Escalation
+
+**TypeScript/ESLint errors → STOP and fix immediately:**
+- **Schema changes** → Verify schema-validator.ts types
+- **Type errors in executors** → Check TypeScript/Python executor types
+- **MCP SDK version mismatch** → Verify @modelcontextprotocol/sdk version
+
+### Success Path
+
+1. If build **PASSES** → Run test suite (`npm test`)
+2. **EXCEPTION:** Skip if issue documented in development notes
+
+**Safety Limit:** Max 5 circuit iterations to prevent infinite loops
+
+---
+
+**Type safety is LAW. Nuclear clean when corrupted.**