secufusion-mcp 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,4 @@
-# SecuFusion MCP Server
+# SecuFusion MCP Server
 
 > **Developer workflow tooling for the SecuFusion platform** — enforces zero-trust architecture standards, tracks task specs, and gates PRs with automated guardrail checks.
 
@@ -10,306 +10,661 @@
 
 ## What is this?
 
-`secufusion-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that plugs into AI coding assistants (Claude Desktop, Cursor, Cline, Antigravity, etc.) and gives them three powerful tools to enforce SecuFusion's engineering standards throughout the development lifecycle.
+`secufusion-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that plugs into AI coding assistants (Claude Desktop, Cursor, Cline, etc.) and gives them three powerful tools to enforce SecuFusion's engineering standards throughout the development lifecycle:
 
 | Tool | Phase | What it does |
 |---|---|---|
-| `manage_feature_spec` | Planning & Execution | Creates/updates a `.current-task-spec.md` blueprint for every feature |
+| `manage_feature_spec` | Planning & Execution | Creates/updates a `.current-task-spec.md` blueprint (works for single-repo or cross-repo tasks) |
 | `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` so they are never repeated |
-| `run_pre_pr_checks` | PR Handoff | Scans the codebase and gates PRs with automated guardrail validation |
+| `run_pre_pr_checks` | PR Handoff | Discovers modified microservices across the workspace and gates PRs via AST-level linters + structural checks |
 
 ---
 
 ## Installation
 
-No installation needed for teammates — just add to your MCP config and it runs via `npx`.
-
-If you want to run it from a local build (faster, fully offline):
+### Option 1 — `npx` (no install required)
 
 ```bash
-git clone https://github.com/your-org/secufusion-mcp
-cd secufusion-mcp
-npm install
-npm run build
+npx secufusion-mcp
 ```
 
----
+### Option 2 — Global install
 
-## Setup: Add to Your MCP Client
-
-### Which config should I use?
+```bash
+npm install -g secufusion-mcp
+```
 
-| Situation | Command to use |
-|---|---|
-| **You have the source on disk** (faster, offline) | `node C:\path\to\secufusion-mcp\index.js` |
-| **Anyone else / fresh machine** (auto-downloads, cached after first run) | `npx -y secufusion-mcp` |
+### Option 3 — Local project install
 
-> `npx` downloads from npm on first run (~3s) then caches it locally. Every run after that is instant and requires no network.
+```bash
+npm install --save-dev secufusion-mcp
+```
 
 ---
 
-### Antigravity IDE
+## Setup: Add to Your MCP Client
+
+### Claude Desktop
 
