# MCP Demo Project

## Overview

This project demonstrates how to build and test a Model Context Protocol (MCP) server using Python and FastMCP.

The repository contains:

* `server.py` - MCP Server implemented using FastMCP
* `server.js` - Sample REST API implemented using Express.js
* `client_test.py` - Python client for testing the MCP server
* `requirements.txt` - Python dependencies
* `package.json` - Node.js dependencies (optional)

---

# Architecture

```text
+----------------------+
| MCP Client           |
| (Claude, Cursor,     |
|  Custom Client)      |
+----------+-----------+
           |
           | MCP Protocol
           |
           v
+----------------------+
| server.py            |
| FastMCP Server       |
+----------+-----------+
           |
           | HTTP (Optional)
           |
           v
+----------------------+
| server.js            |
| Express REST API     |
+----------+-----------+
           |
           v
+----------------------+
| Database / Services  |
+----------------------+
```

The MCP server exposes tools, resources, and prompts that AI agents can use.

The Express server demonstrates how an MCP server can interact with existing REST APIs.

---

# Services

## 1. Python MCP Server (`server.py`)

The MCP server runs on:

```text
http://127.0.0.1:8000/mcp
```

### Available Tools

#### add_numbers

Adds two integers.

Example:

```json
{
  "a": 5,
  "b": 7
}
```

Result:

```json
12
```

---

#### get_weather

Returns mock weather information.

Example:

```json
{
  "city": "Hyderabad"
}
```

Result:

```text
The weather in Hyderabad is sunny, 25°C.
```

---

### Available Resources

#### greeting://{name}

Example:

```text
greeting://Jaya
```

Result:

```text
Hello, Jaya! Welcome to MCP.
```

---

### Available Prompts

#### code_review_prompt

Generates a code review prompt.

Input:

```text
public class Test {}
```

Output:

```text
Please review this code and suggest improvements:

public class Test {}
```

---

## 2. Node.js REST Server (`server.js`)

The Express server runs on:

```text
http://localhost:3000
```

### Endpoints

#### Health Check

```http
GET /health
```

Example Response:

```json
{
  "status": "ok",
  "uptime": 123.45
}
```

---

#### Manifest

```http
GET /manifest
```

Returns server metadata.

---

#### Context API

```http
POST /context
```

Request:

```json
{
  "query": "Hello MCP",
  "metadata": {
    "user": "Jaya"
  }
}
```

Response:

```json
{
  "received": {
    "query": "Hello MCP",
    "metadata": {
      "user": "Jaya"
    }
  },
  "response": "MCP server received: Hello MCP"
}
```

---

# Prerequisites

## Python

Verify installation:

```bash
python --version
```

Install dependencies:

```bash
pip install -r requirements.txt
```

---

## Node.js (Optional)

Verify installation:

```bash
node -v
npm -v
```

Install dependencies:

```bash
npm install
```

or

```bash
npm install express
```

---

# Running the Application

## Start the MCP Server

```bash
python server.py
```

Expected Output:

```text
Uvicorn running on http://127.0.0.1:8000
```

---

## Start the Express Server

```bash
node server.js
```

Expected Output:

```text
MCP server listening on http://localhost:3000
```

---

# Testing the MCP Server

## Step 1: Initialize Session

Windows CMD:

```bash
curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}"
```

Copy the returned:

```text
mcp-session-id
```

---

## Step 2: List Available Tools

```bash
curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"2\",\"method\":\"tools/list\"}"
```

---

## Step 3: Call add_numbers Tool

```bash
curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"3\",\"method\":\"tools/call\",\"params\":{\"name\":\"add_numbers\",\"arguments\":{\"a\":5,\"b\":7}}}"
```

Expected Result:

```json
12
```

---

## Step 4: Call get_weather Tool

```bash
curl -v -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" -H "Mcp-Session-Id: <SESSION_ID>" http://127.0.0.1:8000/mcp -d "{\"jsonrpc\":\"2.0\",\"id\":\"4\",\"method\":\"tools/call\",\"params\":{\"name\":\"get_weather\",\"arguments\":{\"city\":\"Hyderabad\"}}}"
```

---

# Testing the Express Server

Health Check:

```bash
curl http://localhost:3000/health
```

Manifest:

```bash
curl http://localhost:3000/manifest
```

Context API:

```bash
curl -X POST http://localhost:3000/context -H "Content-Type: application/json" -d "{\"query\":\"Hello MCP\"}"
```

---

# MCP Concepts Used

### Tool

An executable function exposed to MCP clients.

Examples:

* add_numbers
* get_weather

### Resource

Read-only contextual information.

Example:

* greeting://{name}

### Prompt

Reusable prompt templates exposed to AI clients.

Example:

* code_review_prompt

---

# Learning Objectives

This project demonstrates:

* Building an MCP Server with FastMCP
* Exposing Tools, Resources, and Prompts
* Using Streamable HTTP Transport
* Testing MCP APIs with curl
* Creating a REST API with Express.js
* Integrating MCP with existing backend services
* Understanding MCP architecture and workflows