mcp-tutorial

# MCP Tutorial [](https://github.com/modelcontextprotocol/typescript-sdk) This tutorial project provides examples of stateless and stateful server and client implementations using the Model Context Protocol (MCP). ## Overview The Model Context Protocol (MCP) is a protocol designed to standardize communication with AI models. This project offers examples of server and client implementations using the new communication method of MCP called Streamable HTTP Transport. Streamable HTTP Transport is a communication method that uses Server-Sent Events (SSE) format for responses from the server to the client, featuring the following characteristics: - Sending messages from the client to the server via HTTP POST requests - Returning responses from the server to the client in Server-Sent Events (SSE) format - Communicating through a single endpoint (usually `/mcp`) - Session management functionality (optional) - Reconnection mechanism - Support for backward compatibility In this tutorial, you will learn about two implementation approaches: 1. **Stateless Mode**: The server does not maintain a session with the client, and each request is processed independently. 2. **Stateful Mode**: The server maintains a session with the client and retains state. ## Features - **Implementation of Stateless Server and Client** - Simple implementation without session management - Easy horizontal scaling - Independent request processing - **Implementation of Stateful Server and Client** - State management using session IDs - Retaining session state through an event store - Contextual conversations maintaining dialogue - **Frontend Implementation** - Modern frontend using Next.js - State management through React components - Styling with TailwindCSS - **Sample Tool** - Implementation example of a dice tool - Basic patterns for tool registration and execution ## Prerequisites - **Node.js**: v18.0.0 or higher - **npm**: v8.0.0 or higher - **TypeScript**: v5.0.0 or higher ## Installation ### Clone the Repository ```bash git clone https://github.com/yourusername/mcp-tutorial.git cd mcp-tutorial ``` ### Setup Stateless Server and Client ```bash cd stateless npm install ``` ### Setup Stateful Server and Client ```bash cd stateful npm install ``` ### Setup Frontend ```bash cd stateful/frontend npm install ``` ## Usage ### Start Stateless Server ```bash cd stateless npm run dev ``` The server will start at `http://localhost:3000/mcp`. ### Run Stateless Client ```bash cd stateless npm run dev:client ``` ### Start Stateful Server ```bash cd stateful npm run dev ``` The server will start at `http://localhost:3000/mcp`. ### Run Stateful Client ```bash cd stateful npm run dev:client ``` ### Start Frontend ```bash cd stateful/frontend npm run dev ``` The frontend will start at `http://localhost:8080`. ## Basic Operations ### Command Line Client 1. Use the `list-tools` command to retrieve the list of tools provided by the server. 2. Use the `call-tool` command to execute the dice tool (specifying the number of sides). 3. For stateful clients, use the `terminate-session` command to end the session. 4. Use the `exit` command to terminate the client. ### Frontend Client 1. Click the "Get Tool List" button to display the list of tools provided by the server. 2. Specify the number of sides in the dice tool and click the "Roll Dice" button. 3. For stateful mode, use the "End Session" button to terminate the session. ## Project Structure ``` mcp-tutorial/ ├── stateless/ # Stateless implementation │ ├── client/ # Command line client │ ├── server/ # Stateless server │ └── frontend/ # Simple HTML frontend │ └── stateful/ # Stateful implementation ├── client/ # Command line client ├── server/ # Stateful server └── frontend/ # Next.js frontend ``` ### Key Components - **MCP Server**: Registers tools and processes requests from clients. - **Transport**: Handles communication between the client and server. - **Event Store**: Retains session state in stateful mode. - **Tools**: Functions provided by the server (e.g., dice). - **Client**: Application that invokes the server's tools. ## Technology Stack ### Server Side - **Express.js**: HTTP server framework - **TypeScript**: Type-safe development language - **MCP SDK**: Implementation of the Model Context Protocol - **Zod**: Schema validation ### Client Side - **TypeScript**: Type-safe development language - **MCP SDK**: Implementation of the Model Context Protocol ### Frontend - **Next.js**: React framework - **React**: UI library - **TailwindCSS**: Utility-first CSS framework