@tenantegroup/ai-rules-mcp 1.0.0

package/INSTALLATION.md

@@ -0,0 +1,52 @@
+# Installation Guide: `@tenantegroup/ai-rules-mcp`
+
+This guide explains how to hook the unified AI Rules MCP server into various AI assistants and editors.
+
+---
+
+## 1. Prerequisites
+Ensure you have Node.js (version 18 or higher) installed on your system.
+
+Install the package globally:
+```bash
+npm install -g @tenantegroup/ai-rules-mcp
+```
+
+---
+
+## 2. Editor & Client Configuration
+
+### Claude Desktop (macOS & Windows)
+1. Open the Claude config file:
+   * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+2. Add the following entry:
+   ```json
+   {
+     "mcpServers": {
+       "ai-rules": {
+         "command": "ai-rules-mcp"
+       }
+     }
+   }
+   ```
+3. Restart Claude Desktop.
+
+### Cursor / VS Code (with Roo Code or Cline)
+If you are using extension engines supporting MCP in VS Code:
+1. Open the extension's MCP Settings panel.
+2. Click **Add New MCP Server**.
+3. Set parameters:
+   * **Name**: `ai-rules`
+   * **Type**: `command`
+   * **Command**: `ai-rules-mcp`
+4. Save and restart the extension.
+
+---
+
+## 3. Verifying Installation
+In your chat, ask the assistant:
+* *"List all rules available in the AI Rules MCP server"*
+* *"Get the Cloudflare workflows rule"*
+
+The assistant should trigger a tool call to the server and display the returned Markdown content.

package/README.md

