Demo MCP Basic

This project demonstrates a fundamental client-server interaction using the Model Context Protocol (MCP). MCP allows AI models, like those accessed via the AI SDK (e.g., Google Gemini/Vertex AI), to securely discover and utilize external tools or resources provided by a separate server process.

In this example:

• The Server (`src/server/`) acts as an MCP provider, offering simple calculation tools (addition, subtraction, etc.).
• The Client (`src/client/`) uses the AI SDK to interact with a Google AI model and connects to the MCP server to make the server's tools available to the AI during generation.

This setup illustrates how you can extend the capabilities of AI models by giving them access to custom functionalities hosted on an MCP server.

Prerequisites

• Node.js (Version >=23.0.0 as specified in `package.json`)
• npm (comes with Node.js)
• A Google AI (Gemini) API Key. You can obtain one from Google AI Studio. (Required for using Gemini models).

Setup

1. Clone the repository:

git clone git@github.com:bertrandgressier/demo-ts-mcp-client-server.git
    cd demo-mcp-basic

2. Install dependencies:

npm install

3. Create Environment File:

Copy the example environment file `.env.example` to a new file named `.env`:

cp .env.example .env

Then, edit the `.env` file to add your actual API keys and configuration. The required and optional variables are:

# Required for Google Studio Models (Gemini)
    GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY

    # Required for Google Vertex AI Models
    VERTEX_PROJECT_ID=YOUR_VERTEX_PROJECT_ID

    # Optional: Defaults to 'us-central1' if not set
    # VERTEX_LOCATION=your-vertex-location

    # Optional: Path to Vertex AI service account key file. Defaults to 'vertex-key.json' in the root if not set.
    # VERTEX_KEY_FILE=path/to/your/vertex-key.json

_Replace `YOUR_GOOGLE_API_KEY` and `YOUR_VERTEX_PROJECT_ID` with your actual credentials._

_If you use a Vertex AI key file, ensure it's placed correctly (e.g., in the root as `vertex-key.json` or provide the correct path in `VERTEX_KEY_FILE`)._

Available Scripts

• Build TypeScript:

npm run build

Compiles TypeScript code from `src` to JavaScript in `dist`.

• Start Production Server:

npm run start
  # or specifically
  npm run start:server

Builds the project (if not already built) and runs the compiled server from `dist/server/server.js`.

• Start Production Client:

npm run start:client

Runs the compiled client from `dist/client/client.js`.

• Run Server in Development Mode:

npm run dev:server

Runs the server directly using `ts-node` (or similar via `--experimental-transform-types`) without needing a separate build step.

• Run Server in Development Mode with Watch:

npm run dev:server:watch

Runs the server using `nodemon`, automatically restarting it when changes are detected in the `src/server` directory.

• Run Client in Development Mode:

npm run dev:client

Runs the client directly using `ts-node` (or similar).

Example Client (`src/client/client.ts`)

The primary example client script demonstrates the following:

1. Connects to the MCP Server: Establishes a connection to the locally running MCP server (expected at `http://localhost:3001/sse`).

2. Fetches Tools: Retrieves the list of tools made available by the connected server.

3. Configures AI Model: Uses the AI SDK (`generateText`) configured with a Google AI model (Gemini via API Key or Vertex AI, depending on environment variables set in `.env` and potentially `src/models/google-ai-provider.ts`).

4. Executes Prompt: Sends a prompt (`6 + 12`) along with a system message instructing the AI to use the fetched tools to solve the calculation.

5. Outputs Result: Prints the final text response generated by the AI model after potentially using the server-provided tools.

This client serves as a basic illustration of how an application can interact with an MCP server to leverage its tools within an AI generation flow.

Project Structure

• `src/`: Contains the TypeScript source code.
  • `client/`: Code for the MCP client application.
  • `server/`: Code for the MCP server application.
  • `model.ts`: Handles AI model initialization and environment variable loading.
• `dist/`: Contains the compiled JavaScript code (after running `npm run build`).
• `.env`: Stores environment variables (API keys, etc.) - Do not commit this file.
• `package.json`: Project metadata and dependencies.
• `tsconfig.json`: TypeScript compiler configuration.