EasyMCP TypeScript MCP Server for Node.js

Overview

EasyMCP is a lightweight, TypeScript-first Model Context Protocol (MCP) server for Node.js. It provides a structured server runtime to host model tools, plugins, and request handlers that speak the MCP specification. The project is intended to reduce boilerplate when building tools that need to manage model context, telemetry, and pluggable capabilities, while keeping type safety and developer ergonomics in mind.

The core idea is to make it simple to register typed tools and plugins, expose them over HTTP or socket endpoints, and compose them into larger workflows. This makes EasyMCP useful for local development, model orchestration, testing harnesses, and small production deployments that require a predictable, extensible server surface for model-related operations.

Features

• TypeScript-first API surface with type definitions for handlers and plugins
• Minimal starter server and CLI for quick iteration
• Pluggable architecture for registering tools, middlewares, and IO adapters
• HTTP endpoints that implement MCP-style semantics for model context and tool invocation
• CORS and logging configuration for web integrations
• Example plugins and templates to get started quickly

Installation / Configuration

Install the package with npm or yarn:

# npm
npm install easy-mcp

# yarn
yarn add easy-mcp

Add basic TypeScript configuration if your project doesn’t already have one:

// tsconfig.json (minimal)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Basic server example (src/server.ts):

import { createMCPServer } from "easy-mcp";

async function main() {
  const server = createMCPServer({
    host: "0.0.0.0",
    port: 4000,
    logLevel: process.env.LOG_LEVEL ?? "info",
    cors: { origin: "*" },
  });

  // Register a simple tool
  server.registerTool("echo", {
    inputSchema: { type: "string" },
    async run(ctx, input) {
      return { output: `echo: ${input}` };
    },
  });

  // Start listening
  await server.listen();
  console.log("EasyMCP server running on http://localhost:4000");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Package.json scripts:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "ts-node-dev --respawn src/server.ts"
  }
}

Configuration options (example)

Adjust these via env vars or pass directly to createMCPServer.

Available Resources

• Repository: https://github.com/zcaceres/easy-mcp/
• Examples folder: check the repo for example servers and plugin templates
• Issues & Discussions: open an issue on the GitHub repo for bugs or feature requests
• License and contribution guidelines: see repo for licensing and contribution details

If the project exposes a CLI, you can typically run:

npx easy-mcp init    # scaffold a project (if available)
npx easy-mcp start   # start server using local config

(Refer to the repo README or examples for exact CLI commands).

Use Cases

1. Local prototyping of model tools

   • Quickly expose a set of small deterministic utilities (summarizers, token counters, formatters) that your frontend can call while iterating on UX.
   • Example: register a “summarize” tool that accepts text and returns a short summary; call it from a web app via POST /tools/summarize.

2. Model orchestration and adapters

   • Use EasyMCP as a thin proxy that maps MCP tool invocations to different model backends (OpenAI, local LLMs, cloud APIs). Each tool can implement provider logic and credentials management.
   • Example: a “translate” tool chooses a provider at runtime based on request metadata and returns a normalized result object.

3. Testing and CI harnesses

   • Stand up a deterministic MCP server that returns canned responses or uses lightweight mock models for integration tests. Swap in a real model server later without changing the test harness.
   • Example: in tests, start an EasyMCP instance that implements “classify” with predictable outputs.

4. Plugin ecosystems and extensibility

   • Build reusable plugins for authentication, telemetry, caching, or prompt templating. Load them dynamically from a plugins directory to extend behavior without changing the core server.
   • Example: a plugin that logs each tool’s input/output and attaches tracing IDs to context.

Sample Tool Interface

Below is a minimal pattern to implement a tool plugin:

export interface Tool<Input = any, Output = any> {
  name: string;
  inputSchema?: unknown;
  run(ctx: ToolContext, input: Input): Promise<Output>;
}

Registering a plugin:

server.registerPlugin({
  name: "metrics",
  async onRequest(ctx) {
    // attach timing or counters
  },
});

Next Steps

• Clone the repo and explore the examples directory for concrete server and plugin implementations.
• Use TypeScript types provided by the package to build safe tool handlers and integrate with your existing services.
• Open issues or contribute plugins that the community can reuse.

For full API details and latest usage, consult the GitHub repository: https://github.com/zcaceres/easy-mcp/