MCP TypeScript Server

This project is a Model Context Protocol (MCP) server written in TypeScript. It is a simple, local‑development oriented implementation designed as a quick start for developers who want to add MCP tools quickly and try them in their editor.

You only need to add files under src/tools. A template is provided to make this straightforward.

Prerequisites

• Node.js: Install the current LTS version from https://nodejs.org/.
• npm: Comes with Node.js. Verify with npm -v.

Install

npm install

Environment setup

Create a .env file in the project root before starting the server.

• If an .env.example file exists, copy it and fill in values:

  cp .env.example .env
  # then edit .env

• If there is no example file, create .env and add any variables required by your tools. Typical patterns include API keys and configuration values (e.g., PORT=, API_KEY=). Keep .env out of version control.

Start the server

npm start

What you should see in the terminal

When you run npm start:

• You will see logs indicating the server is running and listening on the env PORT.
• You may see a list of discovered tools and their names.
• The process will remain running, waiting for an MCP client (like Cursor or VS Code) to connect.

> easy-mcp-ts@0.1.0 start
> tsx src/server.ts

Importing tool module: colorTools.ts
Importing tool module: templateTool.ts
Imported 2 tool module(s)

Registering tool: convert_color_code
Registered 1 tool(s)

Listening on port 8080

---

Adding Your Own Tools

You only need to add files under src/tools. A template is provided to make this straightforward.

Use the template

1. Copy the template tool file:
   • From: src/tools/templateTool.ts
   • To: src/tools/<yourFileName>.ts
2. Open your new file and implement your tool logic following the template’s structure:
   • Export a default function that returns the tool’s MCP definition and handler(s).
   • Give your tool a unique name and description.
   • Define the input schema (params) and implement the action.
3. Restart the server, and restart your tools in VSCode or Cursor. Your tool will be picked up automatically when the server starts.

---

Included Tools

Color tools

This repo includes color conversion utilities exposed as an MCP tool. It accepts a CSS color input and converts it to a requested target space.

• Tool name: convert_color_code
• Parameters:
  • code (string): CSS color (e.g., #ff00ff, rgb(255 0 255), hsl(300 100% 50%), oklch(...), or named colors)
  • target (one of): hex, rgb, hsl, hwb, lab, lch, oklab, oklch, named
• Result: { result: string } with the converted color; empty string if parsing fails

Use this as a reference for how to structure a tool: clear name/description, Zod schemas for parameters/results, and a single focused action.

---

Connect the Server to Editors

You can use either Cursor or VS Code (or both). Both rely on a JSON config that points to this server and starts it via npm start.

The Cursor connection file is located at .cursor/mcp.json

The VS Code connection file is located as .vscode/mcp.json

For both, copy the values to your global mcp.json file to use across all projects.

---

Contributing

Purpose and scope

This project is for quick starts and local experimentation. Keep contributions simple, focused, and easy for others to adopt.

PR guidelines

1. Add your tool as a new file in src/tools/<yourToolName>.ts using src/tools/templateTool.ts as a baseline.
2. Provide a unique tool name, a concise description, and Zod schemas for inputs/outputs.
3. Validate inputs thoroughly and return clear, user‑facing errors.
4. Avoid unnecessary dependencies; keep the footprint small.
5. Ensure npm start runs cleanly and your tool is auto‑registered.

Adding tools for everyone’s use

• Target broadly useful capabilities (e.g., format conversions, project utilities, or public API helpers that don’t require secrets).
• If credentials are required, read them from .env and document variables in .env.example.
• Favor deterministic, idempotent operations and small, structured outputs.

PRs that align with these rules are more likely to be merged quickly.

---

Docker

The image can be gathered from mattbeard0/easy-mcp-ts:latest or build your own as below.

Build image

With Docker installed and the Docker engine running:

docker build -t easy-mcp-ts .

Run container

docker run --rm -p 8080:8080 easy-mcp-ts

The server listens on port 8080 inside the container and exposes the /mcp endpoint.

---

Wishlist

• Cloudflare Workers Deploy Support
• Testing scripts with decorators
• Adjustable HTTP Options
• Prompt Support
• Resource Support
• Env and Type Checks Automated