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        │
                    └──────────────────┘

Related MCP server: MCP Job Matching Server

✨ 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

📁 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.