MCP Server with Tool, Resource, Prompt, and Sampling

A full-featured Model Context Protocol (MCP) server built with Node.js and TypeScript. This project demonstrates how to implement and integrate the core capabilities of MCP into a single server, communicating over stdio.

🚀 Features

This server showcases the four main pillars of the Model Context Protocol:

• Resources (users://all): Exposes local data to the LLM. It safely reads from src/data/users.json using node:fs so the LLM can analyze existing user data.
• Tools (create-user): Allows the LLM to take action by securely writing new user data to the local file system with strict validation via zod.
• Sampling (create-random-user): Demonstrates server-to-client LLM requests. When triggered, the server uses the sampling/createMessage endpoint to ask the client LLM to generate fake user data, parses the response, and automatically saves it.
• Prompts: Configured to support structured prompt templates that guide the LLM's interactions with the provided tools and resources.

🛠️ Prerequisites

• Node.js: v20 or higher (Tested on v24)
• Package Manager: yarn or npm

📦 Installation

1. Clone the repository and navigate to the directory:

   cd mcp-server-sampling
   

   Install dependencies:

   yarn install
   

   (Ensure @modelcontextprotocol/sdk and zod are installed).

Initialize the data file: Ensure you have an empty or valid JSON array in src/data/users.json:

JSON:🏗️ Build & Run

Because this project uses modern ES Modules (ESM) and is strictly typed, you must build the project before connecting it to an MCP client like VS Code.

Compile the TypeScript code to JavaScript:

Bash yarn build (This outputs the compiled code to the /build directory).

(Optional) Test the server locally using the MCP Inspector:

npx @modelcontextprotocol/inspector node build/server.js

🔌 VS Code Configuration

To connect this server to VS Code (or Cursor/Claude Desktop), you need to register it in your client's MCP settings.

For VS Code, update your configuration (usually found in your MCP settings file) to point to the compiled server.js file:

{
  "mcp.servers": {
    "my-mcp-server-sampling": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/server.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

⚠️ Important Troubleshooting Note:

Always remember to run yarn build after making any changes to src/server.ts. VS Code executes the compiled build/server.js file, so if you skip the build step, your changes will not be reflected in the IDE.

🐛 Common Pitfalls Avoided

ESM Imports: All @modelcontextprotocol/sdk imports include the .js extension to comply with strict Node.js ESM resolution.

Stdio Corruption: Uses console.error exclusively for logging to prevent corrupting the JSON-RPC stdout stream used for client-server communication.

Dynamic JSON Loading: Uses node:fs with absolute paths rather than import statements to reliably read users.json both in development (tsx) and production (node).