@perfai/mcp 1.0.24 → 1.0.26
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 +249 -253
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,352 +1,348 @@
|
|
|
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
|
-
|
|
5
|
+
---
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## 📦 Installation
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
|
|
10
|
+
npx -y @perfai/mcp@latest
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
Or
|
|
13
|
+
Or install globally:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
npm install perfai
|
|
16
|
+
npm install -g @perfai/mcp
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
Generate MCP configuration files with placeholders:
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
perfai-mcp-setup
|
|
25
|
-
```
|
|
19
|
+
---
|
|
26
20
|
|
|
27
|
-
|
|
21
|
+
## ⚡ Quick Start — One-Line Setup
|
|
28
22
|
|
|
29
|
-
|
|
23
|
+
### Claude (Desktop or CLI)
|
|
30
24
|
|
|
31
25
|
```bash
|
|
32
|
-
perfai-mcp-
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
This starts the MCP server over stdio. Use with an MCP client (Cursor, VS Code, MCP Inspector).
|
|
26
|
+
claude mcp add perfai-mcp --scope user -e PERFAI_USERNAME=your@email.com -e PERFAI_PASSWORD=yourpassword -- npx -y @perfai/mcp@latest
|
|
36
27
|
|
|
37
|
-
### Required Environment Variables
|
|
38
|
-
|
|
39
|
-
You only need to provide your PerfAI credentials:
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
set PERFAI_USERNAME=your-username
|
|
43
|
-
set PERFAI_PASSWORD=your-password
|
|
44
28
|
```
|
|
45
29
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
### Kubernetes (K8s Secrets)
|
|
30
|
+
That single command registers the server, sets credentials, and connects it to Claude. No config file editing needed.
|
|
49
31
|
|
|
50
|
-
Store credentials in a Kubernetes `Secret` and inject them as environment variables (recommended for clusters).
|
|
51
|
-
|
|
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
32
|
---
|
|
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
33
|
|
|
84
|
-
|
|
85
|
-
await startServer();
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
All logging is written to stderr to remain MCP-compatible.
|
|
89
|
-
|
|
90
|
-
## 🔐 Authentication & Security
|
|
91
|
-
|
|
92
|
-
**🎯 Universal Device Code Authentication** - Works with ANY MCP client without configuration!
|
|
34
|
+
## 🔧 MCP Client Configuration
|
|
93
35
|
|
|
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
|
|
36
|
+
### Claude Desktop
|
|
100
37
|
|
|
101
|
-
|
|
38
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
102
39
|
|
|
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
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"perfai-mcp": {
|
|
44
|
+
"command": "npx",
|
|
45
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
46
|
+
"env": {
|
|
47
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
48
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
149
53
|
```
|
|
150
54
|
|
|
151
|
-
###
|
|
152
|
-
```bash
|
|
153
|
-
npm start
|
|
154
|
-
```
|
|
55
|
+
### Cursor
|
|
155
56
|
|
|
156
|
-
|
|
57
|
+
**Project-level** — create `.cursor/mcp.json` in your project root:
|
|
157
58
|
|
|
158
|
-
```
|
|
159
|
-
|
|
59
|
+
```json
|
|
60
|
+
{
|
|
61
|
+
"mcpServers": {
|
|
62
|
+
"perfai-mcp": {
|
|
63
|
+
"command": "npx",
|
|
64
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
65
|
+
"env": {
|
|
66
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
67
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
160
72
|
```
|
|
161
73
|
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
npm run mcp:inspect
|
|
165
|
-
```
|
|
74
|
+
**Global** — add the same block to `~/.cursor/mcp.json`.
|
|
166
75
|
|
|
167
|
-
|
|
76
|
+
### VS Code (Copilot Agent Mode)
|
|
77
|
+
|
|
78
|
+
Create `.vscode/mcp.json` in your workspace:
|
|
168
79
|
|
|
169
|
-
### For Cursor
|
|
170
|
-
Add to your `cursor_mcp_config.json`:
|
|
171
80
|
```json
|
|
172
81
|
{
|
|
173
|
-
"
|
|
82
|
+
"servers": {
|
|
174
83
|
"perfai-mcp": {
|
|
175
84
|
"type": "stdio",
|
|
176
85
|
"command": "npx",
|
|
177
|
-
"args": ["perfai
|
|
86
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
178
87
|
"env": {
|
|
179
|
-
"PERFAI_USERNAME": "your
|
|
180
|
-
"PERFAI_PASSWORD": "
|
|
88
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
89
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
181
90
|
}
|
|
182
91
|
}
|
|
183
92
|
}
|
|
184
93
|
}
|
|
185
94
|
```
|
|
186
95
|
|
|
187
|
-
|
|
188
|
-
|
|
96
|
+
> Note: VS Code uses the `"servers"` key (not `"mcpServers"`).
|
|
97
|
+
|
|
98
|
+
### Windsurf
|
|
99
|
+
|
|
100
|
+
Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
101
|
+
|
|
189
102
|
```json
|
|
190
103
|
{
|
|
191
104
|
"mcpServers": {
|
|
192
105
|
"perfai-mcp": {
|
|
193
|
-
"type": "stdio",
|
|
194
106
|
"command": "npx",
|
|
195
|
-
"args": ["perfai
|
|
107
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
196
108
|
"env": {
|
|
197
|
-
"PERFAI_USERNAME": "your
|
|
198
|
-
"PERFAI_PASSWORD": "
|
|
109
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
110
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
199
111
|
}
|
|
200
112
|
}
|
|
201
113
|
}
|
|
202
114
|
}
|
|
203
115
|
```
|
|
204
116
|
|
|
205
|
-
|
|
117
|
+
### Zed
|
|
206
118
|
|
|
207
|
-
|
|
119
|
+
Add to your Zed `settings.json`:
|
|
120
|
+
|
|
121
|
+
```json
|
|
122
|
+
{
|
|
123
|
+
"context_servers": {
|
|
124
|
+
"perfai-mcp": {
|
|
125
|
+
"command": {
|
|
126
|
+
"path": "npx",
|
|
127
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
128
|
+
"env": {
|
|
129
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
130
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
131
|
+
}
|
|
132
|
+
},
|
|
133
|
+
"settings": {}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
208
138
|
|
|
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
|
|
139
|
+
### Any other MCP client
|
|
218
140
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"command": "npx",
|
|
144
|
+
"args": ["-y", "@perfai/mcp@latest"],
|
|
145
|
+
"env": {
|
|
146
|
+
"PERFAI_USERNAME": "your@email.com",
|
|
147
|
+
"PERFAI_PASSWORD": "yourpassword"
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
224
151
|
|
|
225
|
-
|
|
152
|
+
---
|
|
226
153
|
|
|
227
|
-
|
|
228
|
-
```bash
|
|
229
|
-
# List available organizations
|
|
230
|
-
manage_organizations {"action": "list"}
|
|
154
|
+
## 🔐 Authentication
|
|
231
155
|
|
|
232
|
-
|
|
233
|
-
manage_organizations {"action": "select", "org_id": "your-org-id"}
|
|
156
|
+
Run the `login` tool from your AI assistant to open a browser-based Auth0 login. After authenticating, all protected tools become available automatically.
|
|
234
157
|
|
|
235
|
-
|
|
236
|
-
|
|
158
|
+
```
|
|
159
|
+
login # opens browser → authenticate → done
|
|
160
|
+
auth_status # verify you're authenticated
|
|
161
|
+
logout # clear session
|
|
237
162
|
```
|
|
238
163
|
|
|
239
|
-
|
|
240
|
-
```bash
|
|
241
|
-
# List security issues
|
|
242
|
-
show_security_issues {"limit": 20}
|
|
164
|
+
---
|
|
243
165
|
|
|
244
|
-
|
|
245
|
-
show_security_issues {"search": "myapp", "limit": 10}
|
|
166
|
+
## 🛠️ Available Tools
|
|
246
167
|
|
|
247
|
-
|
|
248
|
-
ai_fix_security_issue {"issue_id": "14"}
|
|
168
|
+
### 🔓 Public (no authentication required)
|
|
249
169
|
|
|
250
|
-
|
|
251
|
-
|
|
170
|
+
| Tool | Description |
|
|
171
|
+
| ------------- | -------------------------------------------------------- |
|
|
172
|
+
| `login` | Authenticate with PerfAI via Auth0 OAuth. Opens browser. |
|
|
173
|
+
| `auth_status` | Check current authentication status and user info. |
|
|
252
174
|
|
|
253
|
-
|
|
254
|
-
ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • MULTIPLE /store"}
|
|
175
|
+
### 🔒 Protected (authentication required)
|
|
255
176
|
|
|
256
|
-
|
|
257
|
-
show_fixed_issues {}
|
|
258
|
-
```
|
|
177
|
+
#### User & Session
|
|
259
178
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
179
|
+
| Tool | Description |
|
|
180
|
+
| ----------- | ------------------------------------------------------ |
|
|
181
|
+
| `user_info` | Get detailed information about the authenticated user. |
|
|
182
|
+
| `logout` | Clear authentication session. |
|
|
183
|
+
| `setup` | Auto-configure org and app with default values. |
|
|
184
|
+
|
|
185
|
+
#### Organization & App Management
|
|
186
|
+
|
|
187
|
+
| Tool | Parameters | Description |
|
|
188
|
+
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
|
|
189
|
+
| `manage_organizations` | `action` (list/select/refresh), `sequence`, `org_id` | List orgs with sequence numbers, select by number or ID. |
|
|
190
|
+
| `list_apps` | `search`, `environment`, `page`, `limit` | List all APPs with optional filters and pagination. |
|
|
191
|
+
| `select_app` | `sequence`, `name_or_label`, `app_id` | Select an APP by sequence number, partial name/label, or exact ID. |
|
|
192
|
+
|
|
193
|
+
#### Issue Summary
|
|
194
|
+
|
|
195
|
+
| Tool | Description |
|
|
196
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
197
|
+
| `summarize_issues` | Full dashboard for the selected APP — security risk, design issues, quality issues, attack surface, bug bounty savings, and coverage. |
|
|
198
|
+
|
|
199
|
+
#### Security Issues
|
|
200
|
+
|
|
201
|
+
| Tool | Parameters | Description |
|
|
202
|
+
| ----------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
|
|
203
|
+
| `show_security_issues` | `limit`, `severities[]`, `status`, `sort_by`, `sort_order`, `search`, `cursor` | List security vulnerabilities with filters. |
|
|
204
|
+
| `ai_fix_security_issue` | `issue_id` (sequence #, ID, or description) | Generate an AI-powered fix prompt for a security issue. |
|
|
205
|
+
| `check_security_fixes` | `wait_seconds` | Check which previously fixed issues were actually resolved. |
|
|
206
|
+
|
|
207
|
+
#### Design Issues
|
|
208
|
+
|
|
209
|
+
| Tool | Parameters | Description |
|
|
210
|
+
| --------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
|
|
211
|
+
| `show_design_issues` | `limit`, `status`, `sort_by`, `sort_order`, `search`, `cursor` | List API design issues with filters. |
|
|
212
|
+
| `ai_fix_design_issue` | `issue_id` | Generate an AI-powered fix prompt for a design issue. |
|
|
213
|
+
| `check_design_fixes` | `wait_seconds` | Check which design fixes were actually resolved. |
|
|
214
|
+
|
|
215
|
+
#### Quality / Spec Validation Issues
|
|
216
|
+
|
|
217
|
+
| Tool | Parameters | Description |
|
|
218
|
+
| ---------------------- | ---------------------------------------------------- | ------------------------------------------------------ |
|
|
219
|
+
| `show_quality_issues` | `limit`, `sort_by`, `sort_order`, `search`, `cursor` | List spec validation issues. |
|
|
220
|
+
| `ai_fix_quality_issue` | `issue_id` | Generate an AI-powered fix prompt for a quality issue. |
|
|
221
|
+
| `check_quality_fixes` | `wait_seconds` | Check which quality fixes were actually resolved. |
|
|
222
|
+
|
|
223
|
+
#### Session State
|
|
224
|
+
|
|
225
|
+
| Tool | Description |
|
|
226
|
+
| ------------------- | -------------------------------------------------- |
|
|
227
|
+
| `show_fixed_issues` | Show all AI-fixed issues from the current session. |
|
|
264
228
|
|
|
265
|
-
|
|
266
|
-
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 💡 Typical Workflow
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
1. login # authenticate
|
|
235
|
+
2. manage_organizations {"action": "list"} # see your orgs
|
|
236
|
+
3. manage_organizations {"action": "select", "sequence": 1}
|
|
237
|
+
4. list_apps {"search": "payments"} # find your app
|
|
238
|
+
5. select_app {"sequence": 2} # or by name: {"name_or_label": "payments"}
|
|
239
|
+
6. summarize_issues # dashboard overview
|
|
240
|
+
7. show_security_issues {"severities": ["Critical", "High"]}
|
|
241
|
+
8. ai_fix_security_issue {"issue_id": "3"} # fix issue #3
|
|
242
|
+
9. show_design_issues {"status": "Open"}
|
|
243
|
+
10. show_quality_issues {}
|
|
267
244
|
```
|
|
268
245
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
run_security_test {
|
|
273
|
-
"spec_url": "http://localhost:3000/swagger.json",
|
|
274
|
-
"local_base_path": "http://localhost:3000"
|
|
275
|
-
}
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 📋 Tool Examples
|
|
276
249
|
|
|
277
|
-
|
|
278
|
-
|
|
250
|
+
### Organization & App Selection
|
|
251
|
+
|
|
252
|
+
```jsonc
|
|
253
|
+
// List organizations with sequence numbers
|
|
254
|
+
manage_organizations {"action": "list"}
|
|
255
|
+
|
|
256
|
+
// Select org by sequence number (preferred)
|
|
257
|
+
manage_organizations {"action": "select", "sequence": 2}
|
|
258
|
+
|
|
259
|
+
// List apps — filter by name or environment
|
|
260
|
+
list_apps {"search": "checkout", "environment": "production", "page": 1, "limit": 50}
|
|
261
|
+
|
|
262
|
+
// Select app by partial name
|
|
263
|
+
select_app {"name_or_label": "checkout"}
|
|
264
|
+
|
|
265
|
+
// Select app by sequence number from list_apps
|
|
266
|
+
select_app {"sequence": 4}
|
|
279
267
|
```
|
|
280
268
|
|
|
281
|
-
|
|
269
|
+
### Summary Dashboard
|
|
282
270
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
271
|
+
```jsonc
|
|
272
|
+
// Full dashboard: security + design + quality + attack surface
|
|
273
|
+
summarize_issues {}
|
|
286
274
|
```
|
|
287
275
|
|
|
288
|
-
###
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
276
|
+
### Security Issues
|
|
277
|
+
|
|
278
|
+
```jsonc
|
|
279
|
+
// Show only Critical and High issues
|
|
280
|
+
show_security_issues {"severities": ["Critical", "High"], "limit": 20}
|
|
293
281
|
|
|
294
|
-
|
|
282
|
+
// Show dismissed issues
|
|
283
|
+
show_security_issues {"status": "Dismissed"}
|
|
284
|
+
|
|
285
|
+
// Fix issue #5
|
|
286
|
+
ai_fix_security_issue {"issue_id": "5"}
|
|
287
|
+
|
|
288
|
+
// Fix by description
|
|
289
|
+
ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • GET /users"}
|
|
295
290
|
```
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
291
|
+
|
|
292
|
+
### Design & Quality Issues
|
|
293
|
+
|
|
294
|
+
```jsonc
|
|
295
|
+
show_design_issues {"status": "Open", "sort_by": "createdOn", "sort_order": "DESC"}
|
|
296
|
+
show_quality_issues {"limit": 50}
|
|
297
|
+
ai_fix_design_issue {"issue_id": "2"}
|
|
298
|
+
ai_fix_quality_issue {"issue_id": "7"}
|
|
304
299
|
```
|
|
305
300
|
|
|
306
|
-
|
|
301
|
+
---
|
|
307
302
|
|
|
308
|
-
|
|
303
|
+
## 🚀 Local Development
|
|
309
304
|
|
|
310
305
|
```bash
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
#
|
|
315
|
-
npm
|
|
306
|
+
git clone https://github.com/perfai/mcp-server.git
|
|
307
|
+
cd mcp-server
|
|
308
|
+
npm install
|
|
309
|
+
npm run build # compile TS → dist/
|
|
310
|
+
npm start # start MCP server
|
|
311
|
+
npm run dev # watch mode
|
|
312
|
+
npm run mcp:inspect # MCP Inspector UI at http://localhost:6274
|
|
316
313
|
```
|
|
317
314
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
### Common Issues
|
|
315
|
+
---
|
|
321
316
|
|
|
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
|
|
317
|
+
## 🔍 Troubleshooting
|
|
326
318
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
319
|
+
| Problem | Fix |
|
|
320
|
+
| --------------------------------------------- | ---------------------------------------------------------- |
|
|
321
|
+
| Browser doesn't open on `login` | Manually visit the URL shown in the tool response |
|
|
322
|
+
| `No organizations found` | Run `manage_organizations {"action": "refresh"}` |
|
|
323
|
+
| App not found by name | Run `list_apps {}` first and use the exact sequence number |
|
|
324
|
+
| Protected tool says "Authentication required" | Run `login` first |
|
|
325
|
+
| Stale issues after a fix | Wait a moment and re-run `show_*_issues` |
|
|
330
326
|
|
|
331
|
-
|
|
332
|
-
- **Docker errors**: Ensure Docker Desktop is running
|
|
333
|
-
- **Invalid URLs**: Verify your APP is accessible and spec URL is valid
|
|
334
|
-
- **Timeout**: Large APIs may take longer; check Docker logs
|
|
327
|
+
Debug logs go to stderr:
|
|
335
328
|
|
|
336
|
-
### Debug Mode
|
|
337
|
-
The server logs all activity to stderr, making debugging easier:
|
|
338
329
|
```bash
|
|
339
|
-
npm start 2> debug.log
|
|
330
|
+
npm start 2> debug.log
|
|
340
331
|
```
|
|
341
332
|
|
|
342
|
-
|
|
333
|
+
---
|
|
343
334
|
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
-
|
|
347
|
-
-
|
|
348
|
-
-
|
|
349
|
-
-
|
|
335
|
+
## 🌟 Key Features
|
|
336
|
+
|
|
337
|
+
- **Auth0 OAuth2** — secure browser-based login, no plaintext credentials in config
|
|
338
|
+
- **Org & App selection** — by sequence number, name/label partial match, or ID
|
|
339
|
+
- **Issue filters** — severity, status (Open/Dismissed), sort field & direction, keyword search, pagination
|
|
340
|
+
- **Summary dashboard** — single-call overview of security, design, quality, attack surface, and bug bounty savings
|
|
341
|
+
- **AI fix prompts** — generate actionable fix instructions for any issue by number, ID, or description
|
|
342
|
+
- **Fix tracking** — compare AI-fixed issues against post-run results to confirm resolution
|
|
343
|
+
|
|
344
|
+
---
|
|
350
345
|
|
|
346
|
+
## 📄 License
|
|
351
347
|
|
|
352
|
-
|
|
348
|
+
MIT — see [LICENSE](LICENSE)
|