mcp-stateful-example

stevemadere/mcp-stateful-example

3.2

If you are the rightful owner of mcp-stateful-example and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

This project provides a minimal, fully MCP-compliant server and client setup for exploring and validating session-based tool invocation workflows using the Model Context Protocol (MCP).

Tools

  1. imagine

    Picks a random number between the specified lower and upper bounds and stores it in the session.

  2. isLessThan

    Checks if a number is less than the previously imagined number in the current session.

MCP Stateful Example

A minimal, fully MCP-compliant server and client setup for exploring and validating session-based tool invocation workflows using the Model Context Protocol (MCP).

Features

  • Toy Stateful MCP Server: Implements a minimal MCP server with session handling
  • Test Tools: Includes imagine and isLessThan tools for testing session state
  • Integration Tests: Python-based tests for validating server behavior and session persistence
  • Health Check: Built-in /health endpoint for monitoring server status

Prerequisites

  • Node.js 18+
  • Python 3.8+ (for integration tests)
  • npm or yarn

Getting Started

  1. Clone the repository
  2. Install Node.js dependencies: 
    npm install
  3. Install Python dependencies for integration tests: 
    pip install -r test/integration/requirements.txt
  4. Create a .env.test file in the project root with the following content: 
    PORT=3088
  5. Start the development server: 
    npm run dev

Running Tests

Unit Tests

npm test

Integration Tests

# Run all integration tests
npm run itest

# Or run a specific test
cd test/integration
python test_initialize.py

Project Structure

  • src/ - Source code
    • server/ - MCP server implementation
      • tools/ - Tool definitions
    • client/ - Test client implementation
  • test/ - Test files
    • integration/ - Python-based integration tests
  • scripts/ - Build and utility scripts

Available Tools

imagine

Picks a random number between the specified lower and upper bounds and stores it in the session.

Parameters:

  • lower: Lower bound (inclusive)
  • upper: Upper bound (inclusive)

isLessThan

Checks if a number is less than the previously imagined number in the current session.

Parameters:

  • number: Number to compare against the imagined number

API Endpoints

GET /health

Health check endpoint that returns server status.

POST /mcp

Main MCP protocol endpoint for handling MCP-compliant requests.

Environment Variables

  • PORT: Port number the server will listen on (default: 3000)
  • NODE_ENV: Environment mode (e.g., 'development', 'production')

License

ISC