# MCP Server and Client Example (TypeScript)

This project demonstrates the creation and interaction of a simple Model Context Protocol (MCP) server and a standalone MCP client using TypeScript and the `@modelcontextprotocol/sdk`.

The setup includes:
1.  **`my-mcp-greeter-server`**: An MCP server that provides greeting-related tools, resources, and prompts.
2.  **`my-mcp-client-script`**: A simple command-line client script that launches the server, connects to it, and interacts with its capabilities programmatically.

Communication between the client and server in this example uses the **stdio (standard input/output)** transport mechanism.

## Overview of the Process Followed

This project was built following these main phases:

1.  **Server Development**: Creating the MCP service provider.
2.  **Client Development**: Creating a script to consume the server's services.
3.  **Testing & Interaction**: Running the client script, which launches the server and demonstrates communication.
4.  **(Optional) Integration**: Discussing how to integrate the server with existing MCP clients like VS Code extensions.

## Prerequisites

Before you begin, ensure you have the following installed:
*   [Node.js](https://nodejs.org/) (v16 or higher recommended)
*   [npm](https://www.npmjs.com/) (usually included with Node.js)
*   A text editor or IDE (like VS Code)
*   `npx` (usually included with npm) - useful for testing with MCP Inspector.

## Phase 1: Building the MCP Server (`my-mcp-greeter-server`)

1.  **Project Setup**:
    *   Created the directory `my-mcp-greeter-server`.
    *   Initialized an npm project: `npm init -y`.
    *   Installed necessary dependencies: `npm install @modelcontextprotocol/sdk zod`.
    *   Installed development dependencies: `npm install -D typescript @types/node`.
    *   Initialized TypeScript configuration: `npx tsc --init`.
    *   Configured `tsconfig.json` (setting `"module": "Node16"`, `"target": "ES2022"`, `"outDir": "./build"`, `"rootDir": "./src"`, etc.).
    *   Updated `package.json` to include `"type": "module"` and added `build`/`start` scripts.
    *   Created the source file `src/index.ts`.

2.  **Server Implementation (`src/index.ts`)**:
    *   Imported required modules (`McpServer`, `StdioServerTransport`, `z`).
    *   Defined constants for server `name` and `version`.
    *   Instantiated `McpServer`, passing the name, version, and declaring its capabilities (tools, resources, prompts).
    *   **Defined a Tool (`greet`)**: Used `server.tool()` to create a function callable by clients. Included a description, defined input parameters with Zod (`name`, `politeness`), and implemented the handler to return a personalized greeting string.
    *   **Defined a Resource (`server-info`)**: Used `server.resource()` to expose static data. Provided a unique URI (`info://greeter/about`) and implemented the handler to return the server's name and version.
    *   **Defined a Prompt (`suggest-greeting`)**: Used `server.prompt()` to create a reusable interaction template. Included a description and implemented the handler to return a predefined set of user/assistant messages to guide an LLM interaction.
    *   **Used Stdio Transport**: Instantiated `StdioServerTransport` as the communication method.
    *   **Connected**: Called `await server.connect(transport)` to make the server ready.
    *   **Logging**: Added `console.error` statements for visibility during execution, especially important for stdio transport where stdout is used for protocol messages.
    *   **Kept Alive**: Ensured the Node.js process didn't exit immediately after connection.

3.  **Building & Fixing**:
    *   Ran `npm run build` to compile TypeScript to JavaScript in the `build` directory.
    *   Fixed a TypeScript error related to accessing server version directly, opting to use predefined constants instead.

## Phase 2: Building the MCP Client Script (`my-mcp-client-script`)

1.  **Project Setup**:
    *   Created a separate directory `my-mcp-client-script`.
    *   Initialized an npm project: `npm init -y`.
    *   Installed necessary dependencies: `npm install @modelcontextprotocol/sdk`.
    *   Installed development dependencies: `npm install -D typescript @types/node`.
    *   Initialized and configured `tsconfig.json` similarly to the server project.
    *   Updated `package.json` with `"type": "module"` and `build`/`start` scripts.
    *   Created the source file `src/client-script.ts`.

2.  **Client Implementation (`src/client-script.ts`)**:
    *   Imported required modules (`Client`, `StdioClientTransport`, `path`, `url`).
    *   **Determined Server Path**: Calculated the path to the *server's* compiled `index.js` file (relative or absolute).
    *   **Configured Stdio Transport**: Instantiated `StdioClientTransport`, providing the `command` (`node`) and `args` (the path to the server script). *This configuration is key, as the client transport launches the server process.*
    *   **Instantiated Client**: Created a `Client` instance, giving it an identity and declaring its intent to use tools and resources.
    *   **Connected**: Called `await client.connect(transport)`, which launched the server process and established the MCP connection over its stdio streams.
    *   **Interacted with Server**:
        *   Called the `greet` tool using `await client.callTool()`.
        *   Read the `server-info` resource using `await client.readResource()`.
        *   Fetched the `suggest-greeting` prompt using `await client.getPrompt()`.
    *   **Logged Results**: Used `console.log` to display the responses received from the server.
    *   **Closed Connection**: Used `await client.close()` in a `finally` block to cleanly shut down the connection and terminate the server process.

## Phase 3: Building and Running

1.  **Build Both Projects**:
    *   `cd my-mcp-greeter-server && npm run build`
    *   `cd ../my-mcp-client-script && npm run build`

2.  **Run the Client**:
    *   `cd my-mcp-client-script`
    *   `npm run start` (or `node build/client-script.js`)
    *   Observed the interleaved output from both the client (`console.log`) and the server (`console.error`), confirming successful communication and execution of tools/resources/prompts.

## Explanation of Roles

*   **The Server (`GreeterServer`)**:
    *   **Provides Services**: Exposes specific capabilities (greeting tool, server info, prompt template).
    *   **Passive Listener (in stdio)**: Waits for a client to connect via its standard streams.
    *   **Executes Logic**: Runs the code associated with a tool/resource/prompt when requested by the client.
    *   **Sends Results**: Formats results according to MCP specs and sends them back to the client.

*   **The Client (`client-script.ts`)**:
    *   **Consumes Services**: Uses the capabilities offered by the server.
    *   **Initiator (in stdio)**: Launches the server process and establishes the connection.
    *   **Sends Requests**: Decides which tool to call, resource to read, or prompt to get, and sends the appropriate MCP request.
    *   **Receives Results**: Processes the responses sent back by the server.
    *   **Controls Flow**: Manages the sequence of interactions and decides when to close the connection.

## Testing the Server Interactively

While the client script tests the programmatic interaction, you can test the server's capabilities individually using the MCP Inspector:

```bash
# Make sure the server is NOT already running
# Replace /path/to/... with the actual absolute path
npx @modelcontextprotocol/inspector node /path/to/my-mcp-greeter-server/build/index.js