MCP Server Client

A complete implementation of the Model Context Protocol (MCP) demonstrating a bidirectional server-client architecture with AI integration. This project showcases how to build scalable, protocol-based communication systems with tool invocation, resource management, and prompt handling.

📋 Overview

This repository contains two main components:

• MCP Server: Exposes tools, resources, and prompts via the Model Context Protocol
• MCP Client: Interactive CLI client that communicates with the server and integrates Google Gemini for intelligent query handling

The project demonstrates practical patterns for building AI-augmented applications using standardized protocols.

✨ Features

Server Features

• Tools: Callable functions that perform specific operations

  • create-user: Create users with name, email, address, and phone
  • get_github_repos: Fetch public repositories from a GitHub user
  • create-random-user: Generate random user data using AI

• Resources: Queryable data sources with support for templated URIs

  • expenses://all: Access all expenses data
  • expenses://daily-total/{month}/{day}: Query daily expense totals by month and day

• Prompts: Pre-configured AI prompts for common tasks

  • explain_sql_query: Generate detailed explanations of SQL queries

• Bidirectional Communication: Server can send sampling requests back to the client

Client Features

• Interactive CLI Menu: Navigate tools, resources, and prompts easily
• AI Integration: Google Gemini API integration for intelligent responses
• Dynamic Input Handling: Automatically generates input prompts based on tool/resource requirements
• Query System: Submit natural language queries that leverage server tools

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• Google Gemini API key

Installation

# Clone the repository
git clone https://github.com/surojcodes/mcp-server-client.git
cd mcp-server-client

# Install dependencies
npm install

Configuration

Create a .env file in the root directory:

GEMINI_API_KEY=your_gemini_api_key_here

Building

# Build the TypeScript files
npm run server:build

# Or watch for changes during development
npm run server:build:watch

Running

# Start the server (in one terminal)
npm run server:inspect

# Start the client in another terminal
npm run client:dev

📖 Usage

Once the client connects to the server, you'll see an interactive menu:

What do you want to do?
  ❯ Query
    Tools
    Prompts
    Resources
    Resource Templates

Using Tools

1. Select "Tools" from the menu
2. Choose a tool from the list
3. Provide input values as prompted
4. View the tool's response

Querying Resources

1. Select "Resources" from the menu
2. Choose a resource or resource template
3. For templated resources, provide parameter values
4. View the resource data (formatted as JSON)

Using Prompts

1. Select "Prompts" from the menu
2. Choose a prompt
3. Provide any required arguments
4. Review the prompt and confirm to run it with Gemini

Natural Language Queries

1. Select "Query" from the menu
2. Enter a natural language question
3. The AI model processes your query using available tools
4. View the generated response

🏗️ Project Structure

mcp-server-client/
├── src/
│   ├── server.ts           # MCP Server implementation
│   ├── client.ts           # MCP Client implementation
│   └── data/
│       ├── users.json      # User data storage
│       └── expenses.json   # Expense data storage
├── dist/                   # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

🔧 Development

Scripts

• npm run server:build - Compile TypeScript to JavaScript
• npm run server:build:watch - Watch TypeScript files and recompile on changes
• npm run server:inspect - Run server with MCP Inspector for debugging
• npm run client:dev - Run the client CLI

Debugging

Use the MCP Inspector to debug the server:

npm run server:inspect

This opens a browser interface to inspect server state and test tools/resources.

📦 Dependencies

Runtime

• @modelcontextprotocol/sdk - MCP protocol implementation
• @ai-sdk/google - Google Generative AI integration
• ai - AI utilities and text generation
• @inquirer/prompts - Interactive CLI prompts
• dotenv - Environment variable management
• zod - TypeScript-first schema validation

Development

• typescript - TypeScript compiler
• tsx - TypeScript executor for Node.js
• @types/node - Node.js type definitions
• @modelcontextprotocol/inspector - MCP Inspector tool

🤖 AI Integration

The client uses Google's Gemini API for:

• Processing natural language queries
• Generating random user data for testing
• Explaining SQL queries through prompts
• Intelligent context-aware responses

📝 Data Management

User Data (src/data/users.json)

Stores created users with:

• id: Unique identifier
• name: User's full name
• email: User's email address
• address: User's physical address
• phone: User's phone number

Expense Data (src/data/expenses.json)

Stores expenses organized by month with:

• date: Day of the month
• description: Expense description
• amount: Expense amount

🔐 Security Notes

• The DANGEROUSLY_OMIT_AUTH=true flag in the inspector command disables authentication for development only
• Never use this flag in production
• Always protect your Gemini API key
• Validate and sanitize all user inputs

🎓 Learning Resources

This project demonstrates:

• Protocol-based client-server architecture
• Tool invocation and resource management
• AI model integration with TypeScript
• Interactive CLI design patterns
• Bidirectional RPC communication

📄 License

MIT

👤 Author

surojcodes@gmail.com

🤝 Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

---

Happy coding! 🚀