secufusion-mcp 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,315 @@
+# 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.
+
+[![npm version](https://img.shields.io/npm/v/secufusion-mcp)](https://www.npmjs.com/package/secufusion-mcp)
+[![license](https://img.shields.io/npm/l/secufusion-mcp)](./LICENSE)
+[![node](https://img.shields.io/node/v/secufusion-mcp)](https://nodejs.org)
+
+---
+
+## 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.
+
+| 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 |
+| `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):
+
+```bash
+git clone https://github.com/your-org/secufusion-mcp
+cd secufusion-mcp
+npm install
+npm run build
+```
+
+---
+
+## Setup: Add to Your MCP Client
+
+### Which config should I use?
+
+| 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` |
+
+> `npx` downloads from npm on first run (~3s) then caches it locally. Every run after that is instant and requires no network.
+
+---
+
+### Antigravity IDE
+
+Open **Customizations → MCP Servers** → edit `mcp_config.json` directly:
+
+**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"
+    }
+  }
+}
+```
+
+**If you are a teammate (no source):**
+```json
+{
+  "mcpServers": {
+    "secufusion-mcp": {
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+---
+
+### Claude Desktop
+
+Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "secufusion-mcp": {
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"]
+    }
+  }
+}
+```
+
+---
+
+### VS Code — Cline Extension
+
+Install the **Cline** extension → click ⚙️ Settings → **MCP Servers** → **Edit Config**:
+
+```json
+{
+  "mcpServers": {
+    "secufusion-mcp": {
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### VS Code — Workspace level (commit to repo)
+
+Create `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "secufusion-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "secufusion-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Open Settings → MCP → Add:
+
+```json
+{
+  "secufusion-mcp": {
+    "command": "npx",
+    "args": ["-y", "secufusion-mcp"]
+  }
+}
+```
+
+---
+
+## How to Use It (Day-to-Day)
+
+### Start a task — just paste your Azure work item
+
+You do not need to learn any commands. Just tell your AI assistant:
+
+```
+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
+
+You can be brief or paste the full ticket — both work:
+
+```
+# Minimal
+WI-2847: MFA for admin login with TOTP.
+
+# Full Azure paste
+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
+```
+
+---
+
+### Tick off completed work
+
+```
+I've finished the tenantId scoping and written the unit tests. Update the spec.
+```
+
+The AI checks off the matching boxes in `.current-task-spec.md`.
+
+---
+
+### Record a mistake (so it never happens again)
+
+```
+Never use hardcoded staging URLs like https://staging.secufusion.io.
+All env URLs must come from application.properties.
+```
+
+The AI logs it to `.rejected-patterns.json` and checks it before every future suggestion.
+
+---
+
+### Run pre-PR checks
+
+```
+Run pre-PR checks for work item 2847.
+```
+
+**Pass:**
+```
+✅ [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 🚀
+```
+
+**Fail (fix and re-run):**
+```
+❌ [SPEC] 2 unchecked items:
+   • 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
+```
+
+---
+
+### Quick cheat sheet
+
+| What you want | What to say |
+|---|---|
+| Start a task | `WI-XXXX: [description]` |
+| Check where you left off | `Read the current spec` |
+| Mark work done | `Mark [X] 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?` |
+
+---
+
+## Tools Reference
+
+### 1. manage_feature_spec
+
+| 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 |
+
+---
+
+### 2. log_rejected_pattern
+
+| 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 |
+
+---
+
+### 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 |
+| **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 |
+
+---
+
+## Files Created in Your Repo
+
+| 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 |
+
+---
+
+## Workflow
+
+```
+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
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18.0.0
+- An MCP-compatible AI client (Antigravity, Claude Desktop, Cursor, Cline, etc.)
+
+---
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "secufusion-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "SecuFusion MCP server - developer workflow tooling with guardrails",
   "main": "index.js",
@@ -36,4 +36,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.0.0"
   }
-}
+}