Candidate Eval API

A lightweight backend service for evaluating candidates against job requirements using FastAPI, asynchronous Python, and MCP (Model Context Protocol).

The project demonstrates how to build a production-style AI/backend service where the same evaluation capabilities can be accessed through both REST APIs and MCP tools.

🎯 Project Overview

Candidate Eval API simulates an AI-powered candidate evaluation system.

A client can submit a candidate and job information, trigger an evaluation, and retrieve the evaluation result through REST APIs.

An AI agent can perform similar operations through MCP tools.

                    ┌──────────────────┐
                    │      Client      │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │     FastAPI      │
                    │   REST APIs      │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │ Evaluation       │
                    │ Service          │
                    │                  │
                    │ Async Processing │
                    └────────┬─────────┘
                             ▲
                             │
                    ┌────────┴─────────┐
                    │   MCP Server     │
                    │                  │
                    │ MCP Tools        │
                    └──────────────────┘

✨ Key Features

• REST APIs built with FastAPI
• Asynchronous request processing using asyncio
• Concurrent execution using asyncio.gather()
• Custom FastAPI middleware
• Request ID and processing-time tracking
• Pydantic request/response validation
• In-memory evaluation storage
• MCP server with evaluation tools
• Shared business logic between REST APIs and MCP
• Basic automated testing with pytest

🛠️ Tech Stack

Technology	Purpose
Python	Application development
FastAPI	REST API framework
Pydantic	Data validation
asyncio	Asynchronous/concurrent processing
MCP	AI-agent tool interface
pytest	Testing
HTTPX	API testing

📁 Repository Structure

candidate-eval-api/
│
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI application and REST endpoints
│   ├── models.py        # Pydantic models
│   ├── service.py       # Evaluation business logic
│   ├── middleware.py    # Request middleware
│   └── mcp_server.py    # MCP server and tools
│
├── tests/
│   └── __init__.py      # Test package
│
├── requirements.txt
├── README.md
└── .gitignore

The application follows a simple separation of concerns:

API Layer
    ↓
Service Layer
    ↓
Data / Storage

Both FastAPI and MCP are intended to use the same service layer rather than duplicating business logic.

🚀 Getting Started

1. Clone the repository

git clone <repository-url>
cd candidate-eval-api

2. Create a virtual environment

Windows

python -m venv .venv
.venv\Scripts\activate

Linux / macOS

python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Start the FastAPI application

uvicorn app.main:app --reload

The API will be available at:

http://127.0.0.1:8000

Interactive API documentation:

http://127.0.0.1:8000/docs

🔌 REST API

The application exposes endpoints for managing candidate evaluations.

Create Evaluation

POST /evaluations

Example request:

{
  "candidate_id": "C001",
  "job_id": "J100",
  "skills": [
    "python",
    "fastapi",
    "aws"
  ]
}

Get Evaluation

GET /evaluations/{evaluation_id}

Run Evaluation

POST /evaluations/{evaluation_id}/run

Run Batch Evaluation

POST /evaluations/{evaluation_id}/run-batch

API behavior and implementation are intentionally evolving as the project is developed.

🤖 MCP Interface

The project also exposes candidate evaluation functionality through MCP.

Planned tools include:

evaluate_candidate

Evaluates a candidate against a job and returns an evaluation result.

get_evaluation

Retrieves an existing candidate evaluation.

The MCP interface allows an AI agent to interact with the evaluation service using structured tools rather than directly calling REST endpoints.

⚡ Async Processing

The evaluation workflow demonstrates asynchronous processing.

Independent evaluation operations such as:

Skill Analysis
Resume Analysis
Experience Analysis

can execute concurrently using:

asyncio.gather()

This allows independent I/O-bound operations to execute concurrently instead of sequentially.

🧩 Middleware

Custom middleware is used to provide request-level observability.

Each response can include:

X-Request-ID
X-Process-Time

Example log:

GET /evaluations/E001 - 200 - 0.023s

This provides a foundation for request tracing and performance monitoring.

🧪 Testing

Tests are implemented using pytest.

Run the test suite with:

pytest

🗺️ Future Improvements

Potential extensions include:

• Persistent database storage
• Authentication and authorization
• Redis-based caching
• Background task processing
• Evaluation queues
• Retry and timeout handling
• Structured logging
• Docker containerization
• CI/CD pipeline
• More comprehensive test coverage
• Real LLM-based candidate evaluation
• Additional MCP resources and tools

📌 Project Status

🚧 Work in Progress

This project is being developed incrementally to demonstrate practical backend engineering, asynchronous Python, FastAPI, and MCP integration patterns.