thesven/streamable-mcp-example-typescript

Streamable MCP Example

A simple example of using the Model Context Protocol (MCP) with a client-server architecture, demonstrating tool capabilities and streaming communication.

Features

• MCP server with tool capabilities
• Client with fallback transport mechanisms
• TypeScript implementation
• Express.js server
• Tool execution example (addition)

Prerequisites

• Node.js (v18 or higher)
• pnpm (recommended) or npm

Installation

1. Clone the repository:

git clone <repository-url>
cd streamable-mcp-example

2. Install dependencies:

pnpm install

Development

1. Build the project:

pnpm build

2. Start the server:

pnpm start:server

3. In a separate terminal, run the client:

pnpm start:client

Project Structure

streamable-mcp-example/
├── client/             # Client implementation
│   └── index.ts       # Client entry point
├── server/            # Server implementation
│   └── index.ts       # Server entry point
├── package.json       # Project configuration
├── tsconfig.json      # TypeScript configuration
└── README.md         # This file

Implementation Details

Server

The server implements:

• MCP protocol support
• Tool capability registration
• Request handling
• Express.js integration
• Error handling

Client

The client implements:

• MCP protocol support
• Transport fallback mechanism
• Tool discovery
• Tool execution
• Error handling

Available Tools

Addition Tool

A simple tool that adds two numbers:

{
  name: "tools/addition",
  description: "Add two numbers together",
  parameters: {
    type: "object",
    properties: {
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["a", "b"]
  }
}

BTC Price Tool

A tool that retrieves BTC price data from Yahoo Finance:

{
  name: "tools/getBTCPrices",
  description: "Get BTC price data. Valid ranges: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max. Valid intervals: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo",
  parameters: {
    type: "object",
    properties: {
      timeFrame: {
        type: "string",
        enum: ["1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max"]
      },
      interval: {
        type: "string",
        enum: ["1m", "2m", "5m", "15m", "30m", "60m", "90m", "1h", "1d", "5d", "1wk", "1mo", "3mo"]
      }
    },
    required: ["timeFrame"]
  }
}

• Arguments:
  • timeFrame (required): Range of data (e.g., '1d', '5d', '1mo', etc.)
  • interval (optional): Data interval (e.g., '1m', '5m', '1h', etc.)
• Output:
  • Returns an array of price points (JSON), each with price, volume, high, low, and timestamp fields.
  • Example output:

    [
      { "price": 109715.88, "volume": 123456, "high": 110000, "low": 109000, "timestamp": "2025-05-27T23:59:00.000Z" },
      ...
    ]
    

  • The latest price for the requested range is the last item in the array.

MCP Endpoint & Protocol

• The MCP server exposes its endpoint at: http://localhost:3000/mcp
• Only POST requests are supported. GET/DELETE will return a 405 error.
• The server requires the Accept: application/json header (or includes it in a list).
• The server is compliant with JSON-RPC 2.0 and the Model Context Protocol (MCP).
• Tool calls and tool listing follow the MCP SDK and protocol.

Cursor Integration

To use this server with Cursor:

1. Ensure .cursor/mcp.json exists with the following content:

   {
     "mcpServers": {
       "streamable-mcp-example": {
         "url": "http://localhost:3000/mcp"
       }
     }
   }
   

2. Restart Cursor if it was running.
3. The server's output format is compatible with Cursor and the MCP SDK.

Error Handling

The implementation includes error handling for:

• Connection failures
• Transport fallback
• Invalid requests
• Server errors

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.