Sharjeelbaig/MCP-Server

MCP server — minimal example

This repository is a small example MCP server implemented in TypeScript. It demonstrates how to expose simple "tools" and resources using the Model Context Protocol (MCP).

What's in this repo

• server.ts — the MCP server implementation (uses @modelcontextprotocol/sdk and StdioServerTransport).
• package.json — project manifest and dev dependencies.

Prerequisites

• Node.js (v16+ recommended)
• npm (bundled with Node)

Install

Install production and dev dependencies:

npm install

If you want to run the TypeScript file directly you'll also need a runtime helper such as ts-node:

npm install --save-dev ts-node

How this server is intended to run

The server uses a stdio transport (StdioServerTransport) and connects via standard input/output. That makes it suitable to be spawned by an MCP host/inspector or started directly for local testing.

Run options

1. Start the official MCP inspector (project start script):

npm start

This projects start script runs the MCP inspector (npx @modelcontextprotocol/inspector@latest`) so you can inspect and drive the server locally.

2. Run the server directly (recommended for development):

# (ensure ts-node is installed as shown above)
npx ts-node-esm server.ts

If you prefer compilation, add a tsconfig.json, compile with npx tsc, then run the compiled JS with node.

What the server exposes

Tools (name and input shape):

• trackPackage — input: { trackingNumber: string }

  • Returns a simple text response indicating the tracking number being checked.

• getWeather — input: { city: string }

  • Returns a small JSON-like payload with temp and forecast, or an error when the city is unsupported.

Resources (URI -> content):

• flights://airports — plain text list of supported airport codes (JFK, LAX, ORD).
• weather://cities — plain text list of supported cities (New York, London).

Quick test notes

• Running npx ts-node-esm server.ts will start the server and connect it to stdio. Use the MCP inspector (see npm start) to drive the server in a local development loop.
• The server writes startup/debug lines to stderr (these are visible in the terminal).

Example JSON payloads (for reference)

• trackPackage input:

{ "trackingNumber": "ABC123" }

• getWeather input:

{ "city": "London" }

Troubleshooting

• If npx ts-node-esm server.ts fails: install ts-node (dev dependency) or compile with tsc.
• If npm start does not show the inspector UI, verify you have network access for npx and that the inspector package is reachable.

Next steps you might want

• Add a tsconfig.json and a short dev script that runs the server with a file watcher (e.g., ts-node-dev).
• Add unit tests for each tool handler and a small integration test that spawns the server and sends MCP messages over stdio.
• Add documentation for connecting an MCP client to this server.

If you'd like, I can also:

• add a tsconfig.json and dev script (quick), or
• add an example client snippet that talks to this server over stdio.

This README was updated to reflect the actual project files (server.ts and package.json) and to point to the MCP getting-started docs as the source of the example design.