@perfai/mcp 1.0.24

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 PerfAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,352 @@
+# PerfAI MCP Server
+
+A specialized Model Context Protocol (MCP) server for **PerfAI Security Analysis** with Auth0 authentication.
+
+## 📦 Installation (from npm)
+
+Install globally (CLI):
+
+```bash
+npm install -g perfai-mcp-server
+```
+
+Or add as a project dependency:
+
+```bash
+npm install perfai-mcp-server --save-dev
+```
+
+## ⚙️ Quick Setup
+
+Generate MCP configuration files with placeholders:
+
+```bash
+perfai-mcp-setup
+```
+
+This creates `cursor_mcp_config.json` and `vscode_mcp_config.json` in your current directory with placeholder credentials that you can edit.
+
+## 🚀 Run (CLI)
+
+```bash
+perfai-mcp-server
+```
+
+This starts the MCP server over stdio. Use with an MCP client (Cursor, VS Code, MCP Inspector).
+
+### Required Environment Variables
+
+You only need to provide your PerfAI credentials:
+
+```bash
+set PERFAI_USERNAME=your-username
+set PERFAI_PASSWORD=your-password
+```
+
+**Note:** Auth0 domain and client ID are pre-configured and don't need to be set.
+
+### Kubernetes (K8s Secrets)
+
+Store credentials in a Kubernetes `Secret` and inject them as environment variables (recommended for clusters).
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: perfai-mcp-secrets
+type: Opaque
+stringData:
+  PERFAI_USERNAME: "<perfai-username>"
+  PERFAI_PASSWORD: "<perfai-password>"
+  # Optional (only if used in your deployment)
+  PERFAI_DASHBOARD_API_AUTH: "Authorization: Basic <base64(user:pass)>"
+  PERFAI_AUTH0_CLIENT_SECRET: "<auth0-client-secret>"
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: perfai-mcp
+spec:
+  template:
+    spec:
+      containers:
+        - name: perfai-mcp
+          envFrom:
+            - secretRef:
+                name: perfai-mcp-secrets
+```
+
+## 🧩 Programmatic Usage
+
+```ts
+import { startServer, authManager, AuthenticationManager } from '@perfai/mcp-server';
+
+// Start server (returns a promise)
+await startServer();
+```
+
+All logging is written to stderr to remain MCP-compatible.
+
+## 🔐 Authentication & Security
+
+**🎯 Universal Device Code Authentication** - Works with ANY MCP client without configuration!
+
+- **🔑 Auth0 Integration**: Seamless integration with `auth.perfai.ai`
+- **🌐 Zero Configuration**: No redirect URLs needed - works everywhere
+- **📱 Device Code Flow**: Simple browser authentication like Netflix/GitHub
+- **🛡️ Session Management**: Secure token storage and automatic validation
+- **🔄 Auto-Detection**: Server automatically detects authentication completion
+- **👥 Multi-User Support**: Isolated sessions for different users
+
+## 🛠️ Available Tools
+
+### 🔓 **Public Tools** (No authentication required)
+- **🔐 `login`**: Authenticate with PerfAI using OAuth2 Device Code flow
+- **📊 `auth_status`**: Check current authentication status and user information
+
+### 🔒 **Protected Tools** (Authentication required)
+
+#### 👤 **User Management**
+- **👤 `user_info`**: Get detailed authenticated user information
+- **🚪 `logout`**: Clear authentication session and logout
+
+#### 🏢 **Organization Management**
+- **🏢 `manage_organizations`**: List, select, and refresh organizations
+  - Actions: `list`, `select`, `refresh`
+- **📋 `list_apps`**: List all APPs in table format (Seq, App Name, Label) - shows unique instances
+- **🎯 `select_app`**: Select an APP by sequence number from list_apps table
+
+#### 🔒 **Security Analysis**
+- **🔒 `show_security_issues`**: List security vulnerabilities by organization
+  - Shows 20 issues at a time with pagination
+  - Sorted by severity (Critical → High → Medium → Low)
+  - Displays CVSS scores for each issue
+  - Supports pagination, search, and severity filtering
+- **🤖 `ai_fix_security_issue`**: Generate AI-powered remediation prompts
+  - Works with sequence numbers, issue IDs, or descriptive text
+- **📋 `show_fixed_issues`**: View all AI-fixed security issues in current session
+
+#### 🚀 **Security Testing**
+- **🚀 `run_security_test`**: Execute comprehensive security analysis using Docker
+  - Requires OpenAPI spec URL and local API base path
+  - Uses PerfAI's Docker-based security testing engine
+  - Waits 40 seconds for system to process security issues
+- **🔍 `check_security_fixes`**: Check which previously fixed security issues were actually resolved
+  - Independent tool that can be run anytime
+  - Shows comparison table of fixed vs still existing issues
+  - Clears fixed issues from session after comparison
+
+## 🚀 Quick Start (Local Development)
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Build the Project
+```bash
+npm run build
+```
+
+### 3. Start the Server (built output)
+```bash
+npm start
+```
+
+Or directly via ts-node (optional):
+
+```bash
+npx ts-node src/index.ts
+```
+
+### 4. Test with MCP Inspector (Optional)
+```bash
+npm run mcp:inspect
+```
+
+## 🔧 MCP Client Configuration
+
+### For Cursor
+Add to your `cursor_mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "perfai-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["perfai-mcp-server"],
+      "env": {
+        "PERFAI_USERNAME": "your-username",
+        "PERFAI_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### For VS Code
+Add to your `vscode_mcp_config.json`:
+```json
+{
+  "mcpServers": {
+    "perfai-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["perfai-mcp-server"],
+      "env": {
+        "PERFAI_USERNAME": "your-username",
+        "PERFAI_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## 🧪 Authentication Flow
+
+### Step-by-Step Authentication
+
+1. **Check Initial Status**: Run `auth_status` → Shows "Not Authenticated"
+2. **Login**: Run `login` tool:
+   - ✅ Browser automatically opens to PerfAI Auth0 device page
+   - 📱 You'll see a simple code (e.g., `BDJK-WHNZ`)
+   - 🔐 Enter the code in browser and complete authentication
+   - 🔄 Server automatically detects completion
+3. **Verify**: Run `auth_status` → Shows user info and "Authenticated"
+4. **Use Protected Tools**: All 9 protected tools now available
+5. **Logout**: Run `logout` → Returns to 2 public tools only
+
+### Security Features
+- **🔒 Zero Configuration**: No Auth0 redirect URL setup required
+- **🌐 Universal Compatibility**: Works with any MCP client
+- **⏰ Auto-Expiry**: Tokens automatically expire for security
+- **🔄 Session Isolation**: Each user session is completely isolated
+
+## 📋 Tool Usage Examples
+
+### Organization Management
+```bash
+# List available organizations
+manage_organizations {"action": "list"}
+
+# Select an organization
+manage_organizations {"action": "select", "org_id": "your-org-id"}
+
+# Refresh organization list
+manage_organizations {"action": "refresh"}
+```
+
+### Security Analysis
+```bash
+# List security issues
+show_security_issues {"limit": 20}
+
+# Search for specific app issues
+show_security_issues {"search": "myapp", "limit": 10}
+
+# Generate AI fix for an issue by sequence number
+ai_fix_security_issue {"issue_id": "14"}
+
+# Generate AI fix for an issue by ID
+ai_fix_security_issue {"issue_id": "issue-id-here"}
+
+# Generate AI fix for an issue by description
+ai_fix_security_issue {"issue_id": "System Design Issues/Enumerable Resource ID • MULTIPLE /store"}
+
+# Show all fixed issues
+show_fixed_issues {}
+```
+
+### APP Management
+```bash
+# List available APPs (shows table with sequence numbers)
+list_apps {}
+
+# Select an APP by sequence number from list_apps table
+select_app {"sequence": 1}
+```
+
+### Security Testing
+```bash
+# Run comprehensive security test (waits 40 seconds for processing)
+run_security_test {
+  "spec_url": "http://localhost:3000/swagger.json",
+  "local_base_path": "http://localhost:3000"
+}
+
+# Check which previously fixed issues were actually resolved
+check_security_fixes {"wait_seconds": 15}
+```
+
+## 🏗️ Development
+
+### Watch Mode
+```bash
+npm run dev
+```
+
+### Available Scripts
+- `npm run build` – Compile TypeScript to JavaScript
+- `npm run dev` – Watch mode for development
+- `npm start` – Start the MCP server
+- `npm run mcp:inspect` – Start MCP Inspector for testing
+
+### Project Structure
+```
+├── src/
+│   └── index.ts              # Main MCP server implementation
+├── dist/                     # Compiled JavaScript output
+├── package.json              # Dependencies and scripts
+├── tsconfig.json             # TypeScript configuration
+├── cursor_mcp_config.json    # Cursor MCP client config
+├── vscode_mcp_config.json    # VS Code MCP client config
+└── README.md                 # This file
+```
+
+## 🔍 Troubleshooting
+
+### Publishing (Maintainers)
+
+```bash
+# Bump version (choose patch|minor|major)
+npm version patch
+
+# Publish (scoped public)
+npm publish --access public
+```
+
+If you see 403 errors ensure: (1) You're logged in (`npm whoami`), (2) The `@perfai` scope exists and you have publish rights, (3) Version not already published.
+
+### Common Issues
+
+#### Authentication Problems
+- **Browser doesn't open**: Manually visit the URL shown in the login response
+- **Code expired**: Run `login` again to get a new device code
+- **Stuck on authentication**: Check browser for any error messages
+
+#### Organization Issues
+- **No organizations found**: Run `manage_organizations {"action": "refresh"}`
+- **Permission denied**: Ensure your PerfAI account has organization access
+
+#### API Testing Issues
+- **Docker errors**: Ensure Docker Desktop is running
+- **Invalid URLs**: Verify your APP is accessible and spec URL is valid
+- **Timeout**: Large APIs may take longer; check Docker logs
+
+### Debug Mode
+The server logs all activity to stderr, making debugging easier:
+```bash
+npm start 2> debug.log  # Capture debug logs
+```
+
+## 🌟 Features
+
+- **🎯 PerfAI-Focused**: Built specifically for PerfAI security workflows
+- **🔐 Secure Authentication**: OAuth2 Device Code flow with session management
+- **📊 Comprehensive Analysis**: Full security issue management and AI-powered fixes
+- **🐳 Docker Integration**: Containerized security testing engine
+- **🔄 Real-time Updates**: Live tool list updates based on authentication state
+- **📱 Universal Client Support**: Works with Cursor, VS Code, and any MCP client
+
+
+**🚀 Ready to secure your APIs with PerfAI's MCP integration!**

package/dist/auth/authManager.d.ts

@@ -0,0 +1,83 @@
+import { UserSession, FixedIssue } from './types.js';
+export declare class AuthenticationManager {
+    session: UserSession | null;
+    private codeVerifier;
+    private authServer;
+    private sessionStorage;
+    private isInitialized;
+    private initializationPromise;
+    constructor();
+    /**
+     * Wait for session initialization to complete
+     */
+    waitForInitialization(): Promise<void>;
+    /**
+     * Initialize session from persistent storage
+     */
+    private initializeSession;
+    /**
+     * Schedule automatic session saving when session data changes
+     */
+    private scheduleSessionSave;
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Synchronous version for backward compatibility
+     * Note: This will return false if initialization is still in progress
+     */
+    isAuthenticatedSync(): boolean;
+    getUserInfo(): any;
+    getAccessToken(): string | null;
+    getTokenType(): string;
+    getSelectedOrgId(): string | null;
+    getOrganizations(): any[];
+    setSelectedOrgId(orgId: string): void;
+    getSelectedApiId(): string | null;
+    getSelectedApiData(): any | null;
+    getSelectedApiIdentifier(): any | null;
+    setSelectedApi(apiId: string, apiData: any, apiIdentifier: any): void;
+    getSelectedSecurityAppId(): string | null;
+    setSelectedSecurityAppId(securityAppId: string): void;
+    getSelectedDesignAppId(): string | null;
+    setSelectedDesignAppId(designAppId: string): void;
+    getSelectedQualityAppId(): string | null;
+    setSelectedQualityAppId(qualityAppId: string): void;
+    setAppSequenceMap(sequenceMap: Map<number, string>): void;
+    getAppSequenceMap(): Map<number, string> | null;
+    getAppIdBySequence(sequenceNumber: number): string | null;
+    clearAppSequenceMap(): void;
+    getFixedIssues(): FixedIssue[];
+    markIssueAsFixed(issueId: string, issue: any, prompt: string): FixedIssue;
+    isIssueFixed(issueId: string): boolean;
+    clearFixedIssues(): void;
+    getFixedDesignIssues(): FixedIssue[];
+    markDesignIssueAsFixed(issueId: string, issue: any, prompt: string): FixedIssue;
+    isDesignIssueFixed(issueId: string): boolean;
+    clearFixedDesignIssues(): void;
+    getFixedQualityIssues(): FixedIssue[];
+    addFixedQualityIssue(fixedIssue: FixedIssue): void;
+    markQualityIssueAsFixed(issueId: string, issue: any, prompt: string): FixedIssue;
+    isQualityIssueFixed(issueId: string): boolean;
+    clearFixedQualityIssues(): void;
+    clearSession(): void;
+    /**
+     * Get session storage location for debugging
+     */
+    getStorageLocation(): string;
+    /**
+     * Check if there's a valid session in storage without loading it
+     */
+    hasValidStoredSession(): boolean;
+    /**
+     * Save current session to persistent storage
+     */
+    saveCurrentSession(): Promise<void>;
+    generateCodeChallenge(): {
+        codeVerifier: string;
+        codeChallenge: string;
+    };
+    buildAuthUrl(): string;
+    manualCodeFlow(): Promise<string>;
+    startAuthServer(): Promise<string>;
+    exchangeCodeForTokens(code: string): Promise<void>;
+}
+//# sourceMappingURL=authManager.d.ts.map

package/dist/auth/authManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authManager.d.ts","sourceRoot":"","sources":["../../src/auth/authManager.ts"],"names":[],"mappings":"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"}