Model Context Protocol (MCP) Demo Application

A comprehensive demonstration of the Model Context Protocol (MCP) - a standardized protocol that enables AI assistants to interact with external tools and data sources.

🎯 What is Model Context Protocol?

The Model Context Protocol is an open protocol that enables seamless integration between AI applications and external data sources. It provides:

🔧 Tools: Functions that AI can execute (e.g., calculations, API calls)
📚 Resources: Data sources that AI can read (e.g., files, databases)
💬 Prompts: Pre-defined prompt templates for consistent interactions
🔒 Security: Controlled access with clear boundaries

✨ Features

This demo application showcases:

MCP Server

Implements 5 different tools
Provides 2 data resources
Includes prompt templates
Full TypeScript type safety

Tools Implemented

calculate - Perform mathematical calculations
get_weather - Get weather information (simulated)
store_note - Store notes with tags
retrieve_notes - Search and retrieve notes
generate_uuid - Generate unique identifiers

Resources Available

system-info - Current system statistics
notes-list - All stored notes

Interactive Web Interface

Beautiful, modern UI
Real-time tool execution
Resource visualization
Live result display

🚀 Quick Start

Prerequisites

Node.js 18+
npm or yarn

Installation

# Clone or navigate to the project directory
cd model-context-protocol

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Running the Application

Option 1: Web Interface (Recommended)

Start the interactive web interface:

npm run web

Then open your browser to:

http://localhost:3000

The web interface provides:

Visual list of all available tools
Interactive form to call tools
Real-time result display
Resource browser

Option 2: Command Line Client

Run the demo client that showcases all features:

npm run client

This will:

Connect to the MCP server
List all available tools and resources
Execute sample tool calls
Display results in the terminal

Option 3: Server Only

Run just the MCP server (for integration with other clients):

npm run server

📁 Project Structure

model-context-protocol/
├── src/
│   ├── server/
│   │   ├── index.ts       # MCP server implementation
│   │   └── types.ts       # TypeScript type definitions
│   ├── client/
│   │   └── index.ts       # Demo client implementation
│   └── web/
│       ├── server.ts      # Express web server
│       └── public/
│           └── index.html # Web interface
├── dist/                  # Compiled JavaScript (after build)
├── package.json
├── tsconfig.json
└── README.md

🎮 Usage Examples

Using the Web Interface

Start the web server: npm run web
Open http://localhost:3000 in your browser
Click on any tool in the left panel to auto-fill the form
Modify arguments as needed
Click "Execute Tool" to see results

Example Tool Calls

Calculate Expression

{
  "tool": "calculate",
  "arguments": {
    "expression": "(10 + 5) * 2"
  }
}

Result: 30

Get Weather

{
  "tool": "get_weather",
  "arguments": {
    "location": "San Francisco",
    "unit": "celsius"
  }
}

Result: Weather data for San Francisco

Store a Note

{
  "tool": "store_note",
  "arguments": {
    "title": "Project Ideas",
    "content": "Build an MCP-powered application",
    "tags": ["ideas", "projects", "mcp"]
  }
}

Result: Note stored with unique ID

Retrieve Notes

{
  "tool": "retrieve_notes",
  "arguments": {
    "query": "project"
  }
}

Result: All notes matching "project"

Generate UUID

{
  "tool": "generate_uuid",
  "arguments": {}
}

Result: A new UUID like 550e8400-e29b-41d4-a716-446655440000

Reading Resources

System Information

URI: mcp://demo/system-info

Returns current system stats including OS, memory, CPU info, and uptime.

Notes List

URI: mcp://demo/notes-list

Returns all notes stored in the system.

🏗️ How It Works

1. Server Initialization

The MCP server registers available tools and resources:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "calculate",
      description: "Perform mathematical calculations",
      inputSchema: { /* JSON Schema */ }
    }
  ]
}));

2. Client Connection

The client connects to the server via stdio transport:

const client = new Client({ name: "demo-client", version: "1.0.0" });
const transport = new StdioClientTransport({ command: "node", args: ["server.js"] });
await client.connect(transport);

3. Tool Discovery

The client discovers available capabilities:

const tools = await client.request({ method: "tools/list" }, ListToolsResultSchema);

4. Tool Execution

The client calls a tool with parameters:

const result = await client.request({
  method: "tools/call",
  params: {
    name: "calculate",
    arguments: { expression: "2 + 2" }
  }
}, CallToolResultSchema);

5. Resource Access

The client reads data resources:

const resource = await client.request({
  method: "resources/read",
  params: { uri: "mcp://demo/system-info" }
}, ReadResourceResultSchema);

🛠️ Development

Build the Project

npm run build

Development Mode

npm run dev

This will build and start the web interface.

Project Scripts

npm run build - Compile TypeScript to JavaScript
npm run server - Run the MCP server
npm run client - Run the demo client
npm run web - Start the web interface
npm run dev - Build and run web interface

🎨 Architecture

MCP Server (src/server/index.ts)

Implements the MCP protocol
Registers tools and resources
Handles requests from clients
Validates input using Zod schemas
Returns structured responses

MCP Client (src/client/index.ts)

Connects to the MCP server
Discovers available capabilities
Executes tools and reads resources
Displays results

Web Server (src/web/server.ts)

Express-based HTTP server
Proxies requests to MCP server
Provides REST API endpoints
Serves static web interface

Web Interface (src/web/public/index.html)

Modern, responsive design
Interactive tool execution
Real-time result display
Resource browser

🔑 Key MCP Concepts

Tools

Functions that can be executed by AI assistants. Each tool has:

Name: Unique identifier
Description: What the tool does
Input Schema: JSON Schema defining required/optional parameters
Handler: Implementation that processes requests

Resources

Data sources that can be read. Each resource has:

URI: Unique identifier (e.g., mcp://demo/system-info)
Name: Human-readable name
Description: What data it provides
MIME Type: Data format (e.g., application/json)

Prompts

Pre-defined prompt templates that:

Can accept parameters
Provide consistent interaction patterns
Help structure AI conversations

🌟 Benefits of MCP

Standardization - Common protocol for AI-tool integration
Security - Controlled, explicit access to capabilities
Flexibility - Easy to add new tools and resources
Discoverability - AI can discover available capabilities
Type Safety - Strong typing with JSON Schema validation
Interoperability - Works with any MCP-compatible client

📚 Technologies Used

TypeScript - Type-safe development
@modelcontextprotocol/sdk - Official MCP SDK
Node.js - Runtime environment
Express - Web server framework
Zod - Runtime type validation

🔗 Resources

📝 License

MIT

🤝 Contributing

This is a demo application for learning purposes. Feel free to:

Extend it with new tools
Add more resources
Improve the UI
Add tests
Create documentation

💡 Next Steps

To build your own MCP server:

Define your tools and their schemas
Implement tool handlers
Add resources for data access
Create prompt templates
Test with MCP clients
Deploy and integrate with AI applications

Built with ❤️ to demonstrate the power of Model Context Protocol

MCP Demo Application