MCP Server - MyPostmanServer

A lightweight Model Context Protocol (MCP) server built with Node.js that exposes custom tools via HTTP/SSE for clients like Postman.

Overview

This project implements an MCP server that communicates with external clients using Server-Sent Events (SSE) over HTTP. It demonstrates how to:

Create and register custom tools
Validate input parameters with Zod
Establish bidirectional communication with MCP clients
Handle tool invocations and return formatted responses

Features

Custom Tools: Defines a greet tool that clients can invoke
Type-Safe Validation: Uses Zod for runtime parameter validation
SSE Transport: Full-duplex communication over HTTP without WebSockets
Express Server: Lightweight HTTP server for handling client connections

Project Structure

.
├── index.js              # Main MCP server implementation
├── package.json          # Project dependencies and metadata
├── package-lock.json     # Dependency lock file
├── .gitignore            # Git ignore rules
└── README.md             # This file

Prerequisites

Node.js 16+ (with ES module support)
npm or yarn for package management

Installation

Clone the repository:

git clone https://github.com/gunjankum06/mcp.git
cd mcp

Install dependencies:

npm install

Usage

Starting the Server

node index.js

You should see:

🚀 Server ready at http://localhost:3000/sse

Connecting a Client

MCP clients (like Postman, Claude, or custom applications) can connect to the server:

Initiate Connection: Make a GET request to http://localhost:3000/sse
Stream will open: The server establishes a persistent SSE connection
Call Tools: Send requests to http://localhost:3000/message to invoke tools

Available Tools

`greet`

Greets a person by name.

Parameters:

name (string, required): The name of the person to greet

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Hello {name}! MCP is running on your laptop."
    }
  ]
}

Example:

POST http://localhost:3000/message
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "John"
    }
  }
}

Architecture

Components

MCP Server (McpServer)
- Core component that manages tool definitions and processing
- Exposes tools to connected clients
- Handles tool invocations
SSE Transport (SSEServerTransport)
- Manages HTTP streaming connection with clients
- Handles bidirectional message exchange
- Routes /message callbacks back to the server
Express API
- /sse (GET): Endpoint for client connection initialization
- /message (POST): Endpoint for receiving client messages

Communication Flow

Client                          Server
  |                               |
  |---- GET /sse ------->         |
  |                      Create SSE Transport
  |                      Connect MCP Server
  |<----- SSE Stream ----         |
  |                               |
  |---- POST /message ------>     |
  |  (tool call request)  Process Request
  |                               |
  |<----- Response -------        |
  |  (tool response)              |

Dependencies

@modelcontextprotocol/sdk: MCP protocol implementation
express: HTTP server framework
zod: Schema validation library

Configuration

The server is configured in index.js with:

Server Name: MyPostmanServer
Server Version: 1.0.0
Port: 3000

To modify these, edit the corresponding values in the code.

Error Handling

Invalid tool parameters are caught by Zod schema validation
Missing transport connections are handled gracefully in the /message route
The server continues running even if individual tool calls fail

Development

Adding New Tools

To add a new tool, use the server.tool() method:

server.tool(
  "toolName",
  { param1: z.string(), param2: z.number() },
  async ({ param1, param2 }) => ({
    content: [{ type: "text", text: `Result: ${param1} ${param2}` }]
  })
);

Running in Development

For development with auto-reload, install nodemon:

npm install --save-dev nodemon
nodemon index.js

Troubleshooting

Port Already in Use

If port 3000 is already in use, modify the port number in index.js:

app.listen(YOUR_PORT, () => {
  console.log(`🚀 Server ready at http://localhost:YOUR_PORT/sse`);
});

Client Connection Issues

Ensure the server is running before connecting clients
Check that the client is using the correct endpoint URL
Verify that SSE is supported by your client

Tool Not Found

Ensure tools are registered before the server starts listening
Check tool names match exactly (case-sensitive)
Verify input parameters match the defined schema

Resources

License

MIT

Author

gunjankum06 - GitHub user

MyPostmanServer