mcp-talent-server/README.md

Model Context Protocol server for talent management tools

# Talent Management MCP Server

A Model Context Protocol (MCP) server providing tools for talent management, gallery operations, structured data search, and vector-based document search.

## Tools

### 1. Gallery Zip Export (`gallery_zip_export`)
Export gallery images as ZIP files with intelligent search and scoring algorithms.

**Features:**
- Smart search with fuzzy matching
- Folder hierarchy preservation
- S3 upload with public URLs
- Comprehensive metadata export
- MongoDB query support

### 2. Structured Sheets Search (`structured_sheets_search`)
Search across structured data using MongoDB aggregation pipelines.

**Features:**
- Natural language to MongoDB aggregation
- Multi-sheet query support
- Dynamic schema handling
- Advanced filtering and pagination
- Secure pipeline validation

### 3. Vector Search (`vector_search`)
Semantic document search using vector embeddings.

**Features:**
- AI-powered semantic search
- Relevance scoring
- Multi-document support
- Content highlighting
- Smart filtering and deduplication

## Setup

1. **Install dependencies:**
```bash
npm install
```

2. **Environment configuration:**
Copy `.env.example` to `.env` and configure:
```bash
# MongoDB
MONGODB_URI=mongodb://localhost:27017/talent-pitch

# AWS S3
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
AWS_S3_BUCKET_NAME=your-bucket-name
```

3. **Build the server:**
```bash
npm run build
```

4. **Run in development:**
```bash
npm run dev
```

5. **Run in production:**
```bash
npm start
```

## Usage with Claude

Add to your Claude configuration:

```json
{
  "mcpServers": {
    "talent-management": {
      "command": "node",
      "args": ["/path/to/mcp-talent-server/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/talent-pitch",
        "AWS_ACCESS_KEY_ID": "your_key",
        "AWS_SECRET_ACCESS_KEY": "your_secret",
        "AWS_REGION": "us-east-1",
        "AWS_S3_BUCKET_NAME": "your-bucket"
      }
    }
  }
}
```

## Tool Examples

### Gallery Export
```javascript
{
  "folderNames": ["Influencer Photos"],
  "imageNames": ["headshot", "profile"],
  "foldersSearchQuery": "{\"userId\": \"user123\"}",
  "imagesSearchQuery": "{\"tags\": \"professional\"}",
  "maxImages": 20,
  "includeSubfolders": true
}
```

### Structured Search
```javascript
{
  "query": "Find influencers in California with 100K+ followers",
  "limit": 10,
  "page": 1,
  "includeSchema": true
}
```

### Vector Search
```javascript
{
  "query": "Instagram Story pricing for beauty influencers",
  "maxResults": 10,
  "minRelevanceScore": 0.7,
  "includeMetadata": true
}
```

## Development

- **TypeScript**: Full type safety
- **ESM**: Modern module system
- **Zod**: Runtime validation
- **MongoDB**: Document database
- **AWS S3**: File storage
- **MCP SDK**: Protocol compliance

## License

MIT