# Sample MCP Server

This is a complete, minimal Model Context Protocol (MCP) server written in TypeScript. It runs locally, uses the official MCP TypeScript SDK, and exposes exactly three tools:

- `sayHello`
- `addNumbers`
- `getCurrentTime`

The goal is learning. The code is intentionally small, commented, and direct.

## What MCP Is

Model Context Protocol is a standard way for AI applications to connect to external tools and context.

Without MCP, every app invents its own custom way to call tools. With MCP, a host such as ChatGPT can talk to an MCP server using a shared protocol.

An MCP server can expose:

- Tools: actions the model can call
- Resources: data the model can read
- Prompts: reusable prompt templates

This project exposes only tools.

## How This Project Works

This server uses the local `stdio` transport.

That means ChatGPT starts the server as a child process and communicates with it through standard input and standard output:

- ChatGPT writes JSON-RPC messages to the server's stdin.
- The server reads those messages with the MCP SDK.
- The SDK routes tool calls to our TypeScript functions.
- The server writes JSON-RPC responses back to stdout.

There is no HTTP server, no Express app, no database, no authentication, and no cloud service.

## How ChatGPT Discovers Tools

When ChatGPT connects to an MCP server, it performs an initialization handshake. After that, it asks the server which tools are available.

The MCP SDK answers with each tool's:

- Name
- Description
- Input schema

For example, `addNumbers` tells ChatGPT that it needs two numeric inputs named `a` and `b`.

## How Tool Execution Works

When ChatGPT decides to call a tool, it sends a JSON-RPC request containing:

- The tool name
- The tool arguments
- A request id so the response can be matched

The MCP SDK receives the request, validates the shape using the tool schema, and calls the matching TypeScript function.

The function returns an MCP tool result. In this project, results are text content blocks. `addNumbers` returns JSON as formatted text so it is easy to read.

## JSON-RPC Message Flow

The message flow looks like this:

```text
ChatGPT starts: node build/index.js
ChatGPT -> server: initialize
server -> ChatGPT: server name, version, capabilities
ChatGPT -> server: list tools
server -> ChatGPT: sayHello, addNumbers, getCurrentTime
ChatGPT -> server: call addNumbers with { "a": 2, "b": 3 }
server -> ChatGPT: { "result": 5 }
```

You usually do not write JSON-RPC code by hand. The SDK handles it.

## Folder Structure

```text
sample-mcp/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts
    ├── server.ts
    ├── tools/
    │   ├── hello.ts
    │   ├── math.ts
    │   └── time.ts
    └── types.ts
```

## File Guide

### `package.json`

Defines the project name, dependencies, and scripts.

Important scripts:

- `npm run build` compiles TypeScript into `build/`.
- `npm start` runs the compiled MCP server.

### `tsconfig.json`

Configures TypeScript.

This project uses `NodeNext` module settings because the MCP SDK is designed for modern ES modules.

### `src/index.ts`

The entry point.

It creates the server, creates the stdio transport, and connects them.

This file also catches startup errors and writes them to stderr. For stdio MCP servers, stdout must be reserved for JSON-RPC messages.

### `src/server.ts`

Creates the `McpServer` instance and registers all tools.

Keeping this separate from `index.ts` makes the transport setup easy to understand.

### `src/tools/hello.ts`

Registers the `sayHello` tool.

Input:

```json
{
  "name": "Ada"
}
```

Output:

```text
Hello Ada!
```

### `src/tools/math.ts`

Registers the `addNumbers` tool.

Input:

```json
{
  "a": 2,
  "b": 3
}
```

Output:

```json
{
  "result": 5
}
```

### `src/tools/time.ts`

Registers the `getCurrentTime` tool.

It accepts no input and returns the local date and time from your computer.

### `src/types.ts`

Contains tiny helper functions for returning MCP tool results and formatting validation errors.

This keeps the tool files readable without adding a large abstraction layer.

## Install Dependencies

From the project folder:

```bash
cd sample-mcp
npm install
```

Node.js 18 or newer is required.

## Build the Server

```bash
npm run build
```

This compiles TypeScript from `src/` into JavaScript in `build/`.

## Run the Server

```bash
npm start
```

The server will appear to wait silently. That is normal.

An MCP stdio server does not print normal logs to stdout because stdout is reserved for JSON-RPC messages.

## Connect It To ChatGPT

Use ChatGPT's MCP connector settings and add a local stdio server.

Use a command like this:

```bash
node D:\github\mcp\sample-mcp\build\index.js
```

If your path contains spaces, wrap it in quotes.

ChatGPT will start the command, initialize the MCP connection, discover the three tools, and call them when useful.

## How To Add A New Tool

1. Create a new file in `src/tools/`.
2. Define a Zod input schema.
3. Export a function that receives `server: McpServer`.
4. Call `server.registerTool(...)`.
5. Import and call your registration function in `src/server.ts`.

Example shape:

```ts
export function registerExampleTool(server: McpServer): void {
  server.registerTool(
    "exampleTool",
    {
      title: "Example Tool",
      description: "Explain what this tool does.",
      inputSchema: {
        value: z.string(),
      },
    },
    async (input) => {
      const parsed = schema.parse(input);
      return textResult(parsed.value);
    },
  );
}
```

## Common Errors And Fixes

### `node` is not recognized

Install Node.js 18 or newer, then reopen your terminal.

Check your version:

```bash
node --version
```

### Cannot find module

Dependencies are missing.

Run:

```bash
npm install
```

### TypeScript build fails

Run the build from inside the project folder:

```bash
cd sample-mcp
npm run build
```

### ChatGPT does not show the tools

Make sure you built the project first:

```bash
npm run build
```

Then make sure ChatGPT points to the compiled file:

```bash
node D:\github\mcp\sample-mcp\build\index.js
```

### The server prints nothing

That is expected for stdio MCP servers.

Normal text on stdout would break JSON-RPC communication, so this server only writes startup errors to stderr.

### Invalid input

The tools use Zod validation. If a value has the wrong type, the tool returns a meaningful error result instead of crashing the server.

## Tools Included

### `sayHello`

Input:

```json
{
  "name": "Grace"
}
```

Output:

```text
Hello Grace!
```

### `addNumbers`

Input:

```json
{
  "a": 10,
  "b": 5
}
```

Output:

```json
{
  "result": 15
}
```

### `getCurrentTime`

Input:

```json
{}
```

Output:

```text
7/21/2026, 10:30:00 PM
```

The exact format depends on your operating system locale.