-Open **Customizations → MCP Servers** → edit `mcp_config.json` directly:
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or  
+`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-**If you have the source on disk:**
 ```json
 {
   "mcpServers": {
     "secufusion-mcp": {
-      "command": "node",
-      "args": ["C:\\Users\\YourName\\path\\to\\secufusion-mcp\\index.js"],
-      "type": "stdio"
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"]
     }
   }
 }
 ```
 
-**If you are a teammate (no source):**
+### Cursor
+
+Open **Settings → MCP** and add:
+
 ```json
 {
-  "mcpServers": {
-    "secufusion-mcp": {
-      "command": "npx",
-      "args": ["-y", "secufusion-mcp"],
-      "type": "stdio"
-    }
+  "secufusion-mcp": {
+    "command": "npx",
+    "args": ["-y", "secufusion-mcp"]
   }
 }
 ```
 
----
+### Cline (VS Code Extension)
 
-### Claude Desktop
+Open Cline settings → MCP Servers → Add:
 
-Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+```json
+{
+  "secufusion-mcp": {
+    "command": "npx",
+    "args": ["-y", "secufusion-mcp"],
+    "disabled": false
+  }
+}
+```
+
+### Using a local build (development)
 
 ```json
 {
-  "mcpServers": {
-    "secufusion-mcp": {
-      "command": "npx",
-      "args": ["-y", "secufusion-mcp"]
-    }
+  "secufusion-mcp": {
+    "command": "node",
+    "args": ["C:/path/to/secufusion-mcp/index.js"]
   }
 }
 ```
 
 ---
 
-### VS Code — Cline Extension
+## Tools Reference
+
+### 1. `manage_feature_spec`
+
+Creates or updates the `.current-task-spec.md` file — your single source of truth for every task. The AI reads this before writing any code.
 
-Install the **Cline** extension → click ⚙️ Settings → **MCP Servers** → **Edit Config**:
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `action` | `"create"` \| `"update"` \| `"read"` | Yes | What to do with the spec |
+| `task_description` | string | When `action=create` | Full description of the task/feature |
+| `update_content` | string | When `action=update` | Markdown lines to merge (e.g. tick checkboxes) |
+| `work_item_id` | string | No | Azure DevOps work item ID |
+| `reference_file_path` | string | No | Path to an existing source file to extract coding patterns from |
 
+**Example — Create a spec:**
+
+```
+Ask your AI assistant:
+"Start working on WI-1042: Add tenant-scoped audit log export to CSV.
+Reference file: src/services/AuditService.java"
+```
+
+The AI will call:
 ```json
 {
-  "mcpServers": {
-    "secufusion-mcp": {
-      "command": "npx",
-      "args": ["-y", "secufusion-mcp"],
-      "disabled": false
-    }
+  "action": "create",
+  "task_description": "Add tenant-scoped audit log export to CSV...",
+  "work_item_id": "1042",
+  "reference_file_path": "src/services/AuditService.java"
+}
+```
+
+This generates `.current-task-spec.md` with:
+- Task description
+- Pre-filled guardrails checklist
+- Acceptance criteria placeholders
+- Reference code snippet
+- Session log
+
+**Example — Tick off completed work:**
+
+```
+Ask: "Mark the tenantId scoping and unit tests as done in the spec."
+```
+
+The AI will call:
+```json
+{
+  "action": "update",
+  "update_content": "- [x] All DB queries / event payloads are scoped with `tenantId`\n- [x] Unit tests written / updated for new business logic"
+}
+```
+
+**Example — Read current spec:**
+
+```
+Ask: "Where did we leave off? Read the current spec."
+```
+
+```json
+{ "action": "read" }
+```
+
+---
+
+### 2. `log_rejected_pattern`
+
+Appends a rejected code pattern to `.rejected-patterns.json`. The AI checks this file implicitly before every architectural suggestion to avoid repeating past mistakes.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `pattern` | string | Yes | The bad pattern or approach |
+| `reason` | string | Yes | Why it was rejected and what to do instead |
+| `category` | enum | No | `architecture` \| `security` \| `database` \| `logging` \| `api-design` \| `testing` \| `other` |
+| `file_context` | string | No | File or area where the pattern was observed |
+
+**Example:**
+
+```
+Tell your AI: "Never use a global @Repository bean without tenantId scoping again.
+It was leaking cross-tenant data."
+```
+
+The AI will call:
+```json
+{
+  "pattern": "Injecting global @Repository bean and querying without tenantId filter",
+  "reason": "Causes cross-tenant data leakage. Always add .where(tenantId = :tenantId) or use TenantAwareRepository base class.",
+  "category": "security",
+  "file_context": "src/repositories/AuditLogRepository.java"
+}
+```
+
+This writes to `.rejected-patterns.json`:
+```json
+[
+  {
+    "id": 1,
+    "timestamp": "2026-08-26T14:35:00.000Z",
+    "category": "security",
+    "pattern": "Injecting global @Repository bean...",
+    "reason": "Causes cross-tenant data leakage...",
+    "file_context": "src/repositories/AuditLogRepository.java"
   }
+]
+```
+
+---
+
+### 3. run_pre_pr_checks
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `work_item_id` | string | Yes | Azure DevOps work item ID |
+| `root_dir` | string | No | Directory to scan (defaults to cwd) |
+| `skip_checks` | array | No | `spec_boxes`, `console_logs`, `hardcoded_urls`, `flyway_migrations` |
+
+**Guardrail checks:**
+
+| Check | Fails when |
+|---|---|
+| **SPEC** | `.current-task-spec.md` is missing or has unchecked `- [ ]` boxes |
+| **LINTING** | AST linters (ESLint, Checkstyle) fail in any discovered microservice. Fix natively, do not suppress! (Falls back to regex if no linters exist) |
+| **SECURITY** | Hardcoded IPs or `uat.*` / `prod.*` / `staging.*` URLs in source or config files |
+| **FLYWAY** | `@Entity`-annotated Java files exist but no `V*__.sql` Flyway migrations found |
+
+**Example — Run checks before PR:**
+
+```
+Ask: "Prepare the PR for work item 1042."
+```
+
+The AI will call:
+```json
+{
+  "work_item_id": "1042"
 }
 ```
 
-### VS Code — Workspace level (commit to repo)
+**✅ Passing output:**
+```
+# ✅ Pre-PR Checks PASSED — Work Item #1042
+
+✅ [SPEC] All spec checkboxes are checked.
+✅ [LOGGING] No console.log / System.out.println found.
+✅ [SECURITY] No hardcoded UAT/Prod IPs or environment URLs found.
+✅ [FLYWAY] Flyway migration coverage looks good.
+
+## PR Summary
+- Work Item: #1042
+- Spec: All acceptance criteria verified ✅
+- Ready to raise PR 🚀
+```
+
+**❌ Failing output (example):**
+```
+# ❌ Pre-PR Checks FAILED — Work Item #1042
+
+❌ [SPEC] 3 unchecked item(s) in the spec:
+   • Flyway SQL migration created for every modified JPA @Entity
+   • Unit tests written / updated for new business logic
+   • API contract updated if endpoints changed
+
+❌ [LOGGING] Found 2 prohibited log statement(s):
+   • console.log() found at src/components/AuditTable.tsx:47
+   • System.out.println() found at src/main/java/AuditService.java:112
+```
+
+---
+
+## Guardrails Summary
+
+These rules are enforced automatically — the AI will never violate them:
+
+```
+✅ All DB queries and event payloads scoped with tenantId
+✅ No console.log() or System.out.println() in any source file
+✅ No hardcoded UAT/Prod IPs or environment URLs
+✅ Every JPA @Entity change accompanied by a Flyway .sql migration
+✅ Spec must be fully checked before PR is raised
+```
+
+---
+
+## File Outputs
+
+| File | Description |
+|---|---|
+| `.current-task-spec.md` | Living task blueprint — created per feature, updated as work progresses |
+| `.rejected-patterns.json` | Cumulative log of all rejected patterns across sessions |
+
+> **Tip:** Commit both files to your repo so the entire team benefits from the shared knowledge.
+
+---
+
+## Workflow Overview
 
-Create `.vscode/mcp.json` in your project root:
+```
+┌─────────────────────────────────────────────────────┐
+│                 SecuFusion MCP Workflow              │
+├──────────────┬──────────────────────────────────────┤
+│  Phase 1     │  manage_feature_spec (action=create)  │
+│  Planning    │  → Generates .current-task-spec.md    │
+├──────────────┼──────────────────────────────────────┤
+│  Phase 2     │  manage_feature_spec (action=update)  │
+│  Execution   │  → Tick off ACs as you complete them  │
+├──────────────┼──────────────────────────────────────┤
+│  Phase 3     │  log_rejected_pattern                 │
+│  Correction  │  → Record mistakes to avoid repeat    │
+├──────────────┼──────────────────────────────────────┤
+│  Phase 4     │  run_pre_pr_checks                    │
+│  PR Handoff  │  → Must pass before raising PR        │
+└──────────────┴──────────────────────────────────────┘
+```
+
+---
 
+## Real-World Walkthrough
+
+A complete end-to-end example of what you actually type and what happens at each phase.
+
+---
+
+### Step 1 — Integrate (one-time setup)
+
+Add this to your MCP client config and restart. That's it.
+
+**Antigravity / Claude Desktop / Cline — if you have the source on disk:**
 ```json
 {
-  "servers": {
+  "mcpServers": {
     "secufusion-mcp": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "secufusion-mcp"]
+      "command": "node",
+      "args": ["C:\\Users\\YourName\\Desktop\\mcp\\secufusion-mcp\\index.js"],
+      "type": "stdio"
     }
   }
 }
 ```
 
-### Cursor
-
-Open Settings → MCP → Add:
-
+**Teammates / fresh machines — pulls from npm, cached after first run:**
 ```json
 {
-  "secufusion-mcp": {
-    "command": "npx",
-    "args": ["-y", "secufusion-mcp"]
+  "mcpServers": {
+    "secufusion-mcp": {
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"],
+      "type": "stdio"
+    }
   }
 }
 ```
 
----
+> **Why two options?** If you have the compiled `index.js` on disk, `node` starts instantly and works fully offline. Teammates who don't have the source use `npx` — it downloads from npm once (~3s), then caches it locally so every subsequent run is instant with no network needed.
 
-## How to Use It (Day-to-Day)
+---
 
-### Start a task — just paste your Azure work item
+### Step 2 — Start a new task (Planning phase)
 
-You do not need to learn any commands. Just tell your AI assistant:
+Just paste your Azure DevOps work item ID and description directly into the chat. No special syntax needed.
 
+**You type:**
 ```
 WI-2847: Add MFA enforcement for admin users on login.
 Admin users must be forced through TOTP verification before
 accessing any dashboard route. Exempt service accounts.
 ```
 
-The AI automatically calls `manage_feature_spec` and creates `.current-task-spec.md` with:
-- Your task description
-- A guardrails checklist
-- Acceptance criteria placeholders
-- A direct Azure DevOps link
-- A session log
+**The AI automatically calls `manage_feature_spec` and creates `.current-task-spec.md`:**
+```markdown
+# SecuFusion Feature Spec
+
+**Generated:** 2026-08-26T14:35:00.000Z
+**Azure DevOps Work Item:** 2847 → https://dev.azure.com/secufusion/_workitems/edit/2847
+
+## Task Description
+Add MFA enforcement for admin users on login...
+
+## Guardrails Checklist
+- [ ] All DB queries / event payloads are scoped with `tenantId`
+- [ ] No `console.log` / `System.out.println` left in source files
+- [ ] No hardcoded UAT/Prod IPs or environment URLs
+- [ ] Flyway SQL migration created for every modified JPA `@Entity`
+- [ ] Unit tests written / updated for new business logic
+- [ ] API contract updated if endpoints changed
 
-You can be brief or paste the full ticket — both work:
+## Acceptance Criteria
+- [ ] AC-1: (fill in from ticket)
+- [ ] AC-2: (fill in from ticket)
 
+## Session Log
+| 2026-08-26T14:35:00Z | Spec created |
 ```
-# Minimal
+
+You can paste as little or as much as you want:
+
+```
+# Minimal — one liner
 WI-2847: MFA for admin login with TOTP.
 
-# Full Azure paste
+# Full ticket paste — straight from Azure
 WI-2847
 Title: Add MFA enforcement for admin users
 Description: Admin users must complete TOTP verification...
 Acceptance Criteria:
   - Given admin logs in, When MFA not done, Then redirect to /mfa
   - Service accounts in GROUP_SERVICE_ACCOUNTS are exempt
+Priority: High
 ```
 
 ---
 
-### Tick off completed work
+### Step 3 — Write code normally
+
+Just code as usual. With the MCP server active, the AI automatically:
+
+- Adds `tenantId` scoping to every DB query it writes
+- Uses a proper logger (e.g., `log.info()`) — never `console.log`
+- Reads `.rejected-patterns.json` before making any architectural suggestion
+- Reminds you to create a Flyway migration if it touches a `@Entity`
+- References any `reference_file_path` you provided to match your coding style
+
+---
+
+### Step 4 — Tick off completed work (Execution phase)
+
+As you finish pieces of the feature, tell the AI:
 
 ```
-I've finished the tenantId scoping and written the unit tests. Update the spec.
+I've finished the tenantId scoping on all queries and written the unit tests.
+Update the spec.
 ```
 
-The AI checks off the matching boxes in `.current-task-spec.md`.
+The AI calls `manage_feature_spec` with `action=update` and the spec updates:
+
+```markdown
+# Before
+- [ ] All DB queries / event payloads are scoped with `tenantId`
+- [ ] Unit tests written / updated for new business logic
+
+# After
+- [x] All DB queries / event payloads are scoped with `tenantId`
+- [x] Unit tests written / updated for new business logic
+```
+
+A new row is also appended to the Session Log automatically, so you always have an audit trail of progress across sessions.
 
 ---
 
-### Record a mistake (so it never happens again)
+### Step 5 — Course correction (if the AI does something wrong)
+
+Say the AI used a hardcoded URL or proposed a pattern your team has banned:
 
 ```
-Never use hardcoded staging URLs like https://staging.secufusion.io.
-All env URLs must come from application.properties.
+Stop using hardcoded staging URLs like https://staging.secufusion.io.
+All env URLs must come from application.properties. Never hardcode them.
 ```
 
-The AI logs it to `.rejected-patterns.json` and checks it before every future suggestion.
+The AI **immediately** calls `log_rejected_pattern`:
+
+```json
+{
+  "pattern": "Hardcoded staging URL https://staging.secufusion.io in source files",
+  "reason": "Must use @Value('${app.base-url}') from application.properties. Hardcoded URLs break environment parity and expose internal topology.",
+  "category": "security",
+  "file_context": "src/services/NotificationService.java"
+}
+```
+
+This gets appended to `.rejected-patterns.json`:
+
+```json
+[
+  {
+    "id": 1,
+    "timestamp": "2026-08-26T15:10:00.000Z",
+    "category": "security",
+    "pattern": "Hardcoded staging URL https://staging.secufusion.io in source files",
+    "reason": "Must use @Value from application.properties...",
+    "file_context": "src/services/NotificationService.java"
+  }
+]
+```
+
+From this point on, the AI checks this file before every suggestion — the mistake will never be repeated, even in future sessions.
 
 ---
 
-### Run pre-PR checks
+### Step 6 — Pre-PR checks (PR Handoff phase)
+
+When you're done, say:
 
 ```
 Run pre-PR checks for work item 2847.
 ```
 
-**Pass:**
+The AI scans your entire repo and produces a report.
+
+**✅ Everything passes — ready to ship:**
 ```
+# ✅ Pre-PR Checks PASSED — Work Item #2847
+
+Scanned directory: C:\projects\secufusion-backend
+Timestamp: 2026-08-26T16:00:00.000Z
+
 ✅ [SPEC] All spec checkboxes are checked.
 ✅ [LOGGING] No console.log / System.out.println found.
-✅ [SECURITY] No hardcoded URLs found.
-✅ [FLYWAY] Migration coverage looks good.
-Ready to raise PR 🚀
+✅ [SECURITY] No hardcoded UAT/Prod IPs or environment URLs found.
+✅ [FLYWAY] Flyway migration coverage looks good.
+
+## PR Summary
+- Work Item: #2847
+- Spec: All acceptance criteria verified ✅
+- Guardrails: tenantId scoping, no debug logs, no hardcoded URLs, Flyway covered ✅
+- Ready to raise PR 🚀
+
+🚫 Rejected Patterns Reminder (1 on record)
+- [security] Hardcoded staging URL https://staging.secufusion.io in source files
 ```
 
-**Fail (fix and re-run):**
+**❌ Checks fail — you must fix before PR:**
 ```
-❌ [SPEC] 2 unchecked items:
+# ❌ Pre-PR Checks FAILED — Work Item #2847
+
+## Errors (must fix before PR)
+
+❌ [SPEC] 2 unchecked item(s) in the spec:
    • Flyway SQL migration created for every modified JPA @Entity
-   • API contract updated if endpoints changed
-❌ [LOGGING] console.log() found at src/components/AuditExport.tsx:84
+   • API contract (OpenAPI / TS types) updated if endpoints changed
+
+❌ [LINTING] 2 linter error(s) across workspace — fix natively in their respective microservices:
+   • [ESLint] apps/admin-dashboard/src/components/MfaSetup.tsx:47 — Unexpected console statement (no-console)
+   • [Checkstyle/Maven] Build failed: [ERROR] AuditService.java:[112] Line contains System.out.println
+
+## Passed
+✅ [SECURITY] No hardcoded UAT/Prod IPs or environment URLs found.
+✅ [FLYWAY] Flyway migration coverage looks good.
 ```
 
+Fix the issues, run checks again, and only raise the PR once it's fully green.
+
 ---
 
 ### Quick cheat sheet
 
-| What you want | What to say |
+| What you want to do | What to say to the AI |
 |---|---|
-| Start a task | `WI-XXXX: [description]` |
+| Start a new task | `WI-XXXX: [paste description from Azure]` |
 | Check where you left off | `Read the current spec` |
-| Mark work done | `Mark [X] as complete in the spec` |
+| Mark work as done | `Mark the tenantId scoping as complete in the spec` |
 | Record a mistake | `Never do [X] again because [Y]` |
-| Pre-PR check | `Run pre-PR checks for WI-XXXX` |
-| Resume a session | `What's left on the current task?` |
+| Gate the PR | `Run pre-PR checks for WI-XXXX` |
+| Resume after a break | `What's left on the current task?` |
+| Use a reference file | `WI-XXXX: [desc]. Reference: src/services/MyService.java` |
 
 ---
 
-## Tools Reference
+## How It Actually Works — The Invoker
 
-### 1. manage_feature_spec
+There are two layers that need to be in place for the MCP server to work automatically.
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `action` | `create` / `update` / `read` | Yes | Operation to perform |
-| `task_description` | string | When action=create | Full feature/task description |
-| `update_content` | string | When action=update | Markdown lines to merge (e.g. tick checkboxes) |
-| `work_item_id` | string | No | Azure DevOps work item ID |
-| `reference_file_path` | string | No | Existing source file to extract coding patterns from |
+### Layer 1 — `mcp_config.json` (makes tools available)
 
----
+This tells the IDE to start the MCP server process when it launches. The tools become registered and ready, but nothing calls them yet.
 
-### 2. log_rejected_pattern
+```
+IDE starts → reads mcp_config.json → spawns node index.js → tools registered
+```
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `pattern` | string | Yes | The bad pattern or approach |
-| `reason` | string | Yes | Why rejected and what to do instead |
-| `category` | enum | No | `architecture`, `security`, `database`, `logging`, `api-design`, `testing`, `other` |
-| `file_context` | string | No | File where the pattern was observed |
+### Layer 2 — `AGENTS.md` (the invoker — tells AI when to call each tool)
 
----
+Without this, the tools sit idle. The AI doesn't know when to invoke them.
+Create `.agents/AGENTS.md` in your project root:
 
-### 3. run_pre_pr_checks
+```markdown
+# SecuFusion MCP Workflow Rules
 
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `work_item_id` | string | Yes | Azure DevOps work item ID |
-| `root_dir` | string | No | Directory to scan (defaults to cwd) |
-| `skip_checks` | array | No | `spec_boxes`, `console_logs`, `hardcoded_urls`, `flyway_migrations` |
+You are an elite Senior Developer and Architect working on the SecuFusion workspace (containing multiple microservice repositories). You prioritize robust cross-service architecture, zero-trust security (tenant isolation), and flawless state management. You rely on standard AST-aware build tools (ESLint/Checkstyle) for code hygiene. You strictly follow project standards and always use the custom MCP tools provided.
 
-**Guardrail checks:**
+## Phase 1 — Planning (TRIGGER: user assigns a task or work item)
+- Do NOT write code immediately. First, call `manage_feature_spec`.
+- Determine which microservices are likely affected. Pass a `reference_file_path` to observe exact coding patterns.
+- Pass the user's requirements into `task_description` to generate the workspace-level `.current-task-spec.md` blueprint.
+- Wait for the spec to be generated before writing any code.
 
-| Check | Fails when |
-|---|---|
-| **SPEC** | `.current-task-spec.md` is missing or has unchecked `- [ ]` boxes |
-| **LOGGING** | `console.log()` in `.ts/.tsx/.js/.jsx` or `System.out.println()` in `.java` files |
-| **SECURITY** | Hardcoded IPs or `uat.*` / `prod.*` / `staging.*` URLs in source or config files |
-| **FLYWAY** | `@Entity`-annotated Java files exist but no `V*__.sql` Flyway migrations found |
+## Phase 2 — Execution (TRIGGER: as you complete work)
+- Keep the `.current-task-spec.md` file updated as your source of truth.
+- Whenever you finish a logical chunk, call `manage_feature_spec` with `update_content` to check off the `[ ]` boxes to `[x]`.
+- If you are resuming a session, always call `manage_feature_spec` with `action=read` first to know exactly where you left off.
 
----
+## Phase 3 — Course Correction (TRIGGER: user corrects you or rejects an approach)
+- Immediately call `log_rejected_pattern`.
+- Pass the bad `pattern` you used and the `reason`/correction the user provided.
+- Always check `.rejected-patterns.json` implicitly before suggesting architectural choices to ensure you never repeat past mistakes.
 
-## Files Created in Your Repo
+## Phase 4 — PR Handoff (TRIGGER: user says "prepare PR", "finish up", or "run checks")
+- Call `run_pre_pr_checks` with the Azure DevOps `work_item_id`. The tool will automatically discover all modified microservices in the workspace and run their native linters.
+- If the tool throws an error for a specific repository (e.g., missing Flyway SQL migration, or a linter failing due to console logs/bad formatting), YOU MUST navigate to that specific microservice, FIX THE ERROR in the codebase, and run the tool again until the entire workspace passes. Do not suppress linter warnings.
 
-| File | Purpose | Commit? |
-|---|---|---|
-| `.current-task-spec.md` | Living blueprint for the current task | Yes — team visibility |
-| `.rejected-patterns.json` | Cumulative log of banned patterns across sessions | Yes — shared team knowledge |
+## Guardrails (enforce always, no exceptions)
+- All DB queries and event payloads MUST be scoped with `tenantId` unless the spec explicitly notes it as a global/system operation.
+- Do not ignore linter errors. AST-level tools (ESLint, Checkstyle/Maven) are the source of truth for hygiene. Fix them natively.
+- Never hardcode UAT/Prod IPs or URLs. Use environment variables or configuration properties.
+- If you modify a JPA `@Entity` in any backend repo, you MUST create the corresponding Flyway `.sql` migration script before running PR checks.
+```
 
----
+### How it all wires together
+
+```
+mcp_config.json       →  starts the server (tools available)
+      +
+.agents/AGENTS.md     →  tells AI when to invoke each tool (the invoker)
+      ↓
+You say: "WI-1042: Add audit log export"
+      ↓
+AI reads AGENTS.md → Phase 1 triggered → calls manage_feature_spec
+      ↓
+.current-task-spec.md created in your project root
+```
+
+### Reusing across projects
 
-## Workflow
+Copy `.agents/AGENTS.md` into any project's root — the invoker follows you everywhere.
 
 ```
-Phase 1 — Planning    →  manage_feature_spec (create)  →  .current-task-spec.md generated
-Phase 2 — Execution   →  manage_feature_spec (update)  →  tick off ACs as you complete them
-Phase 3 — Correction  →  log_rejected_pattern           →  .rejected-patterns.json updated
-Phase 4 — PR Handoff  →  run_pre_pr_checks              →  must pass green before PR is raised
+ProjectA/
+  .agents/AGENTS.md   ← same file, copy it here
+
+ProjectB/
+  .agents/AGENTS.md   ← and here
+
+mcp_config.json       ← global, never changes
 ```
 
 ---
 
+## Talking to the AI — 5 Things You'll Ever Say
+
+Once both layers are in place, you interact completely naturally:
+
+| Situation | What you say |
+|---|---|
+| 🆕 New task | `WI-XXXX: [paste description from Azure]` |
+| ✅ Done a chunk | `Done with the tenantId scoping, update the spec` |
+| ❌ AI did something wrong | `Don't do X, do Y instead` |
+| 🚀 Ready for PR | `Run checks for WI-XXXX` or `Prepare PR` |
+| 🔄 Resuming after a break | `What's left?` or `Resume the current task` |
+
+**Before `AGENTS.md`:** You had to remember which tool to invoke and when.
+
+**After `AGENTS.md`:** You just describe work. The AI follows the 4-phase workflow automatically — no commands, no syntax, no manual tool calls.
+
+---
+
 ## Requirements
 
-- Node.js >= 18.0.0
+- **Node.js** >= 18.0.0
 - An MCP-compatible AI client (Antigravity, Claude Desktop, Cursor, Cline, etc.)
 
 ---
 
 ## License
 
-ISC
+ISC © SecuFusion

package/index.js

@@ -5,11 +5,11 @@
  * Provides developer-workflow tooling for the SecuFusion platform:
  *   - manage_feature_spec  : create / update task blueprints (.current-task-spec.md)
  *   - log_rejected_pattern : record bad patterns so they are never repeated (.rejected-patterns.json)
- *   - run_pre_pr_checks    : gate PRs with automated guardrail validation
+ *   - run_pre_pr_checks    : gate PRs via AST-level linters (ESLint / Maven Checkstyle) + structural checks
  *
  * Guardrails enforced:
  *   1. All DB queries and event payloads must carry tenantId.
- *   2. No console.log (TS/JS) or System.out.println (Java) in source files.
+ *   2. Code hygiene (console.log, unused vars, formatting) enforced via ESLint / Checkstyle — not regex.
  *   3. No hardcoded UAT/Prod IPs or environment URLs.
  *   4. Every modified JPA @Entity must have a matching Flyway SQL migration.
  */
@@ -18,6 +18,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import fs from "fs";
 import path from "path";
+import { execSync } from "child_process";
 // ─────────────────────────────────────────────
 //  Constants / helpers
 // ─────────────────────────────────────────────
@@ -93,7 +94,7 @@ function appendSessionLog(existing, update) {
 // ─────────────────────────────────────────────
 //  run_pre_pr_checks helpers
 // ─────────────────────────────────────────────
-const CONSOLE_LOG_PATTERNS = [
+const CONSOLE_LOG_REGEX = [
     { regex: /console\.log\s*\(/g, label: "console.log()", ext: [".ts", ".tsx", ".js", ".jsx"] },
     { regex: /System\.out\.println\s*\(/g, label: "System.out.println()", ext: [".java"] },
 ];
@@ -127,9 +128,71 @@ function checkSpecFile() {
     }
     return { unchecked, missing: false };
 }
-function checkConsoleLogs(rootDir) {
+// ── AST-level linting via ESLint (preferred over regex for JS/TS) ─────────────
+function runEslint(rootDir) {
+    // Check if ESLint is configured in the project
+    const eslintConfigs = [".eslintrc", ".eslintrc.js", ".eslintrc.json", ".eslintrc.yml",
+        ".eslintrc.yaml", "eslint.config.js", "eslint.config.mjs"];
+    const hasEslintConfig = eslintConfigs.some((f) => fs.existsSync(path.join(rootDir, f)));
+    const hasPkgEslint = (() => {
+        const pkg = readFileSafe(path.join(rootDir, "package.json"));
+        if (!pkg)
+            return false;
+        try {
+            return !!(JSON.parse(pkg).eslintConfig);
+        }
+        catch {
+            return false;
+        }
+    })();
+    if (!hasEslintConfig && !hasPkgEslint)
+        return { violations: [], available: false };
+    try {
+        execSync("npx eslint . --format json --max-warnings=0 --no-error-on-unmatched-pattern", { cwd: rootDir, stdio: "pipe" });
+        return { violations: [], available: true };
+    }
+    catch (e) {
+        const raw = e.stdout?.toString() ?? "";
+        try {
+            const results = JSON.parse(raw);
+            const violations = [];
+            for (const file of results) {
+                for (const msg of file.messages) {
+                    if (msg.severity > 0) {
+                        violations.push(`[ESLint] ${path.relative(rootDir, file.filePath)}:${msg.line} — ${msg.message}${msg.ruleId ? ` (${msg.ruleId})` : ""}`);
+                    }
+                }
+            }
+            return { violations, available: true };
+        }
+        catch {
+            // ESLint output not JSON — return raw stderr summary
+            const stderr = e.stderr?.toString() ?? "";
+            return { violations: stderr ? [`[ESLint] ${stderr.slice(0, 400)}`] : [], available: true };
+        }
+    }
+}
+// ── Maven + Checkstyle for Java/Spring projects ───────────────────────────────
+function runCheckstyle(rootDir) {
+    const hasPom = fs.existsSync(path.join(rootDir, "pom.xml"));
+    if (!hasPom)
+        return { violations: [], available: false };
+    try {
+        execSync("mvn checkstyle:check -q --no-transfer-progress", { cwd: rootDir, stdio: "pipe" });
+        return { violations: [], available: true };
+    }
+    catch (e) {
+        const output = ((e.stdout?.toString() ?? "") + (e.stderr?.toString() ?? "")).slice(0, 1200);
+        return {
+            violations: [`[Checkstyle/Maven] Build failed:\n${output}`],
+            available: true,
+        };
+    }
+}
+// ── Regex fallback — used only when no linter is configured ──────────────────
+function checkConsoleLogsRegex(rootDir) {
     const violations = [];
-    for (const { regex, label, ext } of CONSOLE_LOG_PATTERNS) {
+    for (const { regex, label, ext } of CONSOLE_LOG_REGEX) {
         const files = walkDir(rootDir, ext);
         for (const file of files) {
             const content = readFileSafe(file);
@@ -161,6 +224,28 @@ function checkHardcodedUrls(rootDir) {
     }
     return violations;
 }
+// ── Workspace / Microservice Discovery ───────────────────────────────────────
+function findProjectRoots(dir, depth = 0) {
+    if (depth > 3)
+        return []; // Limit depth to avoid scanning massive trees
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const hasPackageJson = entries.some(e => e.name === "package.json");
+    const hasPomXml = entries.some(e => e.name === "pom.xml");
+    const roots = [];
+    if (hasPackageJson || hasPomXml) {
+        roots.push(dir);
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (["node_modules", ".git", "dist", "build", "target", ".idea"].includes(entry.name))
+                continue;
+            roots.push(...findProjectRoots(path.join(dir, entry.name), depth + 1));
+        }
+    }
+    return [...new Set(roots)];
+}
 function checkFlywayMigrations(rootDir) {
     const warnings = [];
     const javaFiles = walkDir(rootDir, [".java"]);
@@ -195,10 +280,9 @@ const server = new McpServer({
     version: "1.0.0",
 });
 // ─── Tool 1: manage_feature_spec ─────────────────────────────────────────────
-server.tool("manage_feature_spec", "Create or update the .current-task-spec.md task blueprint. " +
-    "Pass `task_description` to create a new spec, or `update_content` to patch the existing one " +
-    "(e.g., checking off completed acceptance criteria). Optionally provide `reference_file_path` " +
-    "so the spec generator can observe existing coding patterns.", {
+server.tool("manage_feature_spec", "Create or update the .current-task-spec.md blueprint for the current feature. " +
+    "Use this during the Planning and Execution phases. " +
+    "Works for both single-repo and cross-repo workspace tasks.", {
     task_description: z
         .string()
         .optional()
@@ -379,10 +463,11 @@ server.tool("log_rejected_pattern", "Record a coding pattern that was rejected b
     };
 });
 // ─── Tool 3: run_pre_pr_checks ───────────────────────────────────────────────
-server.tool("run_pre_pr_checks", "Run all SecuFusion pre-PR guardrail checks against the current working directory. " +
-    "Validates: spec checkboxes, console.log/System.out.println usage, hardcoded IPs/URLs, " +
-    "and Flyway migration coverage for JPA entities. " +
-    "MUST pass (exit with no errors) before a PR is raised.", {
+server.tool("run_pre_pr_checks", "Run all SecuFusion pre-PR guardrail checks across the workspace. " +
+    "Automatically discovers modified microservices and runs their native linters (ESLint, Maven Checkstyle). " +
+    "Also validates: spec checkboxes, hardcoded IPs/URLs, and Flyway migration coverage for JPA entities. " +
+    "Linter errors must be fixed natively — do not suppress warnings to pass the gate. " +
+    "MUST pass with zero errors before a PR is raised.", {
     work_item_id: z
         .string()
         .describe("Azure DevOps work item ID to include in the PR summary."),
@@ -422,21 +507,56 @@ server.tool("run_pre_pr_checks", "Run all SecuFusion pre-PR guardrail checks aga
     else {
         warnings.push("⚠️  [SPEC] Spec checkbox check SKIPPED (manually bypassed).");
     }
-    // ── 2. Console log check ───────────────────────────────────────────────
+    // ── 2. AST-level linting (Workspace Discovery → ESLint/Checkstyle → regex fallback)
     if (!skip_checks.includes("console_logs")) {
-        const logViolations = checkConsoleLogs(scanRoot);
-        if (logViolations.length > 0) {
-            errors.push(`❌ [LOGGING] Found ${logViolations.length} prohibited log statement(s):\n` +
-                logViolations.map((v) => `   • ${v}`).join("\n"));
+        let projectRoots = findProjectRoots(scanRoot);
+        if (projectRoots.length === 0)
+            projectRoots.push(scanRoot);
+        let anyLinterAvailable = false;
+        const allLintViolations = [];
+        const usedLinters = new Set();
+        for (const pRoot of projectRoots) {
+            const eslint = runEslint(pRoot);
+            const checkstyle = runCheckstyle(pRoot);
+            if (eslint.available) {
+                anyLinterAvailable = true;
+                usedLinters.add("ESLint");
+                allLintViolations.push(...eslint.violations);
+            }
+            if (checkstyle.available) {
+                anyLinterAvailable = true;
+                usedLinters.add("Checkstyle");
+                allLintViolations.push(...checkstyle.violations);
+            }
+        }
+        if (anyLinterAvailable) {
+            // AST linters found and ran — they are the source of truth
+            if (allLintViolations.length > 0) {
+                errors.push(`❌ [LINTING] ${allLintViolations.length} linter error(s) across workspace — fix natively in their respective microservices:\n` +
+                    allLintViolations.map((v) => `   • ${v}`).join("\n"));
+            }
+            else {
+                passed.push(`✅ [LINTING] AST-level linting passed across workspace (${Array.from(usedLinters).join(" + ")}).`);
+            }
         }
         else {
-            passed.push("✅ [LOGGING] No console.log / System.out.println found.");
+            // No linters configured — fall back to regex scan with a warning
+            const regexViolations = checkConsoleLogsRegex(scanRoot);
+            if (regexViolations.length > 0) {
+                errors.push(`❌ [LOGGING] ${regexViolations.length} prohibited log statement(s) found via regex fallback\n` +
+                    `   (No ESLint/Checkstyle config detected in any workspace project — configure a linter for AST-level accuracy):\n` +
+                    regexViolations.map((v) => `   • ${v}`).join("\n"));
+            }
+            else {
+                warnings.push("⚠️  [LOGGING] No ESLint/Checkstyle config found in workspace — used regex fallback. " +
+                    "Consider adding a linter for AST-level hygiene.");
+            }
         }
     }
     else {
-        warnings.push("⚠️  [LOGGING] Console log check SKIPPED (manually bypassed).");
+        warnings.push("⚠️  [LINTING] Linter check SKIPPED (manually bypassed).");
     }
-    // ── 3. Hardcoded URL check ─────────────────────────────────────────────
+    // ── 3. Hardcoded URL check (regex — no AST equivalent needed here) ───────
     if (!skip_checks.includes("hardcoded_urls")) {
         const urlViolations = checkHardcodedUrls(scanRoot);
         if (urlViolations.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secufusion-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "SecuFusion MCP server - developer workflow tooling with guardrails",
   "main": "index.js",
@@ -17,7 +17,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "copy ..\\README.md README.md && npm run build",
+    "postpublish": "del README.md",
     "start": "node index.js",
     "dev": "tsc && node index.js"
   },