engineers-hub-ltd-in-house-project/minimal-mcp

Minimal MCP

A minimal implementation of Model Context Protocol (MCP) server and client for educational and development purposes.

Project Structure

minimal-mcp/
├── server/          # MCP Server (TypeScript)
├── client/          # MCP Client (Python)
└── README.md

Prerequisites

• Node.js 22+
• Python 3.13+
• TypeScript

Server Setup

Install Dependencies

cd server
npm install

Build Server

npm run build

Test Server

npm run inspector

Open the URL shown in the terminal (typically http://localhost:6274/) to test the server tools.

Client Setup

Create Virtual Environment

cd client
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

Install Dependencies

pip install -r requirements.txt

Configure Environment

Create .env file with your OpenAI API key:

echo "OPENAI_API_KEY=your_openai_api_key_here" > .env

Run Client

python client.py

Available Tools

The MCP server provides three tools:

1. calculate_sum: Adds two numbers

   • Parameters: a (number), b (number)
   • Example: calculate_sum(42, 58) → 100

2. reverse_string: Reverses a text string

   • Parameters: text (string)
   • Example: reverse_string('Hello MCP') → 'PCM olleH'

3. get_current_time: Returns current ISO timestamp

   • Parameters: none
   • Example: get_current_time() → '2025-08-24T01:52:39.749Z'

Usage Methods

Method 1: Direct Client Testing

Run the Python client to test all tools:

cd client
python client.py

This will automatically:

1. Connect to the MCP server
2. Execute all three tools with sample data
3. Display results

Method 2: Claude Code Integration

Add MCP server to Claude Code configuration:

{
  "mcpServers": {
    "minimal-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/minimal-mcp/server/build/index.js"]
    }
  }
}

Then use in Claude Code:

Using the minimal-mcp tools:
1. Calculate the sum of 123 and 456
2. Reverse the text "Model Context Protocol"
3. Get the current time

Method 3: MCP Inspector

Use the official MCP inspector for interactive testing:

cd server
npm run inspector

Open the URL shown in the terminal to test tools interactively in the browser.

Development

Server Development

cd server
npm run watch  # Auto-rebuild on changes

Adding New Tools

Edit server/src/index.ts to add new tools:

1. Add tool definition to the tools array:

{
  name: "your_tool_name",
  description: "Description of what the tool does",
  inputSchema: {
    type: "object",
    properties: {
      param: { type: "string", description: "Parameter description" }
    },
    required: ["param"]
  }
}

2. Add tool handler in the CallToolRequestSchema switch case:

case "your_tool_name":
  const { param } = args as { param: string };
  // Your tool logic here
  return {
    content: [
      {
        type: "text",
        text: `Result: ${param}`
      }
    ]
  };

3. Rebuild the server:

npm run build

Troubleshooting

Permission Denied

chmod +x server/build/index.js

Inspector Port Issues

The inspector automatically finds available ports. If you see different port numbers in the output (e.g., proxy on 6277, web UI on 6274), this is normal. Use the URL shown in the terminal output.

Module Not Found

Check Node.js version and ensure all dependencies are installed:

node --version  # Should be 22+
npm install

Architecture

System Overview

graph TB
    subgraph "Claude Code Environment"
        CC[Claude Code]
        MCP_CLIENT[MCP Client]
    end

    subgraph "Minimal MCP Server"
        SERVER[MCP Server Process]
        TOOLS[Tool Handlers]
        subgraph "Available Tools"
            CALC[calculate_sum]
            REV[reverse_string]
            TIME[get_current_time]
        end
    end

    subgraph "Communication Layer"
        STDIO[stdio Transport]
    end

    CC --> MCP_CLIENT
    MCP_CLIENT <--> STDIO
    STDIO <--> SERVER
    SERVER --> TOOLS
    TOOLS --> CALC
    TOOLS --> REV
    TOOLS --> TIME

    style CC fill:#3b82f6,color:#fff
    style SERVER fill:#10b981,color:#fff
    style STDIO fill:#f59e0b,color:#fff

Sequence Diagram

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Client as MCP Client
    participant Server as Minimal MCP Server
    participant Tool as Tool Handler

    Note over User,Tool: Tool Discovery & Registration
    User->>Claude: Start Claude Code
    Claude->>Client: Initialize MCP Client
    Client->>Server: Connect via stdio
    Server->>Client: Send available tools list
    Client->>Claude: Register tools

    Note over User,Tool: Tool Execution Flow
    User->>Claude: "Calculate 42 + 58"
    Claude->>Client: Call calculate_sum(42, 58)
    Client->>Server: Tool execution request
    Server->>Tool: Execute calculate_sum
    Tool->>Tool: Process: 42 + 58 = 100
    Tool->>Server: Return result
    Server->>Client: Send response
    Client->>Claude: Return tool result
    Claude->>User: Display: "The sum of 42 and 58 is 100"

    Note over User,Tool: Error Handling
    User->>Claude: "Invalid request"
    Claude->>Client: Invalid tool call
    Client->>Server: Send invalid request
    Server->>Client: Return error
    Client->>Claude: Handle error
    Claude->>User: Display error message

Demo

Installation and Setup

Method 1: Claude Code Integration

Add the MCP server directly to Claude Code:

claude mcp add minimal-mcp-server minimal-mcp-server

Method 2: Global npm Installation

Install globally and configure manually:

# Install the package globally
npm install -g minimal-mcp-server

# Then add to Claude Code configuration manually
# (or use other MCP-compatible clients)

Manual configuration for Claude Code:

{
  "mcpServers": {
    "minimal-mcp-server": {
      "command": "minimal-mcp-server"
    }
  }
}

Live Test Results

Here are actual test results from Claude Code integration:

1. Calculate Sum

Input: calculate_sum(42, 58)
Output: "The sum of 42 and 58 is 100"

2. Reverse String

Input: reverse_string("Hello MCP World")
Output: "Reversed text: dlroW PCM olleH"

3. Get Current Time

Input: get_current_time()
Output: "Current time: 2025-08-24T02:19:17.244Z"

Python Client Test

You can also test with the included Python client:

cd client
python client.py

Example output:

🚀 Initializing MCP agent and connecting to services...
✅ Created 1 new sessions
🧠 Agent ready with tools: calculate_sum, reverse_string, get_current_time
🔧 Tool call: calculate_sum with input: {'a': 42, 'b': 58}
📄 Tool result: The sum of 42 and 58 is 100
🔧 Tool call: reverse_string with input: {'text': 'Hello MCP'}
📄 Tool result: Reversed text: PCM olleH
🔧 Tool call: get_current_time with input: {}
📄 Tool result: Current time: 2025-08-24T02:16:40.654Z

License

MIT