@tenantegroup/ai-rules-mcp 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to the `@tenantegroup/ai-rules-mcp` project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] - 2026-07-02
+
+### Added
+- **TypeScript Clean Code Manual**: Created [03 - TypeScript Clean Code Standards.md](vault/00%20-%20Core%20Standards/03%20-%20TypeScript%20Clean%20Code%20Standards.md) in the vault's core standards.
+- **MCP Code Quality Updates**: Integrated Clean Code principles (variables, naming, functions, immutability, side-effect prevention) into [rules/nuxt/code-quality.md](rules/nuxt/code-quality.md).
+- Updated [vault/99 - Master Index.md](vault/99%20-%20Master%20Index.md) to register the new Clean Code manual.
+
+---
+
+## [1.1.0] - 2026-07-02
+
+### Added
+- **Obsidian Vault Integration**: Relocated the entire documentation vault into the repository under the [vault/](vault/) folder for unified maintenance.
+- **AI bot mitigation postures**: Added detailed documentation for **Open** (maximum visibility), **Balanced** (standard SEO, block AI training), and **Strict** (lockdown) configurations in [rules/cloudflare/security.md](rules/cloudflare/security.md).
+- **AI Agent Action Directive**: Embedded inline instructions in security rules guiding AI assistants to interactively prompt users when setting up bot controls.
+- **Developer Guide Enhancements**: Expanded configuration instructions for Claude Code, GitHub Copilot, Antigravity CLI, and Pi Coding Agent.
+- **Preview & Testing URL Security Guidelines**: Added instructions on how to programmatically secure or disable Cloudflare testing/preview subdomains (`*.workers.dev` and `*.pages.dev`) in both Workers and Pages setups.
+
+### Changed
+- Updated [.gitignore](.gitignore) to exclude local Obsidian configurations (`vault/.obsidian/` and `vault/.trash/`).
+
+### Fixed
+- Outdated Drizzle Kit configuration rules: updated the `drizzle.config.ts` template and rules to use dialect `'sqlite'` and driver `'d1-http'` to prevent configuration parsing errors in newer versions of Drizzle Kit (v0.21+ / v0.31+).
+
+---
+
+## [1.0.0] - 2026-07-01
+
+### Added
+- Initial release of the Unified AI Rules MCP Server.
+- Dynamic rule filtering based on file types, stack detection, and keywords.
+- Support for Cloudflare Backend, Nuxt Frontend, Flutter Client, and .NET MAUI stacks.
+- Built-in smart project scaffolder (`install_rules_to_project`).

package/README.md

