# CodeChef VIT Papers MCP Server

A standalone Model Context Protocol (MCP) server that exposes the CodeChef VIT papers portal's data to MCP-compatible AI clients (Claude Desktop, Cursor, VS Code Copilot, etc.). It connects directly to the portal's MongoDB database in **read-only** mode, allowing AI assistants to query university question papers, retrieve full metadata, and fetch feeds of recently added papers.

> [!IMPORTANT]
> This server operates purely in **read-only** mode. It does not contain any write or upload capabilities, authentication flows, or external HTTP server interfaces. It communicates strictly via standard input/output (`stdio`) transport.

## Features

- **Tool: `search_papers`**: Search for university question papers using filters like subject (matches both subject name or course code, e.g., "BCSE202P" or "Data Structures"), year, exam type, branch, and campus. Results are capped at 20 documents, displaying a total count notice if more matches exist.
- **Tool: `get_paper_metadata`**: Fetch the complete metadata details for a specific question paper using its database ID.
- **Resource: `recent-papers`**: Access a read-only JSON feed of the last 10 papers added to the database.

---

## Input Validation & Rate Limiting

### Input Validation (Zod)
All tool inputs are validated strictly using Zod before any database queries are executed:
- **`search_papers`**:
  - `subject`: Optional string.
  - `year`: Optional 4-digit integer between `1000` and `9999` (e.g. `2023`).
  - `exam`: Optional enum matching known exam types: `CAT-1`, `CAT-2`, `FAT`, `Model CAT-1`, `Model CAT-2`, `Model FAT`.
  - `branch`: Optional enum matching known branch types: `CSE`, `ECE`.
  - `campus`: Optional enum matching known campuses: `Vellore`, `Chennai`, `Andhra Pradesh`, `Bhopal`, `Bangalore`, `Mauritius`.
- **`get_paper_metadata`**:
  - `paperId`: Required 24-character hexadecimal MongoDB ObjectId string.

If validation fails, the server responds with a clear MCP error before calling MongoDB.

### Rate Limiting
To prevent abuse, the server implements an in-memory **Token Bucket** rate limiter scoped per session (the stdio connection process):
- **Limit**: Max 30 tool calls per minute.
- **Behavior**: Exceeding the rate limit returns a clean MCP error response (no crash) and logs the event to `console.error`.

---

## Setup Instructions

### Prerequisites

- Node.js (v18 or higher recommended)
- npm (v9 or higher)
- A read-only MongoDB URI for the portal's database (never use production write credentials)

### Installation

1. Clone or navigate to the repository directory:
   ```bash
   cd d:/VIT/Club/papserMCP_server
   ```

2. Install the dependencies:
   ```bash
   npm install
   ```

3. Create your environment configuration file:
   Copy `.env.example` to `.env` and fill in your read-only database URI:
   ```bash
   cp .env.example .env
   ```
   Edit `.env`:
   ```env
   MONGODB_URI_READONLY="mongodb+srv://<username>:<password>@cluster.mongodb.net/Papers-staging?retryWrites=true&w=majority"
   ```

---

## Build and Run

To compile the TypeScript source into production-ready JavaScript code:

```bash
# Build the project
npm run build

# Run the server locally (it will wait for stdio inputs)
npm run start
```

For development mode (automatically re-compile files as they change):
```bash
npm run dev
```

---

## Wiring into Claude Desktop

To expose this MCP server to Claude Desktop, add the server to your Claude Desktop configuration file.

### Configuration Path
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

### JSON Configuration Snippet

Add the following snippet under `mcpServers`. Make sure to replace the `env.MONGODB_URI_READONLY` with your actual read-only database credentials:

```json
{
  "mcpServers": {
    "codechefvit-papers-mcp": {
      "command": "node",
      "args": [
        "d:/VIT/Club/papserMCP_server/dist/index.js"
      ],
      "env": {
        "MONGODB_URI_READONLY": "mongodb+srv://<readonly-user>:<password>@cluster.mongodb.net/Papers-staging?retryWrites=true&w=majority"
      }
    }
  }
}
```

> [!TIP]
> On Windows, you can use forward slashes `/` in the file path as shown above, or escape backslashes like `"D:\\VIT\\Club\\papserMCP_server\\dist\\index.js"`.

---

## Try Asking Claude

Once successfully connected, you can ask Claude Desktop questions like:

- *"Can you check if there are any CAT-1 papers for Data Structures [BCSE202P] from the Vellore campus?"*
- *"Find me Vellore campus papers from the year 2023."*
- *"Can you show me the full metadata for the paper with ID 60d5ecb867c2e022f4b2f123?"*
- *"List the last 10 question papers added to the portal."*

---

## License

This repository is maintained privately for the CodeChef VIT chapter.