MCP Learning – TypeScript MCP Server & Client

This repository is a small learning project showing how to build a Model Context Protocol (MCP) server and client in TypeScript.

It includes:

• An MCP server that exposes:
  • User data as resources
  • Tools to create users (including via an LLM)
  • A prompt to generate fake user profiles
• An MCP client (CLI) that connects to the server and lets you explore:
  • Resources
  • Tools
  • Prompts

---

Tech Stack

• TypeScript
• Node.js
• @modelcontextprotocol/sdk
• zod
• tsx
• Node fs/promises for simple JSON-based persistence

---

Project Structure

src/
  server.ts       # MCP server (resources, tools, prompts)
  client.ts       # MCP client (interactive CLI)
  data/
    users.json    # Sample "database" of users

users.json starts with some sample users and is updated whenever new users are created.

---

Features

Server

Implemented in src/server.ts:

• Resources

  • user – users://all
    Returns the full list of users from src/data/users.json.
  • user-details – users://{userId}/profile
    A ResourceTemplate that returns details for a user by id, or an error JSON if the user is not found.

• Tools

  • create-user
    Creates a new user with the fields:
    • name
    • email
    • address
    • phone
      The user is appended to src/data/users.json.
  • create-random-user
    Uses MCP’s sampling/createMessage endpoint to ask an LLM for fake user data in JSON, parses it, and saves it to users.json.

• Prompt

  • generate-fake-user
    Builds a prompt to generate a fake user profile (email, address, phone) for a given name.

Client

Implemented in src/client.ts:

• Connects to the server using StdioClientTransport, spawning npm run server:dev.
• On startup, loads:
  • Tools
  • Prompts
  • Resources
  • Resource templates
• Shows an interactive menu:
  • Query (placeholder for custom logic)
  • Tools (list and run tools, prompting for arguments)
  • Resources (read resources and resource templates)
  • Prompts (run server-defined prompts)

---

Installation

git clone <your-repo-url>
cd <your-repo-folder>

npm install

(Optional) TypeScript build:

npm run server:build

Or watch mode:

npm run server:build:watch

---

Scripts

Defined in package.json:

Script	Command	Description
server:build	tsc	Build the server with TypeScript
server:build:watch	tsc --watch	Build and watch for changes
server:dev	tsx src/server.ts	Run the MCP server in dev mode
server:inspect	set DANGEROUSLY_OMIT_AUTH=true && npx @modelcontextprotocol/inspector npm run server:dev	Run MCP Inspector against the dev server
client:dev	tsx src/client.ts	Run the interactive MCP client

---

Running the Project

Easiest: Start the client (it starts the server for you)

npm run client:dev

The client will:

• Start npm run server:dev as a child process.
• Connect to the MCP server over stdio.
• Show the menu: Query, Tools, Resources, Prompts.

Alternative: Run MCP inspect tool

npm run server:inspect

---

Usage Examples

Once the client is running:

• List all users

  • Choose Resources
  • Select the Users resource (users://all)
  • The client prints the full users.json content.

• Get a single user’s details

  • Choose Resources
  • Select the User Details resource (users://{userId}/profile)
  • Enter a userId such as 1
  • The client prints that user’s data or an error JSON.

• Create a user

  • Choose Tools
  • Select Create user
  • Fill in name, email, address, phone
  • A new user is saved to src/data/users.json and the new ID is returned.

• Create a random user via LLM

  • Choose Tools
  • Select Create Random User
  • The server asks the model for fake user data, parses it, and saves it.

• Generate a fake user profile with a prompt

  • Choose Prompts
  • Select generate-fake-user
  • Enter a name (e.g. Jane Doe)
  • The prompt text is generated and shown in the CLI.

---

Purpose

This project is meant as a learning playground for:

• Understanding MCP servers (resources, tools, prompts)
• Building a simple MCP client
• Experimenting with JSON storage and LLM-powered tools

Feel free to extend it with more tools, resources, or real databases as you learn more.