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.

Related MCP server: TypeScript MCP Server Boilerplate

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v16 or higher recommended)

• npm (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:

# 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