MCP Server and Client

This project demonstrates a Model Context Protocol (MCP) Server and Client implementation using TypeScript. The MCP allows AI assistants to securely access external tools, data sources, and services.

What This Project Does

MCP Server (src/server.ts)

Provides three main capabilities:

1. Resources - Data access:

   • users://all - Get all users from the database
   • users://{userId}/profile - Get specific user details

2. Tools - Actions you can perform:

   • create-user - Manually create a new user
   • create-random-user - Generate a fake user with AI

3. Prompts - Templates for AI interactions:

   • generate-fake-user - Generate fake user data based on a name

MCP Client (src/client.ts)

An interactive CLI that connects to the server and allows you to:

• Query: Ask natural language questions using Google's Gemini AI
• Use Tools: Create users manually or with AI
• Access Resources: View user data
• Use Prompts: Generate content with AI assistance

Setup Instructions

1. Install Dependencies

npm install

2. Set up Gemini API Key

1. Get your API key from Google AI Studio
2. Add it to the .env file:

GEMINI_API_KEY=your_actual_api_key_here

3. Build the Project

npm run server:build

Running the Application

Option 1: Run Server and Client Separately

Terminal 1 - Start the Server:

npm run server:dev

Terminal 2 - Start the Client:

npm run client:dev

Option 2: Use the MCP Inspector (Recommended for Testing)

This provides a web-based interface to test your MCP server:

npm run server:inspect

Then open your browser to the provided URL.

Usage Examples

Using the Interactive Client

When you run the client, you'll get a menu with options:

1. Query: Ask natural language questions like:

   • "Show me all users"
   • "Create a new user named John Doe"
   • "Generate a random user"

2. Tools: Directly use server tools:

   • Create users manually by providing name, email, address, phone
   • Generate random users with AI

3. Resources: Browse available data:

   • View all users
   • Get specific user details by ID

4. Prompts: Use AI templates:

   • Generate fake user data based on a name

Example Queries

• "Can you show me all the users in the database?"
• "Create a new user with the name Sarah Connor"
• "Generate 3 random users for testing"
• "Show me details for user ID 1"

Project Structure

├── src/
│   ├── server.ts          # MCP Server implementation
│   ├── client.ts          # Interactive CLI client
│   └── data/
│       └── users.json     # User database (JSON file)
├── build/                 # Compiled JavaScript files
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── .env                  # Environment variables

Available Scripts

• npm run server:dev - Run server in development mode
• npm run server:build - Build TypeScript to JavaScript
• npm run server:build:watch - Build with watch mode
• npm run server:inspect - Run with MCP Inspector
• npm run client:dev - Run the interactive client

Understanding MCP

The Model Context Protocol (MCP) is an open standard that enables secure connections between AI assistants and external data sources. This project demonstrates:

• Resources: Read-only data access (like databases or APIs)
• Tools: Actions the AI can perform (like creating, updating, deleting)
• Prompts: Templates for AI interactions
• Sampling: Allows the server to request AI completions

Features Demonstrated

1. Resource Templates: Dynamic URIs with parameters
2. Tool Execution: Server-side actions with validation
3. AI Integration: Using Google's Gemini for text generation
4. Prompt Templates: Structured AI interactions
5. JSON Schema Validation: Type-safe parameter handling
6. File System Operations: Reading and writing JSON data

Next Steps

Try these enhancements:

1. Add more user fields (avatar, role, created_date)
2. Implement user search and filtering
3. Add user deletion and update tools
4. Connect to a real database instead of JSON
5. Add authentication and authorization
6. Create more complex prompts and workflows

Troubleshooting

• "Module not found" errors: Run npm install and npm run server:build
• API key errors: Make sure your Gemini API key is correctly set in .env
• Connection errors: Ensure the server is running before starting the client
• Permission errors: Check file permissions for src/data/users.json