# Minimal MCP Demo

This is a very small Model Context Protocol (MCP) example.

The goal is to show the basic architecture in the simplest possible way:

- a server exposes tools
- a client calls those tools
- both communicate over stdio

---

## Architecture

### 1. Server
The server is the part that knows how to do work.

In this project, the server:

- creates an MCP server instance
- registers a tool named `get_weather`
- waits for incoming requests

The server code is in:

- [src/server.ts](src/server.ts)
- [src/index.ts](src/index.ts)

### 2. Tool
A tool is a function the server exposes to the client.

Here, the tool is called `get_weather`.

When the client calls it, the server:

- reads the input (`city`, optional `country`)
- creates a fake weather response
- returns the result as structured data and text

### 3. Client
The client is the part that asks the server to do something.

It:

- starts the server as a child process
- sends a `tools/call` request
- prints the result

The client code is in:

- [src/client.ts](src/client.ts)

### 4. Stdio transport
`stdio` means standard input/output.

This is the communication channel used by the MCP server and client.

In simple terms:

- the client writes a request to the server's stdin
- the server reads it
- the server writes the response to stdout
- the client reads the response

This is why the server uses:

```ts
const transport = new StdioServerTransport();
await server.connect(transport);
```

and the client uses:

```ts
const transport = new StdioClientTransport({
  command: "node",
  args: ["build/index.js"],
});
```

---

## Request flow

Here is the full flow in one simple sequence:

1. Client launches the server
2. Client sends `tools/call` for `get_weather`
3. Server receives the request
4. Server runs the tool function
5. Server returns text + JSON data
6. Client prints the response

### Sequence diagram

```mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Tool

    Client->>Server: Launch process over stdio
    Client->>Server: tools/call { name: "get_weather", arguments: { city, country } }
    Server->>Tool: Execute get_weather
    Tool-->>Server: Return weather result
    Server-->>Client: JSON response with content + structuredContent
    Client->>Client: Print result
```

---

## Files in this project

- [src/server.ts](src/server.ts) - server implementation
- [src/index.ts](src/index.ts) - server entry point
- [src/client.ts](src/client.ts) - client implementation
- [package.json](package.json) - scripts to build and run

---

## Run the demo

Install dependencies:

```bash
npm install
```

Build the project:

```bash
npm run build
```

Run the server:

```bash
npm start
```

Then, in another terminal, run the client:

```bash
npm run client
```

You should see a successful `get_weather` response.

---

## Normal client-server vs MCP

A normal client-server app usually looks like this:

- client sends an HTTP request to a server
- server is already running on a port like `3000`
- server responds with JSON
- both sides communicate over the network

An MCP server is different:

- the server is usually a local process
- the client launches it and communicates over stdio
- the server exposes tools, not general web endpoints
- the client sends MCP protocol messages like `tools/call`

### Simple comparison

| Pattern | Normal app | MCP app |
| --- | --- | --- |
| Transport | HTTP / REST | stdio or streamable HTTP |
| Server role | Service | Tool provider |
| Lifecycle | Long-running service | Often started on demand |
| Main purpose | Business API | Expose actions to an AI client |

### In one sentence

A normal client-server app is built for app-to-app communication, while an MCP server is built for AI/host-to-tool communication.

---

## Mental model

Think of it like this:

- Server = worker
- Tool = job the worker can do
- Client = person asking the worker to do the job
- Stdio = the communication pipe between them

That is the architecture of a basic MCP server.