my-mcp-server

A playground and experimentation project for building an MCP (Model Context Protocol) server using TypeScript. It demonstrates how to expose tools and resources to AI agents and language models via the stdio transport.

The server manages a simple user database (backed by a local JSON file) and exposes endpoints that an AI agent can call to read or create user records.

---

Features

• Tool — my-create-tool: Creates a new user by accepting name, address, email, and phone fields and persisting the record to src/users.json.
• Resource — users://all: Returns the full list of users from the mock database as JSON.
• Resource — users://{userId}/profile: Returns the profile of a single user identified by userId.

---

Prerequisites

• Node.js v18 or later
• npm v9 or later

---

Installation

npm install

---

Running the Server

Development mode (using tsx, no build step)

npm run server:dev

Build & run compiled output

npm run server:build   # compiles TypeScript → JavaScript
node dist/server.js    # run the compiled server

Watch mode (auto-recompile on changes)

npm run server:build:watch

Inspect with MCP Inspector UI

The MCP Inspector lets you interactively call tools and browse resources in a browser UI:

npm run server:inspect

Note: server:inspect sets DANGEROUSLY_OMIT_AUTH=true — use this only for local development.

---

Loading the MCP Server in Agent Environments

Agent CLI (e.g. Claude Code CLI)

Existence of .mcp.json should be picked up by the agent and prompted to load the server. Otherwise it's a simple MCP server config that needs to be added to the configuration with other servers.

---

Project Structure

my-mcp-server/
├── src/
│   ├── server.ts      # MCP server entry point (tools & resources)
│   └── users.json     # Mock user database (read/written at runtime)
├── package.json
└── tsconfig.json

---

Tech Stack

Package	Role
@modelcontextprotocol/sdk	MCP server SDK (tools, resources, stdio transport)
zod	Input schema validation for tools
tsx	Run TypeScript directly without a build step
typescript	TypeScript compiler
@modelcontextprotocol/inspector	Browser-based MCP debug UI

---

License

ISC