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)

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

# 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