secufusion-mcp 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +206 -58
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,36 +10,79 @@
|
|
|
10
10
|
|
|
11
11
|
## What is this?
|
|
12
12
|
|
|
13
|
-
`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
|
|
13
|
+
`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.
|
|
14
14
|
|
|
15
15
|
| Tool | Phase | What it does |
|
|
16
16
|
|---|---|---|
|
|
17
|
-
| `manage_feature_spec` | Planning & Execution | Creates/updates a `.current-task-spec.md` blueprint |
|
|
18
|
-
| `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` |
|
|
19
|
-
| `run_pre_pr_checks` | PR Handoff | Scans the codebase and gates PRs with guardrail validation |
|
|
17
|
+
| `manage_feature_spec` | Planning & Execution | Creates/updates a `.current-task-spec.md` blueprint for every feature |
|
|
18
|
+
| `log_rejected_pattern` | Course Correction | Records bad patterns to `.rejected-patterns.json` so they are never repeated |
|
|
19
|
+
| `run_pre_pr_checks` | PR Handoff | Scans the codebase and gates PRs with automated guardrail validation |
|
|
20
20
|
|
|
21
21
|
---
|
|
22
22
|
|
|
23
23
|
## Installation
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
```
|
|
25
|
+
No installation needed for teammates — just add to your MCP config and it runs via `npx`.
|
|
26
|
+
|
|
27
|
+
If you want to run it from a local build (faster, fully offline):
|
|
29
28
|
|
|
30
|
-
### Option 2 — Global install
|
|
31
29
|
```bash
|
|
32
|
-
|
|
30
|
+
git clone https://github.com/your-org/secufusion-mcp
|
|
31
|
+
cd secufusion-mcp
|
|
32
|
+
npm install
|
|
33
|
+
npm run build
|
|
33
34
|
```
|
|
34
35
|
|
|
35
36
|
---
|
|
36
37
|
|
|
37
38
|
## Setup: Add to Your MCP Client
|
|
38
39
|
|
|
40
|
+
### Which config should I use?
|
|
41
|
+
|
|
42
|
+
| Situation | Command to use |
|
|
43
|
+
|---|---|
|
|
44
|
+
| **You have the source on disk** (faster, offline) | `node C:\path\to\secufusion-mcp\index.js` |
|
|
45
|
+
| **Anyone else / fresh machine** (auto-downloads, cached after first run) | `npx -y secufusion-mcp` |
|
|
46
|
+
|
|
47
|
+
> `npx` downloads from npm on first run (~3s) then caches it locally. Every run after that is instant and requires no network.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
### Antigravity IDE
|
|
52
|
+
|
|
53
|
+
Open **Customizations → MCP Servers** → edit `mcp_config.json` directly:
|
|
54
|
+
|
|
55
|
+
**If you have the source on disk:**
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"mcpServers": {
|
|
59
|
+
"secufusion-mcp": {
|
|
60
|
+
"command": "node",
|
|
61
|
+
"args": ["C:\\Users\\YourName\\path\\to\\secufusion-mcp\\index.js"],
|
|
62
|
+
"type": "stdio"
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**If you are a teammate (no source):**
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"mcpServers": {
|
|
72
|
+
"secufusion-mcp": {
|
|
73
|
+
"command": "npx",
|
|
74
|
+
"args": ["-y", "secufusion-mcp"],
|
|
75
|
+
"type": "stdio"
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
39
83
|
### Claude Desktop
|
|
40
84
|
|
|
41
|
-
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
|
|
42
|
-
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
85
|
+
Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
|
|
43
86
|
|
|
44
87
|
```json
|
|
45
88
|
{
|
|
@@ -52,7 +95,43 @@ or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
|
52
95
|
}
|
|
53
96
|
```
|
|
54
97
|
|
|
55
|
-
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
### VS Code — Cline Extension
|
|
101
|
+
|
|
102
|
+
Install the **Cline** extension → click ⚙️ Settings → **MCP Servers** → **Edit Config**:
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"mcpServers": {
|
|
107
|
+
"secufusion-mcp": {
|
|
108
|
+
"command": "npx",
|
|
109
|
+
"args": ["-y", "secufusion-mcp"],
|
|
110
|
+
"disabled": false
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### VS Code — Workspace level (commit to repo)
|
|
117
|
+
|
|
118
|
+
Create `.vscode/mcp.json` in your project root:
|
|
119
|
+
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"servers": {
|
|
123
|
+
"secufusion-mcp": {
|
|
124
|
+
"type": "stdio",
|
|
125
|
+
"command": "npx",
|
|
126
|
+
"args": ["-y", "secufusion-mcp"]
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Cursor
|
|
133
|
+
|
|
134
|
+
Open Settings → MCP → Add:
|
|
56
135
|
|
|
57
136
|
```json
|
|
58
137
|
{
|
|
@@ -65,92 +144,161 @@ or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
|
65
144
|
|
|
66
145
|
---
|
|
67
146
|
|
|
68
|
-
##
|
|
147
|
+
## How to Use It (Day-to-Day)
|
|
69
148
|
|
|
70
|
-
###
|
|
149
|
+
### Start a task — just paste your Azure work item
|
|
71
150
|
|
|
72
|
-
|
|
151
|
+
You do not need to learn any commands. Just tell your AI assistant:
|
|
73
152
|
|
|
74
|
-
|
|
153
|
+
```
|
|
154
|
+
WI-2847: Add MFA enforcement for admin users on login.
|
|
155
|
+
Admin users must be forced through TOTP verification before
|
|
156
|
+
accessing any dashboard route. Exempt service accounts.
|
|
157
|
+
```
|
|
75
158
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
159
|
+
The AI automatically calls `manage_feature_spec` and creates `.current-task-spec.md` with:
|
|
160
|
+
- Your task description
|
|
161
|
+
- A guardrails checklist
|
|
162
|
+
- Acceptance criteria placeholders
|
|
163
|
+
- A direct Azure DevOps link
|
|
164
|
+
- A session log
|
|
165
|
+
|
|
166
|
+
You can be brief or paste the full ticket — both work:
|
|
83
167
|
|
|
84
|
-
**Example:**
|
|
85
168
|
```
|
|
86
|
-
|
|
87
|
-
|
|
169
|
+
# Minimal
|
|
170
|
+
WI-2847: MFA for admin login with TOTP.
|
|
171
|
+
|
|
172
|
+
# Full Azure paste
|
|
173
|
+
WI-2847
|
|
174
|
+
Title: Add MFA enforcement for admin users
|
|
175
|
+
Description: Admin users must complete TOTP verification...
|
|
176
|
+
Acceptance Criteria:
|
|
177
|
+
- Given admin logs in, When MFA not done, Then redirect to /mfa
|
|
178
|
+
- Service accounts in GROUP_SERVICE_ACCOUNTS are exempt
|
|
88
179
|
```
|
|
89
180
|
|
|
90
181
|
---
|
|
91
182
|
|
|
92
|
-
###
|
|
183
|
+
### Tick off completed work
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
I've finished the tenantId scoping and written the unit tests. Update the spec.
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The AI checks off the matching boxes in `.current-task-spec.md`.
|
|
190
|
+
|
|
191
|
+
---
|
|
192
|
+
|
|
193
|
+
### Record a mistake (so it never happens again)
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
Never use hardcoded staging URLs like https://staging.secufusion.io.
|
|
197
|
+
All env URLs must come from application.properties.
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
The AI logs it to `.rejected-patterns.json` and checks it before every future suggestion.
|
|
93
201
|
|
|
94
|
-
|
|
202
|
+
---
|
|
95
203
|
|
|
96
|
-
|
|
204
|
+
### Run pre-PR checks
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
Run pre-PR checks for work item 2847.
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
**Pass:**
|
|
211
|
+
```
|
|
212
|
+
✅ [SPEC] All spec checkboxes are checked.
|
|
213
|
+
✅ [LOGGING] No console.log / System.out.println found.
|
|
214
|
+
✅ [SECURITY] No hardcoded URLs found.
|
|
215
|
+
✅ [FLYWAY] Migration coverage looks good.
|
|
216
|
+
Ready to raise PR 🚀
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
**Fail (fix and re-run):**
|
|
220
|
+
```
|
|
221
|
+
❌ [SPEC] 2 unchecked items:
|
|
222
|
+
• Flyway SQL migration created for every modified JPA @Entity
|
|
223
|
+
• API contract updated if endpoints changed
|
|
224
|
+
❌ [LOGGING] console.log() found at src/components/AuditExport.tsx:84
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
### Quick cheat sheet
|
|
230
|
+
|
|
231
|
+
| What you want | What to say |
|
|
232
|
+
|---|---|
|
|
233
|
+
| Start a task | `WI-XXXX: [description]` |
|
|
234
|
+
| Check where you left off | `Read the current spec` |
|
|
235
|
+
| Mark work done | `Mark [X] as complete in the spec` |
|
|
236
|
+
| Record a mistake | `Never do [X] again because [Y]` |
|
|
237
|
+
| Pre-PR check | `Run pre-PR checks for WI-XXXX` |
|
|
238
|
+
| Resume a session | `What's left on the current task?` |
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## Tools Reference
|
|
243
|
+
|
|
244
|
+
### 1. manage_feature_spec
|
|
245
|
+
|
|
246
|
+
| Parameter | Type | Required | Description |
|
|
247
|
+
|---|---|---|---|
|
|
248
|
+
| `action` | `create` / `update` / `read` | Yes | Operation to perform |
|
|
249
|
+
| `task_description` | string | When action=create | Full feature/task description |
|
|
250
|
+
| `update_content` | string | When action=update | Markdown lines to merge (e.g. tick checkboxes) |
|
|
251
|
+
| `work_item_id` | string | No | Azure DevOps work item ID |
|
|
252
|
+
| `reference_file_path` | string | No | Existing source file to extract coding patterns from |
|
|
253
|
+
|
|
254
|
+
---
|
|
255
|
+
|
|
256
|
+
### 2. log_rejected_pattern
|
|
97
257
|
|
|
98
258
|
| Parameter | Type | Required | Description |
|
|
99
259
|
|---|---|---|---|
|
|
100
260
|
| `pattern` | string | Yes | The bad pattern or approach |
|
|
101
261
|
| `reason` | string | Yes | Why rejected and what to do instead |
|
|
102
|
-
| `category` | enum | No | architecture
|
|
262
|
+
| `category` | enum | No | `architecture`, `security`, `database`, `logging`, `api-design`, `testing`, `other` |
|
|
103
263
|
| `file_context` | string | No | File where the pattern was observed |
|
|
104
264
|
|
|
105
|
-
**Example:**
|
|
106
|
-
```
|
|
107
|
-
"Never use a global @Repository without tenantId scoping — it leaks cross-tenant data."
|
|
108
|
-
```
|
|
109
|
-
|
|
110
265
|
---
|
|
111
266
|
|
|
112
267
|
### 3. run_pre_pr_checks
|
|
113
268
|
|
|
114
|
-
Scans the codebase and produces a pass/fail report. Must pass before raising a PR.
|
|
115
|
-
|
|
116
|
-
**Parameters:**
|
|
117
|
-
|
|
118
269
|
| Parameter | Type | Required | Description |
|
|
119
270
|
|---|---|---|---|
|
|
120
271
|
| `work_item_id` | string | Yes | Azure DevOps work item ID |
|
|
121
272
|
| `root_dir` | string | No | Directory to scan (defaults to cwd) |
|
|
122
273
|
| `skip_checks` | array | No | `spec_boxes`, `console_logs`, `hardcoded_urls`, `flyway_migrations` |
|
|
123
274
|
|
|
124
|
-
**
|
|
275
|
+
**Guardrail checks:**
|
|
125
276
|
|
|
126
277
|
| Check | Fails when |
|
|
127
278
|
|---|---|
|
|
128
|
-
| SPEC |
|
|
129
|
-
| LOGGING | console.log() or System.out.println()
|
|
130
|
-
| SECURITY | Hardcoded IPs or uat/prod/staging URLs
|
|
131
|
-
| FLYWAY |
|
|
279
|
+
| **SPEC** | `.current-task-spec.md` is missing or has unchecked `- [ ]` boxes |
|
|
280
|
+
| **LOGGING** | `console.log()` in `.ts/.tsx/.js/.jsx` or `System.out.println()` in `.java` files |
|
|
281
|
+
| **SECURITY** | Hardcoded IPs or `uat.*` / `prod.*` / `staging.*` URLs in source or config files |
|
|
282
|
+
| **FLYWAY** | `@Entity`-annotated Java files exist but no `V*__.sql` Flyway migrations found |
|
|
132
283
|
|
|
133
284
|
---
|
|
134
285
|
|
|
135
|
-
##
|
|
286
|
+
## Files Created in Your Repo
|
|
136
287
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
Every JPA @Entity change requires a Flyway .sql migration
|
|
142
|
-
Spec must be fully checked before PR is raised
|
|
143
|
-
```
|
|
288
|
+
| File | Purpose | Commit? |
|
|
289
|
+
|---|---|---|
|
|
290
|
+
| `.current-task-spec.md` | Living blueprint for the current task | Yes — team visibility |
|
|
291
|
+
| `.rejected-patterns.json` | Cumulative log of banned patterns across sessions | Yes — shared team knowledge |
|
|
144
292
|
|
|
145
293
|
---
|
|
146
294
|
|
|
147
295
|
## Workflow
|
|
148
296
|
|
|
149
297
|
```
|
|
150
|
-
Phase 1 — Planning
|
|
151
|
-
Phase 2 — Execution
|
|
152
|
-
Phase 3 — Correction
|
|
153
|
-
Phase 4 — PR Handoff
|
|
298
|
+
Phase 1 — Planning → manage_feature_spec (create) → .current-task-spec.md generated
|
|
299
|
+
Phase 2 — Execution → manage_feature_spec (update) → tick off ACs as you complete them
|
|
300
|
+
Phase 3 — Correction → log_rejected_pattern → .rejected-patterns.json updated
|
|
301
|
+
Phase 4 — PR Handoff → run_pre_pr_checks → must pass green before PR is raised
|
|
154
302
|
```
|
|
155
303
|
|
|
156
304
|
---
|
|
@@ -158,7 +306,7 @@ Phase 4 — PR Handoff : run_pre_pr_checks → must pass to ship
|
|
|
158
306
|
## Requirements
|
|
159
307
|
|
|
160
308
|
- Node.js >= 18.0.0
|
|
161
|
-
- An MCP-compatible AI client (Claude Desktop, Cursor, Cline, etc.)
|
|
309
|
+
- An MCP-compatible AI client (Antigravity, Claude Desktop, Cursor, Cline, etc.)
|
|
162
310
|
|
|
163
311
|
---
|
|
164
312
|
|