pumuki-ast-hooks 5.5.53 → 5.5.54

package/README.md

@@ -866,15 +866,6 @@ Automates the complete Git Flow cycle: commit → push → PR → merge, plus co
 
 For more details, see [MCP_SERVERS.md](./docs/MCP_SERVERS.md).
 
-#### Troubleshooting
-
-If `ai_gate_check` behaves inconsistently (stale branch name, missing rules, or intermittent transport errors), verify you are not running multiple `ast-intelligence-automation` servers across different repositories.
-
-- Prefer enabling a single MCP server for the repository you are working on.
-- Verify the active process points to this repository path:
-  - `.../ast-intelligence-hooks/scripts/hooks-system/infrastructure/mcp/ast-intelligence-automation.js`
-- If you detect multiple processes, stop the duplicates and restart your IDE/MCP servers.
-
 ---
 
 ## API Reference

package/docs/MCP_SERVERS.md

@@ -426,12 +426,26 @@ Checks if there are violations blocking work and returns `BLOCKED` or `ALLOWED`.
 ```json
 {
   "status": "ALLOWED|BLOCKED",
-  "message": "All checks passed",
+  "timestamp": "2026-01-07T22:19:30.363Z",
+  "branch": "feature/my-task",
   "violations": [],
-  "blockingReason": null
+  "warnings": [],
+  "autoFixes": [],
+  "mandatory_rules": {
+    "platforms": ["backend", "frontend", "ios", "android"],
+    "criticalRules": [],
+    "rulesLoaded": ["gold"],
+    "warning": "⚠️ AI MUST read and follow these rules before ANY code generation or modification"
+  },
+  "summary": "🚦 ALLOWED: Gate passed.",
+  "instructions": "You may proceed with user task. CRITICAL: Review mandatory_rules.criticalRules BEFORE generating ANY code."
 }
 ```
 
+**Guarantee:** `mandatory_rules` is always returned (never `null`).
+- If context/platform detection fails, it falls back to `['backend','frontend','ios','android']`.
+- If rules loading fails, it returns an object with `criticalRules: []` and an `error` field instead of `null`.
+
 **When it returns `BLOCKED`:**
 - There are CRITICAL or HIGH violations
 - Evidence is stale and must be updated first

package/docs/RELEASE_NOTES.md

@@ -52,6 +52,40 @@ npm run ast:guard:restart
 
 ---
 
