PerfAI MCP Server

A specialized Model Context Protocol (MCP) server for PerfAI Security Analysis with Auth0 authentication.

📦 Installation (from npm)

Install globally (CLI):

npm install -g perfai-mcp-server

Or add as a project dependency:

npm install perfai-mcp-server --save-dev

⚙️ Quick Setup

Generate MCP configuration files with placeholders:

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)

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:

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.

🧩 Programmatic Usage

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

npm install

2. Build the Project

npm run build

3. Start the Server (built output)

npm start

Or directly via ts-node (optional):

npx ts-node src/index.ts

4. Test with MCP Inspector (Optional)

npm run mcp:inspect

🔧 MCP Client Configuration

For Cursor

Add to your cursor_mcp_config.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:

{
  "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

# 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

# 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

# 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

# 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

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)

# 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:

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!