@prsna_ai/mcp-server/README.md

Model Context Protocol server for PRSNA personality profiles and communication insights

# PRSNA MCP Server

A Model Context Protocol (MCP) server that enables AI tools (Claude, Cursor, OpenAI) to access personality profiles and communication insights from the PRSNA platform.

## 🚀 Quick Start

**For most users:**
```bash
npm install -g @prsna_ai/mcp-server
```

**Then follow our [📋 Complete Setup Guide](./SETUP_GUIDE.md) for step-by-step instructions!**

---

## Features

- **Authentication**: Secure connection to PRSNA API with bearer token
- **Profile Management**: List, search, and retrieve personality profiles  
- **Communication Intelligence**: Get personalized communication tips and strategies
- **Quick Lookup**: @mention functionality for fast profile context
- **Caching**: Intelligent caching for improved performance
- **Error Handling**: Robust error handling with detailed logging

## Available Tools

| Tool | Description |
|------|-------------|
| `prsna_login` | Authenticate with PRSNA using bearer token |
| `list_personality_profiles` | List all saved personality profiles |
| `search_personality_profiles` | Search profiles by name, company, or job title |
| `get_personality_context` | Get comprehensive personality context for a person |
| `get_communication_tips` | Get specific communication tips for interacting with someone |
| `mention_person` | Quick lookup for @mention functionality |
| `my_personality_profile` | Get your own personality profile and assessment results |

## Installation

### Prerequisites

- Node.js 16+ 
- PRSNA account with saved personality profiles
- PRSNA MCP API token (generated from your PRSNA profile settings)

### Setup

1. **Clone and Install**
   ```bash
   cd prsna-mcp
   npm install
   ```

2. **Get Your PRSNA MCP Token**
   - Log into [PRSNA](https://prsna.ai) and go to Profile Settings
   - Click on the "MCP Tokens" tab
   - Generate a new token with a descriptive name (e.g., "Claude Desktop")
   - Copy the token immediately (it won't be shown again)

3. **Environment Configuration**
   ```bash
   cp env.example .env
   ```
   
   Edit `.env` file:
   ```bash
   # Required: Your PRSNA MCP token (starts with prsna_)
   PRSNA_API_TOKEN=prsna_your_generated_token_here
   
   # Optional: Custom API URL (defaults to production)
   PRSNA_API_URL=https://prsna.ai/api
   
   # Optional: Logging level
   LOG_LEVEL=info
   ```

4. **Build the Project**
   ```bash
   npm run build
   ```

5. **Test the Server**
   ```bash
   npm test
   ```

## Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "prsna": {
      "command": "node",
      "args": ["/absolute/path/to/prsna-mcp/dist/index.js"],
      "env": {
        "PRSNA_API_TOKEN": "prsna_your_generated_token_here"
      }
    }
  }
}
```

### Cursor IDE

Add to your Cursor settings (`.cursor-settings/mcp.json`):

```json
{
  "mcp": {
    "servers": {
      "prsna": {
        "command": ["node", "/absolute/path/to/prsna-mcp/dist/index.js"],
        "env": {
          "PRSNA_API_TOKEN": "prsna_your_generated_token_here"
        }
      }
    }
  }
}
```

### Other MCP Clients

For other MCP-compatible tools, use:
- **Command**: `node /path/to/prsna-mcp/dist/index.js`
- **Environment**: Set `PRSNA_API_TOKEN`
- **Transport**: stdio

## Usage Examples

### Basic Authentication

```typescript
// Test your connection
await prsna_login({ token: "your-api-token" })
```

### List Profiles

```typescript
// Get first 10 profiles
await list_personality_profiles({ limit: 10, offset: 0 })

// Get next page
await list_personality_profiles({ limit: 10, offset: 10 })
```

### Search for People

```typescript
// Search by name
await search_personality_profiles({ query: "John Smith" })

// Search by company
await search_personality_profiles({ query: "Acme Corp" })

// Search by job title
await search_personality_profiles({ query: "Product Manager" })
```

### Get Detailed Context

```typescript
// By profile ID
await get_personality_context({ profileId: "profile-id-123" })

// By name
await get_personality_context({ name: "Sarah Johnson" })
```

### Communication Tips

```typescript
// General communication tips
await get_communication_tips({ name: "Alex Thompson" })

