MCP-client-server-demo by Shreedhar73 - MCP Server

Explain Chat MCP

A Model Context Protocol (MCP) server implementation with HTTP streaming capabilities, built with TypeScript and Express. This project demonstrates how to create an MCP server that can communicate with AI clients over HTTP using streaming responses.

What is MCP?

The Model Context Protocol (MCP) is a standard for AI assistants to communicate with external data sources and tools. This implementation provides:

HTTP Streaming Transport: Real-time communication between clients and the MCP server
Session Management: Persistent sessions with resumability support
Tool Integration: Easy-to-use tool registration and calling system
Express Integration: Built on top of Express.js for easy deployment

Features

✅ HTTP streaming transport for real-time communication
✅ Session persistence and resumability
✅ Tool registration and execution
✅ Express.js server integration
✅ TypeScript support
✅ Docker support (coming soon)

Prerequisites

Node.js 18+
npm or yarn
TypeScript knowledge (for development)

Installation

Clone the repository:

git clone <repository-url>
cd explain-chat-mcp

Install dependencies:

npm install

Build the TypeScript code:

npm run build

Running the Server

Development Mode

Start the MCP server in development mode:

npm run server

The server will start on port 3000 by default. You can change this by setting the PORT environment variable:

PORT=8080 npm run server

Production Mode

For production, build the project first:

npm run build
npm run server

Running the Client

The project includes a test client that demonstrates how to connect to the MCP server:

npm run client

This will start a client that connects to the MCP server and provides a simple HTTP API on port 4000.

API Endpoints

MCP Server (Port 3000)

POST /mcp - Handle MCP requests (client-to-server)
GET /mcp - Server-sent events for server-to-client communication
DELETE /mcp - Terminate MCP sessions

Test Client API (Port 4000)

GET /greet?name=<name> - Test the greeting tool

Available Tools

The server currently includes:

greet - A simple greeting tool that takes a name parameter and returns a personalized greeting

Adding New Tools

To add new tools, modify the server setup in src/index.ts:

server.tool(
  "your-tool-name",
  "Description of your tool",
  {
    // Define your tool parameters using Zod schemas
    param1: z.string().describe("Description of param1"),
    param2: z.number().describe("Description of param2"),
  },
  async ({ param1, param2 }): Promise<CallToolResult> => {
    // Your tool implementation here
    return {
      content: [
        {
          type: "text",
          text: `Your tool result: ${param1}, ${param2}`,
        },
      ],
    };
  }
);

Testing

The project includes several test scripts:

# Test the MCP server
npm test

# Test the API endpoints
npm run test:api

# Test the MCP client
npm run test:client

Development

Project Structure

src/
├── index.ts              # Main server entry point
├── client/
│   └── mcp-client.ts     # Test client implementation
├── server/
│   └── server_runner.ts  # Express server setup
└── methods/              # Custom MCP methods (empty for now)

Key Components

ExpressHttpStreamableMcpServer: Main server factory function
StreamableHTTPServerTransport: Handles HTTP streaming transport
McpServer: Core MCP server implementation
InMemoryEventStore: Provides session resumability

Environment Variables

PORT - Server port (default: 3000)

Docker Support

A Dockerfile is included for containerized deployment:

# Build the Docker image
docker build -t explain-chat-mcp .

# Run the container
docker run -p 3000:3000 explain-chat-mcp

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

ISC License

Troubleshooting

Common Issues

Port already in use: Change the PORT environment variable
TypeScript compilation errors: Run npm run build to check for type errors
Connection refused: Ensure the server is running before starting the client

Debug Mode

Enable debug logging by setting the DEBUG environment variable:

DEBUG=* npm run server

Shreedhar73/MCP-client-server-demo