@@ -0,0 +1,57 @@
+# Unified AI Rules MCP Server (`@tenantegroup/ai-rules-mcp`)
+
+Model Context Protocol (MCP) server providing structured AI coding rules for **Cloudflare Backend**, **Nuxt Frontend**, **Flutter Client**, and **.NET MAUI Client** stacks. 
+
+It dynamically selects relevant rules based on task descriptions, file types, and keywords, achieving a **~75% token reduction** compared to loading all rules at once.
+
+---
+
+## ⚡ Key Features
+
+1.  **Smart Context Filtering**: Excludes dotNET rules during Flutter sessions and vice-versa, avoiding AI confusion and conserving token limits.
+2.  **Unified Installation**: One global package to install and maintain instead of multiple repository setups.
+3.  **Smart Scaffolder**: Run `install_rules_to_project` in any workspace. It auto-detects whether the project is Flutter, Nuxt, dotNET, or Cloudflare, and scaffolds the exact rules, context compilation, and pre-commit Git validators needed for that technology.
+
+---
+
+## 🛠️ Tech Stacks Covered
+
+*   **Cloudflare Backend**: Workers runtime edge parity, Drizzle ORM, D1 SQLite database, Workflows (durable sagas), KV storage, R2 bucket storage, and Durable Objects.
+*   **Nuxt Frontend**: Nuxt 4 directory structures, Pinia reactive state, components routing, and API integration client-side.
+*   **Flutter Client**: Riverpod state management, GoRouter routing, Retrofit client API integration, and Drift SQLite persistent database.
+*   **dotNET Client**: .NET MAUI UI shell, XAML layouts, MVVM pattern via CommunityToolkit, Refit strongly-typed HTTP, and sqlite-net.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Global Installation
+Install the unified package globally:
+```bash
+npm install -g @tenantegroup/ai-rules-mcp
+```
+
+### 2. Configure Claude Desktop
+Edit your Claude Desktop configuration (e.g. `%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "ai-rules": {
+      "command": "ai-rules-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop, and the server will be active.
+
+---
+
+## 📖 Available Tools
+
+*   `get_relevant_rules(task_description, file_types, keywords)`: Automatically detects target stacks and returns relevant directives.
+*   `get_rule_by_name(rule_name)`: Returns a specific rule (e.g., `flutter/riverpod` or `cloudflare/workflows`).
+*   `search_rule_content(query)`: Performs a regex search across the contents of all rule files.
+*   `list_all_rules()`: Lists available rules grouped by technology stack.
+*   `install_rules_to_project(target_dir, stack)`: Scaffolds the `.ai/rules/` directory and stack-specific Git validators (`validate-code.js`) into the target repository.

package/USAGE.md

@@ -0,0 +1,46 @@
+# Usage Guide: `@tenantegroup/ai-rules-mcp`
+
+The unified AI Rules MCP server can be used both directly by AI assistants during development and as a command-line tool to initialize new projects.
+
+---
+
+## 1. Interaction Guidelines (For AI Assistants)
+
+The assistant should call the tools automatically when you describe tasks. However, you can guide the assistant explicitly:
+
+*   **Task-Based Rules**: Ask the AI to:
+    *   *"Fetch the relevant rules for adding a table to my Drift database in Flutter."*
+    *   *"Get rules for deploying a Worker using GitHub Actions."*
+*   **Direct Rule Lookup**: Ask:
+    *   *"Show the C# MVVM standards."*
+    *   *"Load the Cloudflare Edge Parity rules."*
+
+The assistant uses the `get_relevant_rules` tool which filters files to minimize token footprint.
+
+---
+
+## 2. Setting Up a Local Project (For Developers)
+
+To configure static testing, compilation, and git hooks inside a repository, the assistant or developer can call `install_rules_to_project`.
+
+### Scaffolding via Claude/AI:
+Just type:
+> *"Install the AI rules to this project"* (or specify a path: *"Install the AI rules to /path/to/my-project"*).
+
+The tool will:
+1. Scan your project folder.
+2. Auto-detect if it's a **Flutter**, **dotNET**, **Nuxt**, or **Cloudflare** workspace.
+3. Create `.ai/rules/` and copy only the rule files for that stack.
+4. Copy validation tools (`validate-code.js`) if available.
+
+### Activate Local Git Hooks & Context (Nuxt/Cloudflare stacks):
+If you initialized a Nuxt/Cloudflare project:
+1. Run the hook installer to prevent non-compliant commits:
+   ```bash
+   node .ai/scripts/install-hooks.js
+   ```
+2. Compile rule sets into `.cursorrules`, `CLAUDE.md`, and `GEMINI.md`:
+   ```bash
+   node .ai/scripts/compile-context.js
+   ```
+   This ensures that even local offline models read rules instantly.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tenantegroup/ai-rules-mcp",
+  "version": "1.0.0",
+  "description": "Unified MCP server providing AI coding rules for Cloudflare Backend, Nuxt Frontend, Flutter Client, and dotNET MAUI stacks with smart context filtering",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "ai-rules-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "ai",
+    "coding-rules",
+    "model-context-protocol",
+    "cloudflare",
+    "workers",
+    "d1",
+    "drizzle",
+    "workflows",
+    "nuxt",
+    "vue",
+    "flutter",
+    "dart",
+    "riverpod",
+    "drift",
+    "dotnet",
+    "csharp",
+    "maui",
+    "mvvm",
+    "sqlite",
+    "refit",
+    "claude",
+    "copilot",
+    "gemini"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "src/",
+    "rules/",
+    "templates/",
+    "README.md",
+    "INSTALLATION.md",
+    "USAGE.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  }
+}

package/rules/cloudflare/api-services.md

@@ -0,0 +1,80 @@
+# API-Only Service Standards
+
+## Framework Standard
+- Use Nuxt (Nitro) deployed to Cloudflare Workers for all API-only backend services
+- Do NOT introduce additional backend frameworks (e.g., Hono) without documented technical limitation
+- Treat Nuxt as a structured server framework (UI layer not required)
+
+## API Design Principles
+All API services must:
+- Use REST architecture with mandatory versioning (`/api/v1/...`)
+- Enforce Zod validation on all inputs
+- Implement structured logging with request IDs
+- Use centralized error handling
+- Apply API key authentication as minimum standard
+- Implement rate limiting where appropriate
+- Include audit logging for sensitive operations
+- Follow D1 migration and testing standards
+
+## Project Structure for API-Only Services
+Organize API routes by version:
+```
+server/
+  api/
+    v1/
+      users.get.ts
+      users.post.ts
+      tasks.get.ts
+  middleware/
+  services/
+  utils/
+```
+
+## API Route Pattern
+Every endpoint must:
+- Wrap handler in centralized error handling
+- Use structured logger
+- Validate input using Zod schemas
+- Return consistent JSON structure
+- Include appropriate HTTP status codes
+
+## Versioning Strategy
+- Use URL path versioning: `/api/v1/`, `/api/v2/`
+- Never break existing API versions
+- Maintain backward compatibility when possible
+- Deprecate old versions with clear timeline
+
+## Authentication for APIs
+Choose based on consumer type:
+- **Internal Services**: Mutual TLS or API key authentication
+- **Mobile Apps**: JWT access tokens + refresh tokens
+- **Third-Party**: API key + secret with rate limiting
+- **Public APIs**: OAuth 2.0 where appropriate
+
+## Response Format Standard
+Return consistent JSON structure:
+```json
+{
+  "success": true,
+  "data": {...},
+  "error": null
+}
+```
+
+Or for errors:
+```json
+{
+  "success": false,
+  "data": null,
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "User-friendly message"
+  }
+}
+```
+
+## Future-Proofing
+Structure projects so they can evolve into fullstack Nuxt applications without architectural rewrites.
+
+## Consistency Rule
+Nuxt + Cloudflare is the backend platform. Framework consistency is mandatory.

package/rules/cloudflare/cicd-deployment.md

@@ -0,0 +1,56 @@
+# CI/CD & Deployment Standards
+
+## Branch Model
+Use Git flow with these branches:
+- `main` → production environment
+- `staging` → staging environment
+- `feature/*` → pull requests only (no direct deployment)
+
+## Deployment Rules
+- Deploy to production only from `main` branch
+- Deploy to staging only from `staging` branch
+- Execute all migrations before production release
+- Run smoke tests after deployment
+- Require pull request approval before merging to `main`
+
+## CI Pipeline Requirements
+Every project must have GitHub Actions workflow including:
+1. **Install**: Install dependencies
+2. **Build**: Build application with Cloudflare preset
+3. **Test**: Run full test suite
+4. **Deploy**: Deploy via Wrangler to appropriate environment
+
+## Pre-Deployment Checklist
+Before every production deployment:
+- [ ] All tests passing
+- [ ] Migration review completed
+- [ ] Staging deployment verified
+- [ ] Database backups confirmed (if applicable)
+- [ ] Rollback plan documented
+
+## Deployment Process
+1. Merge approved PR to `main` or `staging`
+2. CI pipeline runs automatically
+3. Migrations execute before code deployment
+4. Application deploys via Wrangler
+5. Smoke test endpoint validates deployment
+6. Monitor logs for errors
+
+## Smoke Test Requirements
+- Create health check endpoint at `/api/health`
+- Verify database connectivity
+- Verify critical bindings (D1, KV, etc.)
+- Return 200 OK when healthy
+- Return 503 when unhealthy
+
+## Environment-Specific Configuration
+- Use Wrangler environment blocks in `wrangler.toml`
+- Configure separate D1 databases per environment
+- Use environment-specific secrets
+- Test environment parity locally before deployment
+
+## Rollback Strategy
+- Tag releases in Git for easy rollback
+- Document rollback procedure in README
+- Keep previous version deployable
+- Test rollback process in staging

package/rules/cloudflare/database-orm.md

@@ -0,0 +1,28 @@
+# Database & ORM Standards
+
+## Database Strategy
+- Use D1 (SQLite) as default for all projects
+- Maintain one database per environment
+- Apply schema-first thinking to database design
+- Never use KV as primary relational storage (KV is cache only)
+
+## Drizzle ORM Pattern
+- Maintain one central schema file at `/server/db/schema.ts`
+- Define all tables clearly with explicit typing
+- Declare relations explicitly
+- Encapsulate all queries within services
+- Avoid raw SQL unless absolutely necessary
+- Inject database instances into service constructors
+
+## Migration Rules
+- Generate a new migration for every schema change using `drizzle-kit generate`
+- Never modify migrations after they have been applied
+- Commit all migrations to the repository
+- Review production migrations before deployment
+- Apply migrations using `drizzle-kit migrate`
+
+## Query Guidelines
+- Keep all queries encapsulated within service methods
+- Use Drizzle's query builder for type safety
+- Avoid N+1 query patterns
+- Index frequently queried columns

package/rules/cloudflare/edge-parity.md

@@ -0,0 +1,24 @@
+# Cloudflare Edge Parity
+
+## Runtime Requirements
+- Design all code for Cloudflare Workers runtime, not Node.js
+- Use Web Standard APIs only (Fetch, Web Crypto, Service Worker model)
+- Never use Node core modules: `fs`, `path`, `net`, `process`, `crypto` (Node version)
+- Ensure local development, CI, and production behave identically
+
+## Required Tooling
+- Use `wrangler dev` for local development (not `nuxt dev` alone)
+- Apply local D1 migrations before any production deployment
+- Declare all bindings (D1, KV, R2, Queues, Durable Objects) in `wrangler.toml`
+- Test bindings locally before deployment
+- Use Nitro Cloudflare preset for all Nuxt projects
+- Access environment variables via Worker bindings, never `process.env`
+
+## Development Workflow
+- Run projects locally using `wrangler dev`
+- Validate all features against local Worker runtime before deployment
+- Pass all E2E tests against `http://localhost:8787`
+- Run full parity pipeline in CI
+
+## Critical Rule
+Deployment must never be the first time Cloudflare runtime behavior is validated.

package/rules/cloudflare/kv-usage.md

@@ -0,0 +1,31 @@
+# KV Usage Policy
+
+## Core Principle
+KV is an acceleration layer, not a database.
+
+## Appropriate KV Use Cases
+Use KV for:
+- Caching expensive database reads
+- Rate limiting counters
+- Feature flags
+- Session caching (with D1 as source of truth)
+- Temporary data with TTL requirements
+
+## KV Restrictions
+Never use KV for:
+- Primary relational data storage
+- Critical data without D1 backup
+- Complex querying or joins
+- Transactional operations
+- Data requiring strong consistency guarantees
+
+## Data Hierarchy
+- D1 = source of truth
+- KV = performance enhancement layer
+
+## Implementation Guidelines
+- Always write to D1 first, then cache in KV
+- Set appropriate TTL values for cached data
+- Implement cache invalidation strategies
+- Handle KV misses gracefully by falling back to D1
+- Document what data is cached and why

package/rules/cloudflare/logging-observability.md

@@ -0,0 +1,66 @@
+# Logging & Observability
+
+## Core Logging Principles
+- All logs must be structured JSON format
+- Every request must have a unique `requestId`
+- Never log secrets or sensitive credentials
+- Disable debug logs in production
+- Maintain logging consistency across all project components
+
+## Required Log Fields
+Include in every log entry:
+- `level` (debug, info, warn, error, fatal)
+- `event` (machine-readable event name)
+- `timestamp` (ISO 8601 format)
+- `requestId` (unique per request)
+
+Optional but recommended:
+- `userId`
+- `organizationId`
+- `durationMs`
+- `metadata` (context-specific data)
+
+## Log Levels Standard
+Use these levels consistently:
+- **debug**: Development diagnostics only (disabled in production)
+- **info**: Normal business events and operations
+- **warn**: Recoverable issues requiring attention
+- **error**: Operational failures
+- **fatal**: System-level crash or unrecoverable state
+
+## Where Logging Must Occur
+Implement logging at:
+- **Middleware**: Request start, response status, duration
+- **Services**: Major business events (create, update, delete)
+- **Database**: Slow queries, connection issues
+- **Background Jobs**: Job start, completion, failure
+- **Authentication**: Login attempts, failures, logouts
+
+## Request ID Implementation
+- Generate unique `requestId` using `crypto.randomUUID()` in middleware
+- Attach `requestId` to event context
+- Include `requestId` in all downstream logs
+- Use `requestId` to trace requests across services
+
+## Centralized Logger
+- Create single logger utility at `/server/utils/logger.ts`
+- Use logger utility consistently across entire application
+- Never use `console.log` directly in application code
+
+## Production Observability Minimum
+Implement before production launch:
+- Request logging with request IDs
+- Error boundaries with proper logging
+- Health check endpoint for monitoring
+- Structured log output for aggregation
+
+## Scaling Observability
+Add as system matures:
+- External log aggregation service
+- Error tracking service (e.g., Sentry)
+- Performance monitoring
+- Alerting on critical errors
+- Dashboard for operational metrics
+
+## Critical Rule
+If production fails, diagnosis must be possible through logs alone.

package/rules/cloudflare/performance.md

@@ -0,0 +1,44 @@
+# Performance Standards
+
+## Core Principle
+Measure first. Optimize second.
+
+## Pre-Optimization Checklist
+Before adding infrastructure, verify you have:
+- [ ] Indexed all frequently queried database columns
+- [ ] Eliminated N+1 query patterns
+- [ ] Cached heavy reads in KV where appropriate
+- [ ] Minimized JSON payload sizes
+- [ ] Implemented lazy-loading for heavy frontend components
+- [ ] Measured actual performance bottlenecks
+
+## Scaling Path (In Order)
+Add optimizations incrementally as needed:
+1. **Phase 1**: Add KV caching layer for read-heavy operations
+2. **Phase 2**: Implement rate limiting to protect resources
+3. **Phase 3**: Introduce Queues for background processing
+4. **Phase 4**: Harden RBAC and add granular permissions
+5. **Phase 5**: Add advanced monitoring and alerting
+
+## Database Performance
+- Index columns used in WHERE clauses
+- Index columns used in JOIN conditions
+- Index columns used for sorting
+- Avoid SELECT * queries; request only needed columns
+- Use database query analysis to identify slow queries
+
+## Caching Strategy
+- Cache expensive computations in KV
+- Set appropriate TTL values
+- Implement cache invalidation on writes
+- Monitor cache hit rates
+- Document what is cached and why
+
+## Frontend Performance
+- Lazy-load components not needed on initial render
+- Minimize bundle size
+- Use code splitting where appropriate
+- Optimize images and assets
+
+## Critical Rule
+Never prematurely optimize. Optimize only when measurements justify the effort.

package/rules/cloudflare/realtime-background.md

@@ -0,0 +1,58 @@
+# Realtime & Background Processing
+
+## Durable Objects
+
+Use Durable Objects only when:
+- Coordinated shared state is required across multiple clients
+- Building realtime collaboration features
+- Implementing chat systems or presence features
+- Consistent state management is needed beyond simple KV
+
+Do NOT use for:
+- Simple async tasks (use Queues instead)
+- General caching (use KV instead)
+- Standard CRUD operations (use D1 instead)
+- Multi-step orchestration (use Workflows instead)
+
+## Queues
+
+Use Cloudflare Queues for:
+- Asynchronous email processing
+- Webhook delivery and retry logic
+- Background job processing
+- Decoupled async workloads
+- Tasks that can tolerate eventual consistency
+
+Do NOT use for:
+- Multi-step transactions requiring state persistence (use Workflows instead)
+- Operations requiring saga-pattern rollbacks (use Workflows instead)
+- Long-running operations that exceed ~15 minute execution time (use Workflows instead)
+
+Queue Implementation Rules:
+- Keep queue handlers idempotent
+- Implement proper error handling and retry logic
+- Log queue processing for observability
+- Monitor queue depth and processing times
+
+## Push Notifications
+- Handle push notifications via external services (FCM for Android, APNs for iOS)
+- Do NOT implement custom push infrastructure
+- Use Queues to process and batch notification sends
+
+## Decision Tree: Workflows vs Queues vs Durable Objects
+
+| Question | Answer | Use |
+|----------|--------|-----|
+| Need to orchestrate multiple external systems? | Yes | **Workflows** |
+| Need to coordinate real-time state across clients? | Yes | **Durable Objects** |
+| Need simple fire-and-forget async tasks? | Yes | **Queues** |
+| Need saga-pattern rollbacks on failure? | Yes | **Workflows** |
+| Need state persistence across pauses? | Yes | **Workflows** |
+| Need to wait for external events/approvals? | Yes | **Workflows** |
+| Need to coordinate in-memory state for 1-2 clients? | Yes | **Durable Objects** |
+| Need to process batches of simple tasks? | Yes | **Queues** |
+
+**For comprehensive guidance on Workflows** (orchestration, saga rollbacks, idempotency, state management), see **09-workflows.md**.
+
+## General Guideline
+Start simple. Add Durable Objects, Queues, or Workflows only when clear requirements justify them.