Skip to main content
Glama

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

Related MCP server: Resume MCP Server

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

Available Tools

17 tools
analyze_githubA

Analyze a student's public GitHub profile.

Args:
    student_id: The student's UUID.

Returns:
    GitHub analysis including repositories, languages, and activity.

Inputs: student_id (required). Returns: result

analyze_leetcodeA

Analyze a student's public LeetCode profile.

Args:
    student_id: The student's UUID.

Returns:
    LeetCode analysis including problems solved and topic distribution.

Inputs: student_id (required). Returns: result

analyze_portfolioA

Analyze a student's portfolio website.

Args:
    student_id: The student's UUID.

Returns:
    Portfolio analysis including projects and technologies found.

Inputs: student_id (required). Returns: result

analyze_resumeA

Analyze a student's resume (PDF text extraction and structuring).

Args:
    student_id: The student's UUID.

Returns:
    Resume analysis results including extracted skills and experience.

Inputs: student_id (required). Returns: result

analyze_studentA

Run the full analysis pipeline for a student.

Analyzes resume, GitHub, LeetCode, and portfolio in parallel
where possible. Records analysis runs for auditing.

Args:
    student_id: The student's UUID.

Returns:
    Analysis results summary with status for each component.

Inputs: student_id (required). Returns: result

get_data_quality_reportA

Get a data quality report across all imported student data.

Reports on missing fields, invalid URLs, format issues,
and overall data completeness.

Returns:
    Data quality metrics and recommendations.

Inputs: no named parameters. Returns: result

get_import_statusA

Get the status and statistics of a data import operation.

Args:
    import_id: The UUID of the import to check.

Returns:
    Import status including row counts and any error details.

Inputs: import_id (required). Returns: result

get_profile_completenessA

Get the profile completeness score for a student.

Returns a percentage score and breakdown by section
(education, skills, projects, resume, GitHub, etc.).

Args:
    student_id: The student's UUID.

Returns:
    Completeness score and section-by-section breakdown.

Inputs: student_id (required). Returns: result

get_profile_statisticsA

Get aggregate statistics across all student profiles.

Includes CGPA distribution, skill coverage, project counts,
internship rates, and certification coverage.

Returns:
    Formatted statistics report.

Inputs: no named parameters. Returns: result

get_skill_distributionA

Get the distribution of skills across the student cohort.

Shows which skills are most common, least common, and
how skills cluster by category.

Returns:
    Skill distribution report.

Inputs: no named parameters. Returns: result

get_skill_evidenceA

Get the evidence map for a student's skills.

Shows each skill with its evidence sources (resume, GitHub, projects, etc.)
and evidence strength (declared_only, weak_evidence, strong_evidence).

Args:
    student_id: The student's UUID.

Returns:
    Structured skill evidence report.

Inputs: student_id (required). Returns: result

get_skill_gapsA

Get skill gaps identified for a student.

Shows missing, weakly evidenced, and declared-but-unverified skills.

Args:
    student_id: The student's UUID.

Returns:
    Skill gap analysis with recommendations.

Inputs: student_id (required). Returns: result

get_studentA

Retrieve a student's profile by their UUID.

Args:
    student_id: The student's UUID.

Returns:
    Student profile information including name, email, roll number.

Inputs: student_id (required). Returns: result

import_excelA

Import student data from an Excel (.xlsx) file.

Runs the full pipeline: validate → map columns → normalize →
detect duplicates → persist to database → report statistics.

Args:
    file_path: Absolute path to the .xlsx file on the server filesystem.

Returns:
    Import result with statistics (total, successful, failed, duplicate rows).

Inputs: file_path (required). Returns: result

list_studentsA

List all students with pagination.

Args:
    page: Page number (default: 1).
    page_size: Items per page (default: 20, max: 100).

Returns:
    Paginated list of students with total count.

Inputs: page, page_size. Returns: result

search_studentsA

Search for students by name (partial, case-insensitive match).

Args:
    name: Partial name to search for (optional).
    page: Page number (default: 1).
    page_size: Items per page (default: 20, max: 100).

Returns:
    List of matching students with their basic information.

Inputs: name, page, page_size. Returns: result

validate_excelA

Validate an Excel (.xlsx) file structure without importing data.

Checks file format, detects columns, maps to schema fields,
and reports any ambiguous or missing columns.

Args:
    file_path: Absolute path to the .xlsx file on the server filesystem.

Returns:
    Validation result including detected columns, mapping, and warnings.

Inputs: file_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: component analyzers target different platforms, aggregate reports target different metrics, and student queries differ by lookup method. The pipeline analyzer subsumes the individual analyzers without ambiguity, and import/validation/status tools are clearly separated.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern (analyze_*, get_*, import_*, validate_*, search_*, list_*), with no mixed conventions or arbitrary names. This makes the tool surface predictable and easy to navigate.

    Tool Count4/5

    At 17 tools, the server is slightly on the heavier side but still well-scoped: the import pipeline (validate/import/status), analysis pipeline (full + component analyzers), and reporting tools each serve distinct needs. The count feels appropriate for the domain, though a couple of tools could theoretically be merged.

    Completeness4/5

    The tool set covers the full workflow: importing data, validating it, running individual component analyses, generating aggregate statistics, and inspecting per-student details like skill evidence, gaps, and completeness. Minor gaps exist (no update/delete for student records, no export tool), but these are peripheral to the analysis-focused purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers