@perfai/mcp 1.0.24 → 1.0.25
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 +242 -255
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,352 +1,339 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @perfai/mcp
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A Model Context Protocol (MCP) server that brings **PerfAI Security, Design & Quality Analysis** directly into your AI coding assistant. Authenticate once, then list and triage API security issues, generate AI-powered fix prompts, and view detailed dashboards — all from within Claude, Cursor, VS Code, Windsurf, Zed, or any MCP-compatible client.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
Install globally (CLI):
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
npm install -g perfai-mcp-server
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
Or add as a project dependency:
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
npm install perfai-mcp-server --save-dev
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## ⚙️ Quick Setup
|
|
5
|
+
---
|
|
20
6
|
|
|
21
|
-
|
|
7
|
+
## 📦 Installation
|
|
22
8
|
|
|
23
9
|
```bash
|
|
24
|
-
perfai
|
|
10
|
+
npx -y @perfai/mcp@latest
|
|
25
11
|
```
|
|
26
12
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
## 🚀 Run (CLI)
|
|
13
|
+
Or install globally:
|
|
30
14
|
|
|
31
15
|
```bash
|
|
32
|
-
perfai
|
|
16
|
+
npm install -g @perfai/mcp
|
|
33
17
|
```
|
|
34
18
|
|
|
35
|
-
|
|
19
|
+
---
|
|
36
20
|
|
|
37
|
-
|
|
21
|
+
## ⚡ Quick Start — One-Line Setup
|
|
38
22
|
|
|
39
|
-
|
|
23
|
+
### Claude (Desktop or CLI)
|
|
40
24
|
|
|
41
25
|
```bash
|
|
42
|
-
|
|
43
|
-
set PERFAI_PASSWORD=your-password
|
|
26
|
+
claude mcp add perfai-mcp -e PERFAI_USERNAME=your@email.com -e PERFAI_PASSWORD=yourpassword -- npx -y @perfai/mcp@latest
|
|
44
27
|
```
|
|
45
28
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
### Kubernetes (K8s Secrets)
|
|
49
|
-
|
|
50
|
-
Store credentials in a Kubernetes `Secret` and inject them as environment variables (recommended for clusters).
|
|
29
|
+
That single command registers the server, sets credentials, and connects it to Claude. No config file editing needed.
|
|
51
30
|
|
|
52
|
-
```yaml
|
|
53
|
-
apiVersion: v1
|
|
54
|
-
kind: Secret
|
|
55
|
-
metadata:
|
|
56
|
-
name: perfai-mcp-secrets
|
|
57
|
-
type: Opaque
|
|
58
|
-
stringData:
|
|
59
|
-
PERFAI_USERNAME: "<perfai-username>"
|
|
60
|
-
PERFAI_PASSWORD: "<perfai-password>"
|
|
61
|
-
# Optional (only if used in your deployment)
|
|
62
|
-
PERFAI_DASHBOARD_API_AUTH: "Authorization: Basic <base64(user:pass)>"
|
|
63
|
-
PERFAI_AUTH0_CLIENT_SECRET: "<auth0-client-secret>"
|
|
64
31
|
---
|
|
65
|
-
apiVersion: apps/v1
|
|
66
|
-
kind: Deployment
|
|
67
|
-
metadata:
|
|
68
|
-
name: perfai-mcp
|
|
69
|
-
spec:
|
|
70
|
-
template:
|
|
71
|
-
spec:
|
|
72
|
-
containers:
|
|
73
|
-
- name: perfai-mcp
|
|
74
|
-
envFrom:
|
|
75
|
-
- secretRef:
|
|
76
|
-
name: perfai-mcp-secrets
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
## 🧩 Programmatic Usage
|
|
80
|
-
|
|
81
|
-
```ts
|
|
82
|
-
import { startServer, authManager, AuthenticationManager } from '@perfai/mcp-server';
|
|
83
|
-
|
|
84
|
-
// Start server (returns a promise)
|
|
85
|
-
await startServer();
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
All logging is written to stderr to remain MCP-compatible.
|
|
89
|
-
|
|
90
|
-
## 🔐 Authentication & Security
|
|
91
32
|
|
|
92
|
-
|
|
33
|
+
## 🔧 MCP Client Configuration
|
|
93
34
|
|
|
94
|
-
|
|
95
|
-
- **🌐 Zero Configuration**: No redirect URLs needed - works everywhere
|
|
96
|
-
- **📱 Device Code Flow**: Simple browser authentication like Netflix/GitHub
|
|
97
|
-
- **🛡️ Session Management**: Secure token storage and automatic validation
|
|
98
|
-
- **🔄 Auto-Detection**: Server automatically detects authentication completion
|
|
99
|
-
- **👥 Multi-User Support**: Isolated sessions for different users
|
|
35
|
+
### Claude Desktop
|
|
100
36
|
|
|
101
|
-
|
|
37
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
102
38
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
- **📋 `list_apps`**: List all APPs in table format (Seq, App Name, Label) - shows unique instances
|
|
117
|
-
- **🎯 `select_app`**: Select an APP by sequence number from list_apps table
|
|
118
|
-
|
|
119
|
-
#### 🔒 **Security Analysis**
|
|
120
|
-
- **🔒 `show_security_issues`**: List security vulnerabilities by organization
|
|
121
|
-
- Shows 20 issues at a time with pagination
|
|
122
|
-
- Sorted by severity (Critical → High → Medium → Low)
|
|
123
|
-
- Displays CVSS scores for each issue
|
|
124
|
-
- Supports pagination, search, and severity filtering
|
|
125
|
-
- **🤖 `ai_fix_security_issue`**: Generate AI-powered remediation prompts
|
|
126
|
-
- Works with sequence numbers, issue IDs, or descriptive text
|
|
127
|
-
- **📋 `show_fixed_issues`**: View all AI-fixed security issues in current session
|
|
128
|
-
|
|
129
|
-
#### 🚀 **Security Testing**
|
|
130
|
-
- **🚀 `run_security_test`**: Execute comprehensive security analysis using Docker
|
|
131
|
-
- Requires OpenAPI spec URL and local API base path
|
|
132
|
-
- Uses PerfAI's Docker-based security testing engine
|
|
133
|
-
- Waits 40 seconds for system to process security issues
|
|
134
|
-
- **🔍 `check_security_fixes`**: Check which previously fixed security issues were actually resolved
|
|
135
|
-
- Independent tool that can be run anytime
|
|
136
|
-
- Shows comparison table of fixed vs still existing issues
|
|
137
|
-
- Clears fixed issues from session after comparison
|
|
138
|
-
|
|
139
|
-
## 🚀 Quick Start (Local Development)
|
|
140
|
-
|
|
141
|
-
### 1. Install Dependencies
|
|
142
|
-
```bash
|
|
143
|
-
npm install
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
### 2. Build the Project
|
|
147
|
-
```bash
|
|
148
|
-
npm run build
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"mcpServers": {
|
|
42
|
+
"perfai-mcp": {
|
|
43
|
+
"command": "npx",
|
|
44
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
45
|
+
"env": {
|
|
46
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
47
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
149
52
|
```
|
|
150
53
|
|
|
151
|
-
###
|
|
152
|
-
```bash
|
|
153
|
-
npm start
|
|
154
|
-
```
|
|
54
|
+
### Cursor
|
|
155
55
|
|
|
156
|
-
|
|
56
|
+
**Project-level** — create `.cursor/mcp.json` in your project root:
|
|
157
57
|
|
|
158
|
-
```
|
|
159
|
-
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"mcpServers": {
|
|
61
|
+
"perfai-mcp": {
|
|
62
|
+
"command": "npx",
|
|
63
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
64
|
+
"env": {
|
|
65
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
66
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
160
71
|
```
|
|
161
72
|
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
npm run mcp:inspect
|
|
165
|
-
```
|
|
73
|
+
**Global** — add the same block to `~/.cursor/mcp.json`.
|
|
166
74
|
|
|
167
|
-
|
|
75
|
+
### VS Code (Copilot Agent Mode)
|
|
76
|
+
|
|
77
|
+
Create `.vscode/mcp.json` in your workspace:
|
|
168
78
|
|
|
169
|
-
### For Cursor
|
|
170
|
-
Add to your `cursor_mcp_config.json`:
|
|
171
79
|
```json
|
|
172
80
|
{
|
|
173
|
-
"
|
|
81
|
+
"servers": {
|
|
174
82
|
"perfai-mcp": {
|
|
175
83
|
"type": "stdio",
|
|
176
84
|
"command": "npx",
|
|
177
|
-
"args": ["perfai
|
|
85
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
178
86
|
"env": {
|
|
179
|
-
"PERFAI_USERNAME": "your
|
|
180
|
-
"PERFAI_PASSWORD": "
|
|
87
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
88
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
181
89
|
}
|
|
182
90
|
}
|
|
183
91
|
}
|
|
184
92
|
}
|
|
185
93
|
```
|
|
186
94
|
|
|
187
|
-
|
|
188
|
-
|
|
95
|
+
> Note: VS Code uses the `"servers"` key (not `"mcpServers"`).
|
|
96
|
+
|
|
97
|
+
### Windsurf
|
|
98
|
+
|
|
99
|
+
Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
100
|
+
|
|
189
101
|
```json
|
|
190
102
|
{
|
|
191
103
|
"mcpServers": {
|
|
192
104
|
"perfai-mcp": {
|
|
193
|
-
"type": "stdio",
|
|
194
105
|
"command": "npx",
|
|
195
|
-
"args": ["perfai
|
|
106
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
196
107
|
"env": {
|
|
197
|
-
"PERFAI_USERNAME": "your
|
|
198
|
-
"PERFAI_PASSWORD": "
|
|
108
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
109
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
199
110
|
}
|
|
200
111
|
}
|
|
201
112
|
}
|
|
202
113
|
}
|
|
203
114
|
```
|
|
204
115
|
|
|
205
|
-
|
|
116
|
+
### Zed
|
|
117
|
+
|
|
118
|
+
Add to your Zed `settings.json`:
|
|
206
119
|
|
|
207
|
-
|
|
120
|
+
```json
|
|
121
|
+
{
|
|
122
|
+
"context_servers": {
|
|
123
|
+
"perfai-mcp": {
|
|
124
|
+
"command": {
|
|
125
|
+
"path": "npx",
|
|
126
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
127
|
+
"env": {
|
|
128
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
129
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
130
|
+
}
|
|
131
|
+
},
|
|
132
|
+
"settings": {}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
208
137
|
|
|
209
|
-
|
|
210
|
-
2. **Login**: Run `login` tool:
|
|
211
|
-
- ✅ Browser automatically opens to PerfAI Auth0 device page
|
|
212
|
-
- 📱 You'll see a simple code (e.g., `BDJK-WHNZ`)
|
|
213
|
-
- 🔐 Enter the code in browser and complete authentication
|
|
214
|
-
- 🔄 Server automatically detects completion
|
|
215
|
-
3. **Verify**: Run `auth_status` → Shows user info and "Authenticated"
|
|
216
|
-
4. **Use Protected Tools**: All 9 protected tools now available
|
|
217
|
-
5. **Logout**: Run `logout` → Returns to 2 public tools only
|
|
138
|
+
### Any other MCP client
|
|
218
139
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"command": "npx",
|
|
143
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
144
|
+
"env": {
|
|
145
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
146
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
224
150
|
|
|
225
|
-
|
|
151
|
+
---
|
|
226
152
|
|
|
227
|
-
|
|
228
|
-
```bash
|
|
229
|
-
# List available organizations
|
|
230
|
-
manage_organizations {"action": "list"}
|
|
153
|
+
## 🔐 Authentication
|
|
231
154
|
|
|
232
|
-
|
|
233
|
-
manage_organizations {"action": "select", "org_id": "your-org-id"}
|
|
155
|
+
Run the `login` tool from your AI assistant to open a browser-based Auth0 login. After authenticating, all protected tools become available automatically.
|
|
234
156
|
|
|
235
|
-
|
|
236
|
-
|
|
157
|
+
```
|
|
158
|
+
login # opens browser → authenticate → done
|
|
159
|
+
auth_status # verify you're authenticated
|
|
160
|
+
logout # clear session
|
|
237
161
|
```
|
|
238
162
|
|
|
239
|
-
|
|
240
|
-
```bash
|
|
241
|
-
# List security issues
|
|
242
|
-
show_security_issues {"limit": 20}
|
|
163
|
+
---
|
|
243
164
|
|
|
244
|
-
|
|
245
|
-
show_security_issues {"search": "myapp", "limit": 10}
|
|
165
|
+
## 🛠️ Available Tools
|
|
246
166
|
|
|
247
|
-
|
|
248
|
-
|
|
167
|
+
### 🔓 Public (no authentication required)
|
|
168
|
+
|
|
169
|
+
| Tool | Description |
|
|
170
|
+
|------|-------------|
|
|
171
|
+
| `login` | Authenticate with PerfAI via Auth0 OAuth. Opens browser. |
|
|
172
|
+
| `auth_status` | Check current authentication status and user info. |
|
|
173
|
+
|
|
174
|
+
### 🔒 Protected (authentication required)
|
|
175
|
+
|
|
176
|
+
#### User & Session
|
|
177
|
+
| Tool | Description |
|
|
178
|
+
|------|-------------|
|
|
179
|
+
| `user_info` | Get detailed information about the authenticated user. |
|
|
180
|
+
| `logout` | Clear authentication session. |
|
|
181
|
+
| `setup` | Auto-configure org and app with default values. |
|
|
182
|
+
|
|
183
|
+
#### Organization & App Management
|
|
184
|
+
| Tool | Parameters | Description |
|
|
185
|
+
|------|------------|-------------|
|
|
186
|
+
| `manage_organizations` | `action` (list/select/refresh), `sequence`, `org_id` | List orgs with sequence numbers, select by number or ID. |
|
|
187
|
+
| `list_apps` | `search`, `environment`, `page`, `limit` | List all APPs with optional filters and pagination. |
|
|
188
|
+
| `select_app` | `sequence`, `name_or_label`, `app_id` | Select an APP by sequence number, partial name/label, or exact ID. |
|
|
189
|
+
|
|
190
|
+
#### Issue Summary
|
|
191
|
+
| Tool | Description |
|
|
192
|
+
|------|-------------|
|
|
193
|
+
| `summarize_issues` | Full dashboard for the selected APP — security risk, design issues, quality issues, attack surface, bug bounty savings, and coverage. |
|
|
194
|
+
|
|
195
|
+
#### Security Issues
|
|
196
|
+
| Tool | Parameters | Description |
|
|
197
|
+
|------|------------|-------------|
|
|
198
|
+
| `show_security_issues` | `limit`, `severities[]`, `status`, `sort_by`, `sort_order`, `search`, `cursor` | List security vulnerabilities with filters. |
|
|
199
|
+
| `ai_fix_security_issue` | `issue_id` (sequence #, ID, or description) | Generate an AI-powered fix prompt for a security issue. |
|
|
200
|
+
| `check_security_fixes` | `wait_seconds` | Check which previously fixed issues were actually resolved. |
|
|
201
|
+
|
|
202
|
+
#### Design Issues
|
|
203
|
+
| Tool | Parameters | Description |
|
|
204
|
+
|------|------------|-------------|
|
|
205
|
+
| `show_design_issues` | `limit`, `status`, `sort_by`, `sort_order`, `search`, `cursor` | List API design issues with filters. |
|
|
206
|
+
| `ai_fix_design_issue` | `issue_id` | Generate an AI-powered fix prompt for a design issue. |
|
|
207
|
+
| `check_design_fixes` | `wait_seconds` | Check which design fixes were actually resolved. |
|
|
208
|
+
|
|
209
|
+
#### Quality / Spec Validation Issues
|
|
210
|
+
| Tool | Parameters | Description |
|
|
211
|
+
|------|------------|-------------|
|
|
212
|
+
| `show_quality_issues` | `limit`, `sort_by`, `sort_order`, `search`, `cursor` | List spec validation issues. |
|
|
213
|
+
| `ai_fix_quality_issue` | `issue_id` | Generate an AI-powered fix prompt for a quality issue. |
|
|
214
|
+
| `check_quality_fixes` | `wait_seconds` | Check which quality fixes were actually resolved. |
|
|
215
|
+
|
|
216
|
+
#### Session State
|
|
217
|
+
| Tool | Description |
|
|
218
|
+
|------|-------------|
|
|
219
|
+
| `show_fixed_issues` | Show all AI-fixed issues from the current session. |
|
|
249
220
|
|
|
250
|
-
|
|
251
|
-
ai_fix_security_issue {"issue_id": "issue-id-here"}
|
|
221
|
+
---
|
|
252
222
|
|
|
253
|
-
|
|
254
|
-
ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • MULTIPLE /store"}
|
|
223
|
+
## 💡 Typical Workflow
|
|
255
224
|
|
|
256
|
-
|
|
257
|
-
|
|
225
|
+
```
|
|
226
|
+
1. login # authenticate
|
|
227
|
+
2. manage_organizations {"action": "list"} # see your orgs
|
|
228
|
+
3. manage_organizations {"action": "select", "sequence": 1}
|
|
229
|
+
4. list_apps {"search": "payments"} # find your app
|
|
230
|
+
5. select_app {"sequence": 2} # or by name: {"name_or_label": "payments"}
|
|
231
|
+
6. summarize_issues # dashboard overview
|
|
232
|
+
7. show_security_issues {"severities": ["Critical", "High"]}
|
|
233
|
+
8. ai_fix_security_issue {"issue_id": "3"} # fix issue #3
|
|
234
|
+
9. show_design_issues {"status": "Open"}
|
|
235
|
+
10. show_quality_issues {}
|
|
258
236
|
```
|
|
259
237
|
|
|
260
|
-
|
|
261
|
-
```bash
|
|
262
|
-
# List available APPs (shows table with sequence numbers)
|
|
263
|
-
list_apps {}
|
|
238
|
+
---
|
|
264
239
|
|
|
265
|
-
|
|
266
|
-
select_app {"sequence": 1}
|
|
267
|
-
```
|
|
240
|
+
## 📋 Tool Examples
|
|
268
241
|
|
|
269
|
-
###
|
|
270
|
-
```bash
|
|
271
|
-
# Run comprehensive security test (waits 40 seconds for processing)
|
|
272
|
-
run_security_test {
|
|
273
|
-
"spec_url": "http://localhost:3000/swagger.json",
|
|
274
|
-
"local_base_path": "http://localhost:3000"
|
|
275
|
-
}
|
|
242
|
+
### Organization & App Selection
|
|
276
243
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
244
|
+
```jsonc
|
|
245
|
+
// List organizations with sequence numbers
|
|
246
|
+
manage_organizations {"action": "list"}
|
|
280
247
|
|
|
281
|
-
|
|
248
|
+
// Select org by sequence number (preferred)
|
|
249
|
+
manage_organizations {"action": "select", "sequence": 2}
|
|
282
250
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
npm run dev
|
|
286
|
-
```
|
|
251
|
+
// List apps — filter by name or environment
|
|
252
|
+
list_apps {"search": "checkout", "environment": "production", "page": 1, "limit": 50}
|
|
287
253
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
- `npm run dev` – Watch mode for development
|
|
291
|
-
- `npm start` – Start the MCP server
|
|
292
|
-
- `npm run mcp:inspect` – Start MCP Inspector for testing
|
|
254
|
+
// Select app by partial name
|
|
255
|
+
select_app {"name_or_label": "checkout"}
|
|
293
256
|
|
|
294
|
-
|
|
257
|
+
// Select app by sequence number from list_apps
|
|
258
|
+
select_app {"sequence": 4}
|
|
295
259
|
```
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
├── vscode_mcp_config.json # VS Code MCP client config
|
|
303
|
-
└── README.md # This file
|
|
260
|
+
|
|
261
|
+
### Summary Dashboard
|
|
262
|
+
|
|
263
|
+
```jsonc
|
|
264
|
+
// Full dashboard: security + design + quality + attack surface
|
|
265
|
+
summarize_issues {}
|
|
304
266
|
```
|
|
305
267
|
|
|
306
|
-
|
|
268
|
+
### Security Issues
|
|
307
269
|
|
|
308
|
-
|
|
270
|
+
```jsonc
|
|
271
|
+
// Show only Critical and High issues
|
|
272
|
+
show_security_issues {"severities": ["Critical", "High"], "limit": 20}
|
|
309
273
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
274
|
+
// Show dismissed issues
|
|
275
|
+
show_security_issues {"status": "Dismissed"}
|
|
276
|
+
|
|
277
|
+
// Fix issue #5
|
|
278
|
+
ai_fix_security_issue {"issue_id": "5"}
|
|
313
279
|
|
|
314
|
-
|
|
315
|
-
|
|
280
|
+
// Fix by description
|
|
281
|
+
ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • GET /users"}
|
|
316
282
|
```
|
|
317
283
|
|
|
318
|
-
|
|
284
|
+
### Design & Quality Issues
|
|
319
285
|
|
|
320
|
-
|
|
286
|
+
```jsonc
|
|
287
|
+
show_design_issues {"status": "Open", "sort_by": "createdOn", "sort_order": "DESC"}
|
|
288
|
+
show_quality_issues {"limit": 50}
|
|
289
|
+
ai_fix_design_issue {"issue_id": "2"}
|
|
290
|
+
ai_fix_quality_issue {"issue_id": "7"}
|
|
291
|
+
```
|
|
321
292
|
|
|
322
|
-
|
|
323
|
-
- **Browser doesn't open**: Manually visit the URL shown in the login response
|
|
324
|
-
- **Code expired**: Run `login` again to get a new device code
|
|
325
|
-
- **Stuck on authentication**: Check browser for any error messages
|
|
293
|
+
---
|
|
326
294
|
|
|
327
|
-
|
|
328
|
-
- **No organizations found**: Run `manage_organizations {"action": "refresh"}`
|
|
329
|
-
- **Permission denied**: Ensure your PerfAI account has organization access
|
|
295
|
+
## 🚀 Local Development
|
|
330
296
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
-
|
|
334
|
-
|
|
297
|
+
```bash
|
|
298
|
+
git clone https://github.com/perfai/mcp-server.git
|
|
299
|
+
cd mcp-server
|
|
300
|
+
npm install
|
|
301
|
+
npm run build # compile TS → dist/
|
|
302
|
+
npm start # start MCP server
|
|
303
|
+
npm run dev # watch mode
|
|
304
|
+
npm run mcp:inspect # MCP Inspector UI at http://localhost:6274
|
|
305
|
+
```
|
|
335
306
|
|
|
336
|
-
|
|
337
|
-
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## 🔍 Troubleshooting
|
|
310
|
+
|
|
311
|
+
| Problem | Fix |
|
|
312
|
+
|---------|-----|
|
|
313
|
+
| Browser doesn't open on `login` | Manually visit the URL shown in the tool response |
|
|
314
|
+
| `No organizations found` | Run `manage_organizations {"action": "refresh"}` |
|
|
315
|
+
| App not found by name | Run `list_apps {}` first and use the exact sequence number |
|
|
316
|
+
| Protected tool says "Authentication required" | Run `login` first |
|
|
317
|
+
| Stale issues after a fix | Wait a moment and re-run `show_*_issues` |
|
|
318
|
+
|
|
319
|
+
Debug logs go to stderr:
|
|
338
320
|
```bash
|
|
339
|
-
npm start 2> debug.log
|
|
321
|
+
npm start 2> debug.log
|
|
340
322
|
```
|
|
341
323
|
|
|
342
|
-
|
|
324
|
+
---
|
|
325
|
+
|
|
326
|
+
## 🌟 Key Features
|
|
327
|
+
|
|
328
|
+
- **Auth0 OAuth2** — secure browser-based login, no plaintext credentials in config
|
|
329
|
+
- **Org & App selection** — by sequence number, name/label partial match, or ID
|
|
330
|
+
- **Issue filters** — severity, status (Open/Dismissed), sort field & direction, keyword search, pagination
|
|
331
|
+
- **Summary dashboard** — single-call overview of security, design, quality, attack surface, and bug bounty savings
|
|
332
|
+
- **AI fix prompts** — generate actionable fix instructions for any issue by number, ID, or description
|
|
333
|
+
- **Fix tracking** — compare AI-fixed issues against post-run results to confirm resolution
|
|
343
334
|
|
|
344
|
-
|
|
345
|
-
- **🔐 Secure Authentication**: OAuth2 Device Code flow with session management
|
|
346
|
-
- **📊 Comprehensive Analysis**: Full security issue management and AI-powered fixes
|
|
347
|
-
- **🐳 Docker Integration**: Containerized security testing engine
|
|
348
|
-
- **🔄 Real-time Updates**: Live tool list updates based on authentication state
|
|
349
|
-
- **📱 Universal Client Support**: Works with Cursor, VS Code, and any MCP client
|
|
335
|
+
---
|
|
350
336
|
|
|
337
|
+
## 📄 License
|
|
351
338
|
|
|
352
|
-
|
|
339
|
+
MIT — see [LICENSE](LICENSE)
|