perfai-test-1-mcp-server/README.md

PerfAI Model Context Protocol (MCP) server providing security analysis tools and Auth0 authentication.

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

## 🚀 Run (CLI)

```bash
perfai-mcp-server
```

This starts the MCP server over stdio. Use with an MCP client (Cursor, VS Code, MCP Inspector).

### Optional Environment Variables

You can override Auth0 settings:

```bash
set PERFAI_AUTH0_DOMAIN=auth.perfai.ai
set PERFAI_AUTH0_CLIENT_ID=yourClientId
```

PKCE flow is enabled; no client secret is required or bundled.

## 🧩 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_apis`**: List all APIs available in current organization
- **🎯 `select_api`**: Select an API for use with other tools

#### 🔒 **Security Analysis**
- **🔒 `show_security_issues`**: List security vulnerabilities by organization
  - Supports pagination, search, and severity filtering
- **🤖 `ai_fix_security_issue`**: Generate AI-powered remediation prompts
  - Works with 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

## 🚀 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": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_prefai\\dist\\index.js"],
      "env": {}
    }
  }
}
```

### For VS Code
Add to your `vscode_mcp_config.json`:
```json
{
  "mcpServers": {
    "perfai-mcp": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_prefai\\dist\\index.js"],
      "env": {}
    }
  }
}
```

## 🧪 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
ai_fix_security_issue {"issue_id": "issue-id-here"}

# Show all fixed issues
show_fixed_issues {}
```

### API Management
```bash
# List available APIs
list_apis {}

# Select an API for testing
select_api {"api_id": "your-api-id"}
```

### Security Testing
```bash
# Run comprehensive security test
run_security_test {
  "spec_url": "http://localhost:3000/swagger.json",
  "local_base_path": "http://localhost:3000"
}
```

## 🏗️ 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 API 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!**