# Placement Analyzer MCP

Production-grade **Model Context Protocol (MCP)** server for analyzing student placement profiles.  
Designed for college placement cells that receive student data in bulk and need structured, evidence-backed intelligence.

## Architecture

```
MCP Tool
   ↓
Application Service
   ↓
Domain / Business Logic
   ↓
Repository
   ↓
PostgreSQL
```

### Data Flow

```
Excel (.xlsx)
     ↓
Validation → Column Mapping → Normalization → Duplicate Detection
     ↓
PostgreSQL
     ↓
Intelligence Engine (Resume, GitHub, LeetCode, Portfolio)
     ↓
Evidence System → Skill Gaps → Profile Completeness
     ↓
     ↓
MCP Tools & Resources
     ↓
College-wide Placement Analytics (Supply/Demand, Competitiveness)

## Quick Start

### Prerequisites

- Python 3.12+
- Docker & Docker Compose (for local PostgreSQL)

### Setup

```bash
# Clone the repository
git clone https://github.com/mr-sanjai-offl/talentlens-mcp.git
cd talentlens-mcp

# Create environment file
cp .env.example .env

# Start PostgreSQL
docker compose up postgres -d

# Install dependencies (using uv)
uv sync --all-extras

# Or using pip
pip install -e ".[dev]"

# Run database migrations
alembic upgrade head

# Start the MCP server
python -m placement_analyzer.mcp.server
```

### Docker Compose (Full Stack)

```bash
docker compose up --build
```

## MCP Tools

| Group | Tool | Status |
|-------|------|--------|
| **Ingestion** | `validate_excel` | Phase 2 |
| | `import_excel` | Phase 2 |
| | `get_import_status` | Phase 2 |
| **Students** | `get_student` | ✅ Active |
| | `search_students` | ✅ Active |
| | `list_students` | ✅ Active |
| **Analysis** | `analyze_student` | Phase 3 |
| | `analyze_resume` | Phase 3 |
| | `analyze_github` | Phase 3 |
| | `analyze_leetcode` | Phase 3 |
| | `analyze_portfolio` | Phase 3 |
| **Intelligence** | `get_skill_evidence` | Phase 4 |
| | `get_skill_gaps` | Phase 4 |
| | `get_profile_completeness` | Phase 4 |
| **Analytics** | `get_profile_statistics` | Phase 4 |
| | `get_skill_distribution` | Phase 4 |
| | `get_data_quality_report` | Phase 4 |
| **Decision** | `generate_candidate_report` | Phase 7 |
| | `get_placement_readiness` | Phase 7 |
| | `analyze_company` | Phase 7 |
| | `analyze_cohort` | Phase 7 |
| | `simulate_job_requirement` | Phase 7 |
| **Copilot** | `explain_candidate` | Phase 7 |
| | `explain_ranking_position` | Phase 7 |
| | `ask_talentlens` | Phase 7 |
| **Analytics (V2)** | `get_college_overview` | Phase 8 |
| | `get_skill_analytics` | Phase 8 |
| | `get_department_analytics` | Phase 8 |
| | `get_company_supply_analysis` | Phase 8 |
| | `get_skill_supply_demand` | Phase 8 |
| | `get_company_competitiveness` | Phase 8 |

## MCP Resources

| URI | Description |
|-----|-------------|
| `student://{id}` | Full student profile |
| `student://{id}/profile` | Completeness & status |
| `student://{id}/skills` | Skills with evidence |
| `student://{id}/evidence` | Full evidence tree |

## Project Structure

```
src/placement_analyzer/
├── core/          # Errors, enums, types, logging
├── config/        # Pydantic settings
├── database/      # Models, repositories, engine
├── schemas/       # Pydantic request/response models
├── ingestion/     # Excel parsing, validation, normalization
├── intelligence/  # Resume, GitHub, LeetCode, Portfolio analysis
├── services/      # Business logic orchestration
└── mcp/           # MCP server, tools, resources
```

## Development

```bash
# Run tests
pytest -v

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `postgresql+asyncpg://...` | Async database URL |
| `DATABASE_POOL_SIZE` | `5` | Connection pool size |
| `LOG_LEVEL` | `INFO` | Logging level |
| `LOG_FORMAT` | `console` | `json` or `console` |
| `GITHUB_TOKEN` | — | GitHub API token (optional) |
| `MAX_UPLOAD_SIZE_MB` | `50` | Max upload file size |

## Technology Stack

- **Python** 3.12+ with strict typing
- **MCP SDK** v2 (`MCPServer`)
- **SQLAlchemy** 2.x (async) + **asyncpg**
- **Alembic** for migrations
- **Pydantic** 2.x for validation
- **structlog** for structured logging
- **Docker** for deployment

## License

MIT