+# Release Notes - v5.5.52
+
+**Release Date**: January 8, 2026
+**Type**: Patch Release
+**Compatibility**: Fully backward compatible with 5.5.x
+
+---
+
+## 🚦 MCP AI Gate: mandatory_rules always present
+
+### Problem
+`ai_gate_check` could return `mandatory_rules: null` when context/platform detection failed, forcing manual rule loading.
+
+### Solution
+`ai_gate_check` now guarantees `mandatory_rules` is always returned:
+- Fallback to `PlatformDetectionService` when `analyzeContext()` fails or returns no platforms.
+- Deterministic fallback to `backend`, `frontend`, `ios`, `android` when detection is inconclusive.
+- If rule loading fails, returns a non-null object with `criticalRules: []` and an `error` field.
+
+### Impact
+- The AI can reliably read and apply rules on every iteration.
+- Removes a class of regressions caused by missing rule payload in MCP responses.
+
+---
+
+## 📦 Installation / Upgrade
+
+```bash
+npm install --save-dev pumuki-ast-hooks@5.5.52
+npm run install-hooks
+```
+
+---
+
 # Release Notes - v5.5.24
 
 **Release Date**: January 4, 2026

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki-ast-hooks",
-  "version": "5.5.53",
+  "version": "5.5.54",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {

package/scripts/hooks-system/.audit_tmp/hook-metrics.jsonl

@@ -166,3 +166,43 @@
 {"timestamp":1767784524038,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
 {"timestamp":1767784524038,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
 {"timestamp":1767784524038,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767795854402,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767795854402,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767795854402,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767795854402,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767796412339,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767796412339,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767796412339,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767796412339,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767814882292,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767814882292,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767814882292,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767814882292,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815229484,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815229484,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767815229484,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767815229484,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815730534,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815730534,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767815730534,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767815730534,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815803186,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815803186,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767815803186,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767815803186,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815859028,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767815859028,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767815859028,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767815859028,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767818741021,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767818741022,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767818741022,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767818741022,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767818773283,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767818773283,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767818773283,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767818773283,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767819338043,"hook":"audit_logger","operation":"constructor","status":"started","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}
+{"timestamp":1767819338043,"hook":"audit_logger","operation":"ensure_dir","status":"started"}
+{"timestamp":1767819338043,"hook":"audit_logger","operation":"ensure_dir","status":"success"}
+{"timestamp":1767819338043,"hook":"audit_logger","operation":"constructor","status":"success","repoRoot":"/Users/juancarlosmerlosalbarracin/Developer/Projects/ast-intelligence-hooks/scripts/hooks-system"}

package/scripts/hooks-system/application/services/installation/McpConfigurator.js

@@ -1,10 +1,9 @@
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-const crypto = require('crypto');
-const os = require('os');
-const env = require('../../../config/env.js');
 const AuditLogger = require('../logging/AuditLogger');
+const McpServerConfigBuilder = require('./mcp/McpServerConfigBuilder');
+const McpProjectConfigWriter = require('./mcp/McpProjectConfigWriter');
+const McpGlobalConfigCleaner = require('./mcp/McpGlobalConfigCleaner');
 
 const COLORS = {
     reset: '\x1b[0m',
@@ -13,217 +12,22 @@ const COLORS = {
     cyan: '\x1b[36m'
 };
 
-function slugifyId(input) {
-    return String(input || '')
-        .trim()
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 48);
-}
-
-function computeRepoFingerprint(repoRoot) {
-    try {
-        const real = fs.realpathSync(repoRoot);
-        return crypto.createHash('sha1').update(real).digest('hex').slice(0, 8);
-    } catch (error) {
-        if (process.env.DEBUG) {
-            process.stderr.write(`[MCP] computeRepoFingerprint fallback: ${error && error.message ? error.message : String(error)}\n`);
-        }
-        return crypto.createHash('sha1').update(String(repoRoot || '')).digest('hex').slice(0, 8);
-    }
-}
-
-function computeServerIdForRepo(repoRoot) {
-    const legacyServerId = 'ast-intelligence-automation';
-    const forced = (env.get('MCP_SERVER_ID', '') || '').trim();
-    if (forced.length > 0) return forced;
-
-    const repoName = path.basename(repoRoot || process.cwd());
-    const slug = slugifyId(repoName) || 'repo';
-    const fp = computeRepoFingerprint(repoRoot);
-    return `${legacyServerId}-${slug}-${fp}`;
-}
-
 class McpConfigurator {
     constructor(targetRoot, hookSystemRoot, logger = null) {
         this.targetRoot = targetRoot;
         this.hookSystemRoot = hookSystemRoot;
         this.logger = logger;
-    }
-
-    resolveAutomationEntrypoint() {
-        // Prefer dependency-installed hook system (node_modules) to avoid requiring scripts/hooks-system in consumer repos
-        // Fallback to repo-local hook system if it exists.
-        const candidates = [
-            this.hookSystemRoot
-                ? path.join(this.hookSystemRoot, 'infrastructure', 'mcp', 'ast-intelligence-automation.js')
-                : null,
-            path.join(this.targetRoot, 'scripts', 'hooks-system', 'infrastructure', 'mcp', 'ast-intelligence-automation.js')
-        ].filter(Boolean);
-
-        for (const c of candidates) {
-            try {
-                if (fs.existsSync(c)) return c;
-            } catch (error) {
-                // Log error but continue checking other candidates
-                console.warn(`Failed to check path ${c}:`, error.message);
-            }
-        }
-
-        // Last resort: keep previous behaviour
-        return path.join(this.targetRoot, 'scripts/hooks-system/infrastructure/mcp/ast-intelligence-automation.js');
-    }
-
-    disableDuplicateServersForRepo(existing, currentServerId) {
-        if (!existing || !existing.mcpServers) return;
-
-        Object.entries(existing.mcpServers).forEach(([id, server]) => {
-            if (!server || id === currentServerId) return;
-            const envObj = server.env || {};
-            const repoRoot = envObj.REPO_ROOT;
-            if (repoRoot !== this.targetRoot) return;
-
-            const args0 = Array.isArray(server.args) ? String(server.args[0] || '') : '';
-            // Disable legacy server pointing to repo-local scripts/hooks-system when we already configure the canonical one
-            if (args0.includes('/scripts/hooks-system/') || args0.includes('\\scripts\\hooks-system\\')) {
-                server.disabled = true;
-            }
-        });
-    }
-
-    getGlobalWindsurfConfigPath() {
-        return path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+        this.serverConfigBuilder = new McpServerConfigBuilder(targetRoot, hookSystemRoot, logger);
+        this.projectWriter = new McpProjectConfigWriter(targetRoot, logger, this.logSuccess.bind(this), this.logWarning.bind(this), this.logInfo.bind(this));
+        this.globalCleaner = new McpGlobalConfigCleaner(targetRoot, logger, this.logInfo.bind(this));
     }
 
     configure() {
         if (this.logger) this.logger.info('MCP_CONFIGURATION_STARTED');
 
-        let nodePath = process.execPath;
-        if (!nodePath || !fs.existsSync(nodePath)) {
-            try {
-                nodePath = execSync('which node', { encoding: 'utf-8' }).trim();
-            } catch (error) {
-                if (process.env.DEBUG) {
-                    process.stderr.write(`[MCP] which node failed: ${error && error.message ? error.message : String(error)}\n`);
-                }
-                nodePath = 'node';
-            }
-        }
-
-        const serverId = computeServerIdForRepo(this.targetRoot);
-        const entrypoint = this.resolveAutomationEntrypoint();
-        const mcpConfig = {
-            mcpServers: {
-                [serverId]: {
-                    command: nodePath,
-                    args: [
-                        entrypoint
-                    ],
-                    env: {
-                        REPO_ROOT: this.targetRoot,
-                        AUTO_COMMIT_ENABLED: 'false',
-                        AUTO_PUSH_ENABLED: 'false',
-                        AUTO_PR_ENABLED: 'false'
-                    }
-                }
-            }
-        };
-
-        this.configureProjectScoped(mcpConfig, serverId);
-        this.cleanupGlobalConfig(serverId);
-    }
-
-    configureProjectScoped(mcpConfig, serverId) {
-        const windsurfProjectDir = path.join(this.targetRoot, '.windsurf');
-        const windsurfProjectPath = path.join(windsurfProjectDir, 'mcp.json');
-
-        try {
-            if (!fs.existsSync(windsurfProjectDir)) {
-                fs.mkdirSync(windsurfProjectDir, { recursive: true });
-            }
-
-            let finalConfig = mcpConfig;
-            if (fs.existsSync(windsurfProjectPath)) {
-                const existing = JSON.parse(fs.readFileSync(windsurfProjectPath, 'utf8'));
-                if (!existing.mcpServers) existing.mcpServers = {};
-                Object.keys(existing.mcpServers).forEach(id => {
-                    if (id.startsWith('ast-intelligence-automation-') && id !== serverId) {
-                        delete existing.mcpServers[id];
-                    }
-                });
-                existing.mcpServers[serverId] = mcpConfig.mcpServers[serverId];
-                finalConfig = existing;
-            }
-
-            fs.writeFileSync(windsurfProjectPath, JSON.stringify(finalConfig, null, 2));
-            this.logSuccess(`Configured project-scoped Windsurf MCP at ${windsurfProjectPath}`);
-            if (this.logger) this.logger.info('MCP_PROJECT_CONFIGURED', { path: windsurfProjectPath, serverId });
-        } catch (error) {
-            this.logWarning(`Failed to configure project-scoped MCP: ${error.message}`);
-            if (this.logger) this.logger.warn('MCP_PROJECT_CONFIGURE_FAILED', { error: error.message });
-        }
-
-        const cursorProjectDir = path.join(this.targetRoot, '.cursor');
-        const cursorProjectPath = path.join(cursorProjectDir, 'mcp.json');
-
-        try {
-            if (!fs.existsSync(cursorProjectDir)) {
-                fs.mkdirSync(cursorProjectDir, { recursive: true });
-            }
-
-            let finalConfig = mcpConfig;
-            if (fs.existsSync(cursorProjectPath)) {
-                const existing = JSON.parse(fs.readFileSync(cursorProjectPath, 'utf8'));
-                if (!existing.mcpServers) existing.mcpServers = {};
-                Object.keys(existing.mcpServers).forEach(id => {
-                    if (id.startsWith('ast-intelligence-automation-') && id !== serverId) {
-                        delete existing.mcpServers[id];
-                    }
-                });
-                existing.mcpServers[serverId] = mcpConfig.mcpServers[serverId];
-                finalConfig = existing;
-            }
-
-            fs.writeFileSync(cursorProjectPath, JSON.stringify(finalConfig, null, 2));
-            this.logSuccess(`Configured project-scoped Cursor MCP at ${cursorProjectPath}`);
-            if (this.logger) this.logger.info('MCP_CURSOR_CONFIGURED', { path: cursorProjectPath, serverId });
-        } catch (error) {
-            this.logWarning(`Failed to configure Cursor MCP: ${error.message}`);
-            if (this.logger) this.logger.warn('MCP_CURSOR_CONFIGURE_FAILED', { error: error.message });
-        }
-    }
-
-    cleanupGlobalConfig(currentServerId) {
-        const globalConfigPath = this.getGlobalWindsurfConfigPath();
-
-        try {
-            if (!fs.existsSync(globalConfigPath)) return;
-
-            const existing = JSON.parse(fs.readFileSync(globalConfigPath, 'utf8'));
-            if (!existing.mcpServers) return;
-
-            let modified = false;
-            Object.keys(existing.mcpServers).forEach(id => {
-                const server = existing.mcpServers[id];
-                if (!server || !server.env) return;
-
-                if (server.env.REPO_ROOT === this.targetRoot) {
-                    delete existing.mcpServers[id];
-                    modified = true;
-                    this.logInfo(`Removed ${id} from global config (now project-scoped)`);
-                }
-            });
-
-            if (modified) {
-                fs.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2));
-                if (this.logger) this.logger.info('MCP_GLOBAL_CLEANUP', { removedForRepo: this.targetRoot });
-            }
-        } catch (error) {
-            if (process.env.DEBUG) {
-                process.stderr.write(`[MCP] cleanupGlobalConfig failed: ${error.message}\n`);
-            }
-        }
+        const { serverId, mcpConfig } = this.serverConfigBuilder.build();
+        this.projectWriter.configureProjectScoped(mcpConfig, serverId);
+        this.globalCleaner.cleanupGlobalConfig(serverId);
     }
 
     detectIDEs() {

package/scripts/hooks-system/application/services/installation/mcp/McpGlobalConfigCleaner.js

@@ -0,0 +1,49 @@
+const fs = require('fs');
+const path = require('path');
+
+class McpGlobalConfigCleaner {
+    constructor(targetRoot, logger, logInfo) {
+        this.targetRoot = targetRoot;
+        this.logger = logger;
+        this.logInfo = logInfo;
+    }
+
+    cleanupGlobalConfig(currentServerId) {
+        const globalConfigPath = this.getGlobalWindsurfConfigPath();
+
+        try {
+            if (!fs.existsSync(globalConfigPath)) return;
+
+            const existing = JSON.parse(fs.readFileSync(globalConfigPath, 'utf8'));
+            if (!existing.mcpServers) return;
+
+            let modified = false;
+            Object.keys(existing.mcpServers).forEach(id => {
+                const server = existing.mcpServers[id];
+                if (!server || !server.env) return;
+
+                if (server.env.REPO_ROOT === this.targetRoot) {
+                    delete existing.mcpServers[id];
+                    modified = true;
+                    this.logInfo?.(`Removed ${id} from global config (now project-scoped)`);
+                }
+            });
+
+            if (modified) {
+                fs.writeFileSync(globalConfigPath, JSON.stringify(existing, null, 2));
+                this.logger?.info?.('MCP_GLOBAL_CLEANUP', { removedForRepo: this.targetRoot });
+            }
+        } catch (error) {
+            if (process.env.DEBUG) {
+                process.stderr.write(`[MCP] cleanupGlobalConfig failed: ${error.message}\n`);
+            }
+        }
+    }
+
+    getGlobalWindsurfConfigPath() {
+        const os = require('os');
+        return path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+    }
+}
+
+module.exports = McpGlobalConfigCleaner;

package/scripts/hooks-system/application/services/installation/mcp/McpProjectConfigWriter.js

@@ -0,0 +1,59 @@
+const fs = require('fs');
+const path = require('path');
+
+class McpProjectConfigWriter {
+    constructor(targetRoot, logger, logSuccess, logWarning, logInfo) {
+        this.targetRoot = targetRoot;
+        this.logger = logger;
+        this.logSuccess = logSuccess;
+        this.logWarning = logWarning;
+        this.logInfo = logInfo;
+    }
+
+    configureProjectScoped(mcpConfig, serverId) {
+        this.writeWindsurfConfig(mcpConfig, serverId);
+        this.writeCursorConfig(mcpConfig, serverId);
+    }
+
+    writeWindsurfConfig(mcpConfig, serverId) {
+        const windsurfProjectDir = path.join(this.targetRoot, '.windsurf');
+        const windsurfProjectPath = path.join(windsurfProjectDir, 'mcp.json');
+        this.writeProjectConfig(windsurfProjectDir, windsurfProjectPath, mcpConfig, serverId, 'Windsurf', 'MCP_PROJECT_CONFIGURED', 'MCP_PROJECT_CONFIGURE_FAILED');
+    }
+
+    writeCursorConfig(mcpConfig, serverId) {
+        const cursorProjectDir = path.join(this.targetRoot, '.cursor');
+        const cursorProjectPath = path.join(cursorProjectDir, 'mcp.json');
+        this.writeProjectConfig(cursorProjectDir, cursorProjectPath, mcpConfig, serverId, 'Cursor', 'MCP_CURSOR_CONFIGURED', 'MCP_CURSOR_CONFIGURE_FAILED');
+    }
+
+    writeProjectConfig(dir, filePath, mcpConfig, serverId, label, successEvent, errorEvent) {
+        try {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+
+            let finalConfig = mcpConfig;
+            if (fs.existsSync(filePath)) {
+                const existing = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+                if (!existing.mcpServers) existing.mcpServers = {};
+                Object.keys(existing.mcpServers).forEach(id => {
+                    if (id.startsWith('ast-intelligence-automation-') && id !== serverId) {
+                        delete existing.mcpServers[id];
+                    }
+                });
+                existing.mcpServers[serverId] = mcpConfig.mcpServers[serverId];
+                finalConfig = existing;
+            }
+
+            fs.writeFileSync(filePath, JSON.stringify(finalConfig, null, 2));
+            this.logSuccess?.(`Configured project-scoped ${label} MCP at ${filePath}`);
+            this.logger?.info?.(successEvent, { path: filePath, serverId });
+        } catch (error) {
+            this.logWarning?.(`Failed to configure ${label} MCP: ${error.message}`);
+            this.logger?.warn?.(errorEvent, { error: error.message });
+        }
+    }
+}
+
+module.exports = McpProjectConfigWriter;

package/scripts/hooks-system/application/services/installation/mcp/McpServerConfigBuilder.js

@@ -0,0 +1,103 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const crypto = require('crypto');
+const env = require('../../../../config/env.js');
+
+function slugifyId(input) {
+    return String(input || '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+}
+
+class McpServerConfigBuilder {
+    constructor(targetRoot, hookSystemRoot, logger = null) {
+        this.targetRoot = targetRoot;
+        this.hookSystemRoot = hookSystemRoot;
+        this.logger = logger;
+    }
+
+    build() {
+        const serverId = this.computeServerIdForRepo(this.targetRoot);
+        const entrypoint = this.resolveAutomationEntrypoint();
+        const nodePath = this.resolveNodeBinary();
+
+        const mcpConfig = {
+            mcpServers: {
+                [serverId]: {
+                    command: nodePath,
+                    args: [entrypoint],
+                    env: {
+                        REPO_ROOT: this.targetRoot,
+                        AUTO_COMMIT_ENABLED: 'false',
+                        AUTO_PUSH_ENABLED: 'false',
+                        AUTO_PR_ENABLED: 'false'
+                    }
+                }
+            }
+        };
+
+        return { serverId, mcpConfig };
+    }
+
+    resolveAutomationEntrypoint() {
+        const candidates = [
+            this.hookSystemRoot
+                ? path.join(this.hookSystemRoot, 'infrastructure', 'mcp', 'ast-intelligence-automation.js')
+                : null,
+            path.join(this.targetRoot, 'scripts', 'hooks-system', 'infrastructure', 'mcp', 'ast-intelligence-automation.js')
+        ].filter(Boolean);
+
+        for (const candidate of candidates) {
+            try {
+                if (fs.existsSync(candidate)) return candidate;
+            } catch (error) {
+                this.logger?.warn?.('MCP_ENTRYPOINT_CHECK_FAILED', { candidate, error: error.message });
+            }
+        }
+
+        return path.join(this.targetRoot, 'scripts/hooks-system/infrastructure/mcp/ast-intelligence-automation.js');
+    }
+
+    resolveNodeBinary() {
+        let nodePath = process.execPath;
+        if (nodePath && fs.existsSync(nodePath)) return nodePath;
+
+        try {
+            return execSync('which node', { encoding: 'utf-8' }).trim();
+        } catch (error) {
+            if (process.env.DEBUG) {
+                process.stderr.write(`[MCP] which node failed: ${error && error.message ? error.message : String(error)}\n`);
+            }
+            return 'node';
+        }
+    }
+
+    computeServerIdForRepo(repoRoot) {
+        const legacyServerId = 'ast-intelligence-automation';
+        const forced = (env.get('MCP_SERVER_ID', '') || '').trim();
+        if (forced.length > 0) return forced;
+
+        const repoName = path.basename(repoRoot || process.cwd());
+        const slug = slugifyId(repoName) || 'repo';
+        const fp = this.computeRepoFingerprint(repoRoot);
+        return `${legacyServerId}-${slug}-${fp}`;
+    }
+
+    computeRepoFingerprint(repoRoot) {
+        try {
+            const real = fs.realpathSync(repoRoot);
+            return crypto.createHash('sha1').update(real).digest('hex').slice(0, 8);
+        } catch (error) {
+            if (process.env.DEBUG) {
+                process.stderr.write(`[MCP] computeRepoFingerprint fallback: ${error && error.message ? error.message : String(error)}\n`);
+            }
+            return crypto.createHash('sha1').update(String(repoRoot || '')).digest('hex').slice(0, 8);
+        }
+    }
+}
+
+module.exports = McpServerConfigBuilder;