@@ -1,57 +1,170 @@
-# Unified AI Rules MCP Server (`@tenantegroup/ai-rules-mcp`)
+# 🎯 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. 
+[![npm version](https://img.shields.io/npm/v/@tenantegroup/ai-rules-mcp.svg?style=flat-round)](https://www.npmjs.com/package/@tenantegroup/ai-rules-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-blue.svg)](https://nodejs.org/)
 
-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.
+Model Context Protocol (MCP) server providing structured, production-tested AI coding rules for **Cloudflare Backend**, **Nuxt Frontend**, **Flutter Client**, and **.NET MAUI Client** stacks.
+
+By dynamically scanning your current task, files, and keywords, it selects only the rules relevant to your active session. This achieves a **~75% token footprint reduction** and prevents conflicting instructions between frontend, mobile, and backend paradigms (e.g., stopping mobile SQLite rules from polluting a Cloudflare D1 worker context).
 
 ---
 
 ## ⚡ 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.
+1. **Smart Context Filtering**: Dynamically evaluates stack requirements, stripping out dotNET rules during Flutter sessions and vice-versa.
+2. **Interactive AI Scaffolder**: Integrates the `install_rules_to_project` tool. Running this inside any repository auto-detects the tech stack and copies appropriate `.ai/rules`, static compilers, and pre-commit Git validators.
+3. **Multi-Agent Support**: Out-of-the-box support for all major modern AI development interfaces.
+4. **Obsidian Vault Synced**: The source of truth rules are maintained in a structured Obsidian [vault/](vault/) folder right in the repository, making it easy to version-control documentation alongside the MCP code.
 
 ---
 
-## 🛠️ Tech Stacks Covered
+## 🛠️ Supported Stacks
 
-*   **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.
+* **Cloudflare Backend**: Workers runtime edge parity, Drizzle ORM, D1 SQLite, Workflows (durable sagas), KV storage, R2 bucket storage, and Durable Objects.
+* **Nuxt Frontend**: Nuxt 4 directories, Pinia reactive state, layout routing, and client-side API integrations.
+* **Flutter Client**: Riverpod state management, GoRouter, Retrofit clients, and Drift SQLite databases.
+* **dotNET Client**: .NET MAUI UI shell, XAML layouts, MVVM pattern (CommunityToolkit), Refit HTTP clients, and sqlite-net.
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Installation
+
+Ensure you have Node.js (version 18 or higher) installed, then install the package globally:
 
-### 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"
+## ⚙️ Configuration for Coding Agents
+
+### 1. Claude Desktop (macOS & Windows)
+Add the server to your desktop client configuration:
+* **Configuration File Location**:
+  * **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+  * **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+* **JSON Configuration**:
+  ```json
+  {
+    "mcpServers": {
+      "ai-rules": {
+        "command": "ai-rules-mcp"
+      }
     }
   }
-}
-```
+  ```
+* **To Apply**: Restart the Claude Desktop application.
+
+---
+
+### 2. Claude Code (CLI)
+Claude Code supports direct command-line utility configurations.
+* **Using the CLI (Recommended)**:
+  Run the interactive setup wizard in your terminal:
+  ```bash
+  claude mcp add --transport stdio ai-rules ai-rules-mcp
+  ```
+* **Manual Setup**:
+  Open or create `~/.claude.json` and add the configuration under the `mcpServers` block:
+  ```json
+  {
+    "mcpServers": {
+      "ai-rules": {
+        "command": "ai-rules-mcp",
+        "args": []
+      }
+    }
+  }
+  ```
+* **Verify Configuration**: Check connection status by running `claude mcp list`.
+
+---
+
+### 3. GitHub Copilot (CLI & IDEs)
+GitHub Copilot handles MCP integrations across CLI contexts and IDE extension layers.
+* **Using the Copilot CLI**:
+  Run the helper tool to bind the server:
+  ```bash
+  copilot mcp add
+  ```
+  *(Follow the interactive terminal wizard to select `stdio` type, name it `ai-rules`, and enter `ai-rules-mcp` as the command.)*
+* **Manual CLI Config Location**: Saved in `~/.copilot/mcp-config.json`.
+* **VS Code / Visual Studio**:
+  Click the **Configure Tools** gear icon inside the Copilot Chat pane, navigate to the MCP config panel, and add a local command server pointing to `ai-rules-mcp`.
+* **Repository-Level (GitHub.com)**:
+  Go to your repository **Settings** ➔ **Copilot** (under Code & Automation) ➔ **MCP Servers** to configure server hooks globally for your team's Copilot workspace.
+
+---
 
-Restart Claude Desktop, and the server will be active.
+### 4. Antigravity CLI (`agy`)
+The Google Antigravity developer environment natively integrates local and remote MCP hosts.
+* **Configuration File Location**:
+  * **Global Settings**: `~/.gemini/antigravity-cli/mcp_config.json`
+  * **Workspace-local Settings**: `.agents/mcp_config.json` (inside your project directory)
+* **JSON Configuration**:
+  ```json
+  {
+    "mcpServers": {
+      "ai-rules": {
+        "command": "ai-rules-mcp",
+        "args": []
+      }
+    }
+  }
+  ```
+* **TUI Management**:
+  Launch `agy` in your terminal and type `/mcp` to open the **Interactive MCP Manager** to check statuses and reload configurations.
+
+---
+
+### 5. Pi Coding Agent
+Pi manages external toolsets via the `pi-mcp-adapter`.
+* **Step 1: Install the Adapter**:
+  ```bash
+  pi install npm:pi-mcp-adapter
+  ```
+* **Step 2: Configuration File Location**:
+  * **Global**: `~/.pi/agent/mcp.json`
+  * **Project-local**: `.pi/mcp.json` (overrides global preferences)
+* **JSON Configuration**:
+  ```json
+  {
+    "mcpServers": {
+      "ai-rules": {
+        "command": "ai-rules-mcp",
+        "args": []
+      }
+    }
+  }
+  ```
+* **Step 3: Verification**:
+  Open the Pi REPL and use `/mcp setup` to auto-detect and register the server, or type `/mcp` to list active tools.
 
 ---
 
 ## 📖 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.
+*   `get_relevant_rules(task_description, file_types, keywords, include_all)`: Evaluates task context, filters irrelevant tech stacks, and returns matching standards.
+*   `get_rule_by_name(rule_name)`: Directly retrieves a specific rule (e.g., `flutter/riverpod`, `cloudflare/workflows`).
+*   `search_rule_content(query, case_sensitive)`: Performs a regex search inside the contents of all rule files.
+*   `list_all_rules()`: Lists all rule titles grouped by target technology stack.
+*   `install_rules_to_project(target_dir, stack)`: Scaffolds the `.ai/` settings folder, copies rule files, and drops git validator scripts into the specified project root directory.
+
+---
+
+## 📁 Obsidian Vault Structure
+
+The rules served by this MCP server are maintained in the [vault/](vault/) folder of this repository. This folder is structured to be opened directly as an Obsidian vault:
+*   `00 - Core Standards/` — General software engineering and reviewer standards.
+*   `01 - Cloudflare Backend Stack/` — Workers, Workflows, and D1 configuration standards.
+*   `02 - Nuxt Frontend Stack/` — Nuxt 4 and Vue configurations.
+*   `03 - Flutter Client Stack/` — Dart and Riverpod layouts.
+*   `04 - dotNET Client Stack/` — C# and .NET MAUI layouts.
+*   `99 - Master Index.md` — The central map linking all manual entries.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) (if present) or `package.json` for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenantegroup/ai-rules-mcp",
-  "version": "1.0.0",
+  "version": "1.2.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",
@@ -45,7 +45,8 @@
     "templates/",
     "README.md",
     "INSTALLATION.md",
-    "USAGE.md"
+    "USAGE.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18.0.0"

package/rules/cloudflare/security.md

@@ -138,11 +138,129 @@ Implement these before launching:
 - Set `Content-Disposition: attachment` on all endpoints that return binary file content to prevent inline browser rendering
 
 
+## Restricting Testing & Preview URLs
+
+Cloudflare generates default testing subdomains (`*.workers.dev` and `*.pages.dev`) for all Workers and Pages deployments. Since these preview URLs are public, they present a vector for search engine duplication, intellectual property exposure, and direct endpoint exploitation. You must restrict access to these testing channels.
+
+### 1. Cloudflare Workers (Programmatic)
+To disable public access via the default `*.workers.dev` subdomain programmatically:
+*   Configure `workers_dev = false` inside your `wrangler.toml` file.
+*   Once disabled, the Worker will only be accessible via your configured custom domains or internal service bindings.
+*   *Config Example:*
+    ```toml
+    name = "my-api-service"
+    main = "src/index.js"
+    compatibility_date = "2024-01-01"
+    workers_dev = false
+    ```
+
+### 2. Cloudflare Pages & Pages Previews
+Cloudflare Pages does not support disabling the default `*.pages.dev` subdomain or branch preview subdomains programmatically. You must secure them using one of the following methods:
+
+#### A. Cloudflare Access Policy (Recommended)
+Gate all preview URLs behind Cloudflare Zero Trust Access to enforce authorization (e.g., locking access to your organization's email domain or authenticated users):
+1.  Navigate to the Cloudflare Dashboard ➔ **Workers & Pages** ➔ select your Pages project.
+2.  Go to **Settings** ➔ **General** ➔ **Access policy**.
+3.  Click **Enable** (or **Manage**) to bind a Cloudflare Access application policy to your preview deployments.
+
+#### B. Programmatic Edge Middleware
+For a purely code-based restriction, implement a middleware check inside your Pages directory (e.g., `/functions/_middleware.js` for Pages or Nitro middleware for Nuxt) to block direct traffic attempting to connect via any host ending in `pages.dev`:
+
+```javascript
+// /functions/_middleware.js
+export const onRequest = async (context) => {
+  const url = new URL(context.request.url);
+
+  // Intercept and reject direct access to pages.dev subdomains
+  if (url.hostname.endsWith(".pages.dev")) {
+    return new Response(
+      JSON.stringify({
+        error: "Forbidden",
+        message: "Direct access to pages.dev subdomains is prohibited. Please use the registered custom domain."
+      }),
+      {
+        status: 403,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
+
+  return context.next();
+};
+```
+
+
 ## Dependency & Supply Chain Security *(OWASP A06)*
 
 - Configure Dependabot (`.github/dependabot.yml`) for weekly PRs covering npm packages and GitHub Actions in all projects
 - Add `pnpm audit` / `npm audit` as a required CI step on every push; surface known vulnerabilities before merge
 - Review D1 migrations before every production apply — no auto-apply on deploy
+## AI Crawler Control & Bot Mitigation Postures
+
+> [!IMPORTANT]
+> **AI Agent Action Directive**: When you (the AI agent) read this security rule or assist with setting up bot mitigation or crawler controls, you MUST:
+> 1. Ask the user to choose their preferred posture: **Open** (maximum search/AI indexing), **Balanced** (standard SEO but block AI model training), or **Strict** (locked down).
+> 2. Explain the business trade-offs of each posture.
+> 3. Provide the necessary code/configuration files (e.g., `robots.txt`) and outline the exact manual steps they need to take on their Cloudflare Dashboard for that posture.
+
+With the emergence of LLM scrapers, AGI agents, and AI search engines, standard bot protection must be tailored to the website's business goals. We define three distinct postures: **Open**, **Balanced (Medium)**, and **Strict**.
+
+---
+
+### Posture A: Open (Maximum Visibility)
+*   **Best for**: Public marketing sites, blogs, portfolios, and brand landing pages where searchability, AI recommendations (e.g., ChatGPT search, Gemini AI Overviews), and discovery are paramount.
+*   **Goal**: Invite all bots, AGI agents, and training scrapers to read and ingest the site's content so the business appears in all traditional and AI search results.
+
+#### 1. Programmatic Implementation (`robots.txt`)
+Configure `robots.txt` to explicitly grant permission for training and full content reproduction:
+```text
+User-agent: *
+Content-Signal: search=yes,ai-train=yes,use=full
+Allow: /
+```
+
+#### 2. Cloudflare Dashboard Settings
+*   **Legacy "Block AI Bots"**: Toggle **Off**.
+*   **AI Traffic Categories**: Explicitly set **Search**, **Agent**, and **Training** bots to **Allow**.
+*   *Note on Sept 15, 2026 update:* Ensure you opt out of default blocks for "Training" and "Agent" bots on pages with ads.
+
+---
+
+### Posture B: Balanced (Medium / Protection & SEO)
+*   **Best for**: SaaS product landing pages, corporate websites, or publications that want to show up in traditional search results (Google, Bing) but protect their intellectual property from being scraped to train AI models without consent.
+*   **Goal**: Allow discovery through standard search, but block AI model training.
+
+#### 1. Programmatic Implementation (`robots.txt`)
+Configure `robots.txt` to allow search but prohibit model training and restrict content use to excerpts:
+```text
+User-agent: *
+Content-Signal: search=yes,ai-train=no,use=reference
+Allow: /
+```
+
+#### 2. Cloudflare Dashboard Settings
+*   **Legacy "Block AI Bots"**: Toggle **On**.
+*   **AI Traffic Categories**: Set **Search** to **Allow**, but **Training** and **Agent** to **Block**.
+*   *Warning:* Under this setting, multi-purpose crawlers (e.g., Googlebot, Bingbot, Applebot) that crawl for both search and training will be blocked by default as of Sept 15, 2026. Review and override this behavior in the Cloudflare dashboard to allow their search crawls.
+
+---
+
+### Posture C: Strict (Maximum Lockdown)
+*   **Best for**: SaaS web applications, customer portals, internal tools, and private databases.
+*   **Goal**: Deny access to all bots, scrapers, and automated agents to protect user data, secure API endpoints, and reduce server bandwidth costs.
+
+#### 1. Programmatic Implementation (`robots.txt`)
+Tell all crawlers and agents that they are forbidden:
+```text
+User-agent: *
+Disallow: /
+```
+
+#### 2. Cloudflare Dashboard Settings
+*   **Legacy "Block AI Bots"**: Toggle **On**.
+*   **AI Traffic Categories**: Set **Search**, **Agent**, and **Training** bots to **Block**.
+*   **Bot Fight Mode**: Enable **On** (or set up custom WAF rules to challenge all traffic with a bot score below 30).
+*   **Transitive Trust validation**: Programmatically reject requests carrying proxy forwarded headers (e.g., block requests if the standard `Forwarded` header specifies AI operators, or return a `403 Forbidden` response).
 
 
 ## Advanced Security (When Scaling)

package/rules/nuxt/code-quality.md

@@ -1,25 +1,23 @@
 # Code Quality Standards
 
-## TypeScript Requirements
-- Enable strict mode in `tsconfig.json`
-- Never use `any` type without justification
-- Define interfaces for all data structures
-- Use type inference where appropriate
+## TypeScript Requirements & Clean Naming
+- Enable strict mode in `tsconfig.json` (specifically check `--strictNullChecks`)
+- Never use `any` type without justification; use explicit typing or generics
+- Define interfaces or type aliases for all data structures
+- Use meaningful, pronounceable, and searchable variable/constant names (avoid magic numbers/strings)
+- Avoid mental mapping; use explicit names (e.g. `user` instead of `u`)
+- Avoid unneeded context in property definitions (e.g. `make` instead of `carMake` inside a `Car` type)
+- Use default parameters instead of short-circuiting (`||` or ternary checks)
 - Export types for reuse across services
 
-## Code Organization
-- Keep functions small and focused (single responsibility)
-- Extract complex logic into named helper functions
-- Group related functionality in services
-- Avoid deep nesting (max 3 levels recommended)
-- Use early returns to reduce nesting
-
-## Naming Conventions
-- Use camelCase for variables and functions
-- Use PascalCase for classes and types
-- Use UPPER_CASE for constants
-- Use descriptive names (avoid abbreviations)
-- Prefix boolean variables with `is`, `has`, or `should`
+## Code Organization & Functions
+- Keep functions small and focused (Single Responsibility Principle)
+- Functions should ideally take **2 or fewer arguments**; consolidate larger parameter lists into a config object and use destructuring
+- Functions should do exactly one thing and maintain a single level of abstraction
+- Never use flags (boolean parameters) in function signatures; split them into separate functions (e.g. `createTempFile` vs `createFile`)
+- Avoid side effects: do not mutate input objects or arrays; return cloned, modified copies (e.g., `[...cart, item]` instead of `cart.push(item)`)
+- Group related functionality in classes or services
+- Avoid deep nesting (max 3 levels recommended) and use early returns
 
 ## Comments and Documentation
 - Write self-documenting code when possible

package/rules/nuxt/configuration.md

@@ -16,8 +16,9 @@
 ## drizzle.config.ts
 - Define schema in `/server/db/schema.ts`
 - Output migrations to `/drizzle` directory
-- Set driver to `d1`
-- Reference `wrangler.toml` for database credentials
+- Set dialect to `sqlite` (since D1 is SQLite-compatible)
+- Set driver to `d1-http` for Cloudflare D1 migrations and operations
+- Provide Cloudflare accountId, databaseId, and D1 API token credentials via environment variables
 
 ## Environment Variables
 - Commit only `.env.example` to repository

package/src/index.js

@@ -275,7 +275,7 @@ class AIRulesServer {
     this.server = new Server(
       {
         name: "@tenantegroup/ai-rules-mcp",
-        version: "1.0.0",
+        version: "1.2.0",
       },
       {
         capabilities: {