Easy MCP Server

Overview

Easy MCP is a TypeScript framework designed to simplify the creation of Model Context Protocol (MCP) servers. It provides an intuitive API that hides the complexity of MCP implementation behind simple declarations, allowing developers to focus on building functionality rather than dealing with boilerplate code.

Installation

To get started with Easy MCP, you'll need to have Bun installed as it's the preferred package manager and runtime for this project.

# Clone the repository
git clone https://github.com/zcaceres/easy-mcp.git
cd easy-mcp

# Install dependencies
bun install

Usage

Easy MCP offers two main approaches to creating MCP servers:

Using the Experimental Decorators API

The decorators API provides the simplest way to create an MCP server by automatically inferring types and input configurations:

import EasyMCP from "./lib/EasyMCP";
import { Tool, Resource, Prompt } from "./lib/experimental/decorators";

class MyMCP extends EasyMCP {
  @Resource("greeting/{name}")
  getGreeting(name: string) {
    return `Hello, ${name}!`;
  }

  @Prompt()
  greetingPrompt(name: string) {
    return `Generate a greeting for ${name}.`;
  }

  @Tool()
  greet(name: string, optionalContextFromServer: Context) {
    optionalContextFromServer.info(`Greeting ${name}`);
    return `Hello, ${name}!`;
  }
}

const mcp = new MyMCP({ version: "1.0.0" });

Using the Express-like API

For more control, you can use the Express-like API to define your MCP components:

import EasyMCP from "./lib/EasyMCP";

const mcp = new EasyMCP({ version: "1.0.0" });

// Define a tool
mcp.tool("greet", {
  description: "Greet a person by name",
  parameters: [
    {
      name: "name",
      type: "string",
      description: "The name of the person to greet"
    }
  ],
  handler: (name, context) => {
    context.info(`Greeting ${name}`);
    return `Hello, ${name}!`;
  }
});

// Define a resource
mcp.resource("greeting/{name}", {
  handler: (name) => {
    return `Hello, ${name}!`;
  }
});

// Start the server
mcp.listen(3000);

Advanced Features

Context Object

Tools receive a context object that provides access to MCP capabilities:

• Logging: context.info(), context.warn(), context.error()
• Progress reporting: context.progress()
• Request metadata access

Root Directories

You can define root directories for your MCP server:

@Root("/my-sample-dir/photos")
@Root("/my-root-dir", { name: "My laptop's root directory" })
class MyMCP extends EasyMCP {
  // Your MCP implementation
}

Current Limitations

As Easy MCP is still in beta, there are some limitations:

• No support for MCP sampling
• No support for Server-Sent Events (SSE)
• No resource update notifications
• Limited support for prompt inputs

Running Examples

The repository includes several examples that demonstrate different aspects of Easy MCP:

# Run the decorators example
bun start:decorators

# Run the Express-like API example
bun start:express

Contributing

If you encounter any issues or have suggestions for improvements, please open an issue on the GitHub repository.