mcp-talent-server/CLAUDE.md

Model Context Protocol server for talent management tools

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Core Commands
- `npm run build` - Compile TypeScript to JavaScript in `dist/` folder
- `npm run dev` - Start development server with hot reload using nodemon + tsx
- `npm start` - Run production server from compiled `dist/index.js`
- `npm run lint` - Run ESLint on source code
- `npm run typecheck` - Type check without emitting files

### Deployment Commands
- `npm run vercel-build` - Build and prepare for Vercel deployment (copies dist to api/)
- The server can be deployed as both a standalone CLI tool and Vercel serverless function

### Environment Setup
- Copy `.env.example` to `.env` and configure MongoDB URI, AWS credentials
- Requires Node.js >= 18

## Architecture Overview

### MCP Server Structure
This is a **Model Context Protocol (MCP) server** for talent management that implements three main tool categories:

1. **Gallery Management** (`gallery-zip-export.ts`) - Export gallery images as ZIP files with S3 storage
2. **Structured Data Search** (`structured-sheets-search.ts`) - MongoDB aggregation queries on talent data  
3. **Vector Search** (`vector-search.ts`) - Semantic document search using AI embeddings

### Key Components

**Server Core (`src/index.ts`)**:
- `TalentMCPServer` class orchestrates all MCP tool handlers
- Uses `@modelcontextprotocol/sdk` for protocol compliance
- Connects to MongoDB and initializes tool instances
- Handles tool registration and request routing

**Data Models (`src/models/`)**:
- `gallery.model.ts` - Gallery folders and images schemas
- `sheet-schema-tracker.model.ts` - Dynamic schema tracking for structured data
- `sheet-vector.model.ts` - Vector embeddings for search
- `document.model.ts` - Document metadata storage

**Services (`src/services/`)**:
- `database.ts` - MongoDB connection management via Mongoose
- `vector-store.ts` - Vector embeddings and similarity search
- `aws.ts` - S3 file upload and management

### Tool Architecture Pattern
Each tool follows this pattern:
- Schema definition with Zod for input validation
- Tool class with main execution method
- Description constant for MCP tool registration
- Error handling with graceful fallbacks

### Database Integration
- **MongoDB** primary database using Mongoose ODM
- **Pinecone** vector database for semantic search
- **AWS S3** for file storage and public URLs
- All data operations use async/await with proper error handling

### Multi-Sheet Query Strategy
For structured searches requiring data from multiple sheets:
1. Identify which sheets contain required fields
2. Execute separate queries per sheet using `structured_sheets_search`
3. Merge results using common identifiers (talent ID, name)
4. All field references must use `originalData.` prefix in aggregation pipelines

### Environment Dependencies
- **MONGODB_URI** - MongoDB connection string
- **AWS_ACCESS_KEY_ID**, **AWS_SECRET_ACCESS_KEY**, **AWS_REGION**, **AWS_S3_BUCKET_NAME** - S3 credentials
- **PINECONE_API_KEY** - Vector database access (implied from imports)

### Deployment Architecture
- **Dual Deployment**: Can run as standalone MCP server or Vercel serverless function
- **Vercel Configuration**: `vercel.json` configures API routes and Node.js 18 runtime
- **Build Process**: TypeScript compilation outputs to `dist/`, then copied to `api/` for Vercel
- **Binary Distribution**: Published as npm package with CLI executable at `dist/index.js`

### Data Flow Architecture
- **MCP Protocol**: Uses stdio transport for Claude integration, HTTP for Vercel
- **Request Pipeline**: Zod validation → Tool execution → JSON response formatting
- **Error Handling**: Centralized error handling with McpError types and graceful fallbacks
- **Database Patterns**: All models use Mongoose with async/await, aggregation pipelines for complex queries