// Scenario-specific tips
await get_communication_tips({ 
  name: "Alex Thompson",
  scenario: "feedback meeting"
})

// Other scenarios: "project collaboration", "conflict resolution", "brainstorming session"
```

### Quick @Mention Lookup

```typescript
// Fast lookup for mentions
await mention_person({ name: "Maria Garcia" })
```

### Your Own Profile

```typescript
// Get your personality profile
await my_personality_profile({})
```

## Response Format

All tools return responses in this format:

```json
{
  "success": true,
  "data": {
    // Tool-specific response data
  }
}
```

Error responses:

```json
{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}
```

## Personality Dimensions

PRSNA analyzes personality across five key dimensions:

| Dimension | Poles | Description |
|-----------|--------|-------------|
| **Expression** | Internal ↔ External | How people process and share thoughts |
| **Decision Making** | Logic ↔ Feeling | Primary decision-making criteria |
| **Adaptability** | Structured ↔ Adaptive | Preference for planning vs. flexibility |
| **Work Style** | Process-Driven ↔ Results-Driven | Focus on methodology vs. outcomes |
| **Work Tempo** | Fast-Paced ↔ Deliberate-Paced | Preferred speed of work and decisions |

## Caching

The MCP server implements intelligent caching:

- **Profile Data**: 1 hour TTL
- **Search Results**: 15 minutes TTL  
- **User Profile**: 24 hours TTL
- **Maximum Cache Size**: 1000 entries

Cache automatically cleans up expired entries every 5 minutes.

## Logging

Logging levels (set via `LOG_LEVEL` environment variable):

- `DEBUG`: Detailed debugging information
- `INFO`: General information (default)
- `WARN`: Warning messages
- `ERROR`: Error messages only

Logs include timestamps, levels, and structured data for easy debugging.

## Troubleshooting

### Common Issues

**"PRSNA_API_TOKEN environment variable is required"**
- Ensure your `.env` file contains a valid PRSNA API token
- Contact PRSNA support if you need an API token

**"Authentication failed"**
- Verify your API token is correct and not expired
- Check that you have access to the PRSNA API

**"No profile found for name"**
- Check spelling and try partial names
- Use `search_personality_profiles` for broader matching
- Ensure the person has a saved profile in your PRSNA account

**"Failed to connect to PRSNA API"**
- Check your internet connection
- Verify the API URL in your configuration
- Check if PRSNA services are operational

### Debug Mode

Run with debug logging:

```bash
LOG_LEVEL=debug npm run start
```

### Cache Issues

Clear cache by restarting the server:

```bash
# Stop and restart the MCP server
```

## Development

### Project Structure

```
prsna-mcp/
├── src/
│   ├── api/
│   │   ├── client.ts      # PRSNA API client
│   │   └── types.ts       # TypeScript interfaces
│   ├── cache/
│   │   └── cache.ts       # Caching implementation
│   ├── tools/
│   │   ├── auth.ts        # Authentication tool
│   │   ├── profiles.ts    # Profile management tools
│   │   ├── context.ts     # Communication tools
│   │   ├── mention.ts     # @mention functionality
│   │   └── index.ts       # Tool exports
│   ├── utils/
│   │   ├── logger.ts      # Logging utilities
│   │   └── constants.ts   # Configuration constants
│   └── index.ts           # Main MCP server
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Scripts

```bash
npm run build      # Compile TypeScript
npm run dev        # Watch mode development
npm run start      # Start the server
npm run test       # Test the server
npm run clean      # Clean build artifacts
```

### Adding New Tools

1. Create tool function in appropriate file under `src/tools/`
2. Add tool definition with proper schema
3. Export tool in `src/tools/index.ts`
4. Update documentation

## API Reference

### Tool Schemas

Each tool accepts specific parameters defined by JSON schemas. See the source code for detailed schemas, or use the `ListTools` MCP request to get current schemas.

### Error Codes

- `401`: Authentication failed
- `404`: Profile not found
- `429`: Rate limit exceeded
- `500`: Internal server error

## Support

- **Documentation**: This README
- **Issues**: Report issues with detailed error logs
- **PRSNA API**: Contact PRSNA support for API access

## License

MIT License - see LICENSE file for details.

---

**Version**: 1.0.0
**Last Updated**: December 2024