secufusion-mcp 1.0.3 → 1.0.4

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,664 @@
 
 ## 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 |
-| `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` so they are never repeated |
+| `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` so they're never repeated |
 | `run_pre_pr_checks` | PR Handoff | Scans the codebase and gates PRs with automated guardrail validation |
 
 ---
 
 ## 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
 ```
 
----
-
-## Setup: Add to Your MCP Client
+### Option 2 — Global install
 
-### 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`
 
-Install the **Cline** extension → click ⚙️ Settings → **MCP Servers** → **Edit Config**:
+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.
 
+**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`
+
+Scans your entire codebase and produces a pass/fail report. **Must pass before raising a PR.**
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `work_item_id` | string | Yes | Azure DevOps work item ID for the PR summary |
+| `root_dir` | string | No | Directory to scan (defaults to cwd) |
+| `skip_checks` | array | No | Checks to bypass: `spec_boxes`, `console_logs`, `hardcoded_urls`, `flyway_migrations` |
+
+**Checks performed:**
+
+| Check | What fails it |
+|---|---|
+| **SPEC** | `.current-task-spec.md` is missing, or has any unchecked `- [ ]` boxes |
+| **LOGGING** | Any `console.log()` in `.ts/.tsx/.js/.jsx` files, or `System.out.println()` in `.java` files |
+| **SECURITY** | Hardcoded IP addresses or `uat.*` / `prod.*` / `staging.*` URLs in source or config files |
+| **FLYWAY** | `@Entity`-annotated Java files exist but no `V*__.sql` Flyway migration files are 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
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 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.
+
+---
 
-Create `.vscode/mcp.json` in your project root:
+### 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 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
 ```
 
-The AI checks off the matching boxes in `.current-task-spec.md`.
+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:
+
+```
+Stop using hardcoded staging URLs like https://staging.secufusion.io.
+All env URLs must come from application.properties. Never hardcode them.
+```
 
+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"
+}
 ```
-Never use hardcoded staging URLs like https://staging.secufusion.io.
-All env URLs must come from application.properties.
+
+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"
+  }
+]
 ```
 
-The AI logs it to `.rejected-patterns.json` and checks it before every future suggestion.
+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
+
+❌ [LOGGING] Found 2 prohibited log statement(s):
+   • console.log() found at src/components/MfaSetup.tsx:47
+   • System.out.println() found at src/main/java/MfaService.java:112
+
+## 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 working on the SecuFusion platform.
+You have access to the `secufusion-mcp` MCP server. Follow these rules strictly.
 
-**Guardrail checks:**
+## Phase 1 — Planning (TRIGGER: user assigns a task or work item)
+- Do NOT write code immediately.
+- Call `manage_feature_spec` with `action=create`, passing the task description and `work_item_id`.
+- 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 `.current-task-spec.md` updated as your source of truth.
+- When you finish a logical chunk, call `manage_feature_spec` with `action=update`.
+- If resuming a session, always call `manage_feature_spec` with `action=read` first.
 
----
+## Phase 3 — Course Correction (TRIGGER: user corrects you or rejects an approach)
+- Immediately call `log_rejected_pattern`.
+- Pass the bad `pattern` and the `reason` the user provided.
 
-## Files Created in Your Repo
+## Phase 4 — PR Handoff (TRIGGER: user says "prepare PR", "run checks", "ready to ship")
+- Call `run_pre_pr_checks` with the `work_item_id`.
+- Fix any errors and run again until all checks are green.
 
-| 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)
+- Always scope DB queries and event payloads with `tenantId`.
+- Never use `console.log` (JS/TS) or `System.out.println` (Java).
+- Never hardcode UAT/Prod IPs or environment URLs.
+- If you modify a JPA `@Entity`, create the corresponding Flyway `.sql` migration.
+```
 
----
+### 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
+```
 
-## Workflow
+### Reusing across projects
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secufusion-mcp",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "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"
   },