Skip to content

README.md

Latest commit

 

History

History
92 lines (65 loc) · 2.74 KB

README.md

File metadata and controls

92 lines (65 loc) · 2.74 KB

Simple MCP with Node.js & TypeScript

This project is a minimal, educational implementation of a Model Context Protocol (MCP)–style system using Node.js and TypeScript. It demonstrates how a client and server can communicate over standard input/output (stdio) using structured messages, simulating how modern AI tools interact with external context providers.

The project was built using VS Code with GitHub Copilot, exploring how AI-assisted development integrates with protocol-based system design.

🚀 What This Project Demonstrates

  • A lightweight MCP-style client–server architecture
  • Communication over stdio instead of HTTP
  • Structured request/response handling
  • Type-safe development with TypeScript
  • Local JSON-based data access
  • Practical experimentation with AI tooling workflows

This repository focuses on clarity over complexity, making it ideal for learning, experimentation, and extension.

🧠 Architecture Overview

  Client (client.ts)
  |
  | stdio messages
  v
  Server (server.ts)
  |
  | Reads local data
  v
  users.json
  • Client sends structured requests
  • Server processes requests and responds via stdio
  • users.json acts as a mock data source
  • mcp.json defines how the MCP server is launched and integrated

📁 Project Structure

  ├── client.ts # MCP client implementation
  ├── server.ts # MCP server implementation
  ├── users.json # Sample data source
  ├── mcp.json # MCP server configuration
  ├── package.json
  ├── package-lock.json
  └── README.md

⚙️ How It Works

  1. The MCP server is launched using Node.js (configured in mcp.json)
  2. The client communicates with the server via stdio
  3. Requests are parsed and handled in a structured manner
  4. The server reads from users.json and returns results
  5. Responses are sent back to the client in a predictable format

This mirrors how AI tools query external systems for context without relying on traditional REST APIs.

▶️ Running the Project

Install dependencies

npm install
npm run build
node build/server.js
(Client execution depends on your MCP setup or test harness.)

🧪 Why This Matters

Modern AI systems increasingly rely on protocol-driven context sharing rather than monolithic APIs. This project provides a hands-on foundation for understanding:

  • AI tool integrations
  • Context-aware systems
  • Protocol-oriented backend design
  • Developer tooling workflows

📌 Notes

  • This is a learning and exploration project
  • Designed to be easily extended (databases, auth, tools, schemas)
  • Emphasizes readability and correctness over feature depth