MCP Server JS

A simple and elegant TypeScript/JavaScript library for building Model Context Protocol (MCP) servers with a minimal API surface.

Features

✨ Simple API - Create MCP servers with just a few lines of code
🔧 Type-Safe - Full TypeScript support with Zod validation
📦 Zero Dependencies - Minimal production dependencies
🚀 Multiple Transports - HTTP, stdio, and WebSocket support
✅ Fully Tested - Comprehensive test suite

Installation

npm install mcp-server-js

Quick Start

Basic Example

import { createMCP } from "mcp-server-js"

const app = createMCP({ debug: true })

// Register a simple tool
app.tool({
  name: "greet",
  handler: async ({ name }) => {
    return `Hello, ${name}!`
  }
})

app.start()

// Execute a tool
const result = await app.execute("greet", { 
  name: "World" 
})
console.log(result) // "Hello, World!"

With Input Validation

import { createMCP } from "mcp-server-js"
import { z } from "zod"

const app = createMCP()

app.tool({
  name: "add",
  schema: z.object({
    a: z.number(),
    b: z.number()
  }),
  handler: async ({ a, b }) => {
    return { result: a + b }
  }
})

app.start()

// Inputs are validated automatically
const result = await app.execute("add", { 
  a: 5, 
  b: 3 
})

API Reference

createMCP(options?)

Creates a new MCP server instance.

const app = createMCP({
  debug: true // Enable debug logging
})

app.tool(toolDefinition)

Registers a tool on the server.

app.tool({
  name: "tool-name",
  schema: z.object({...}), // Optional: input validation schema
  handler: async (input) => {
    // Tool implementation
    return result
  }
})

app.execute(toolName, input?)

Executes a registered tool.

const result = await app.execute("tool-name", { 
  /* input */ 
})

app.listTools()

Returns an array of all registered tools.

const tools = app.listTools()
tools.forEach(tool => console.log(tool.name))

app.start()

Starts the MCP server.

app.start()

Transports

HTTP Server

import { createMCP, createHttpServer } from "mcp-server-js"

const app = createMCP()

app.tool({
  name: "hello",
  handler: async () => "Hello!"
})

const httpServer = createHttpServer(app, { 
  port: 3000 
})

await httpServer.listen()

Available endpoints:

• GET /tools - List all tools
• POST /execute - Execute a tool

Stdio

import { 
  createMCP, 
  attachStdio 
} from "mcp-server-js"

const app = createMCP()

app.tool({
  name: "hello",
  handler: async () => "Hello!"
})

attachStdio(app)

Examples

See the /examples directory for complete examples:

• basic.ts - Simple server with greeting and calculation tools
• weather.ts - Tool with simulated weather data
• multi-tools.ts - Server with multiple math and string tools

Run examples:

npm run example:basic
npm run example:weather
npm run example:multi

Testing

Run the comprehensive test suite:

npm test

The test suite covers:

• ✅ Server creation
• ✅ Tool registration
• ✅ Input validation
• ✅ Async/sync handlers
• ✅ Error handling
• ✅ Tool listing

Development

Build

npm run build

Watch Mode

npm run dev

Package.json Scripts

{
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --watch",
    "test": "node --loader tsx/cjs tests/server.test.ts",
    "example:basic": "node --loader tsx/cjs examples/basic.ts"
  }
}

Project Structure

mcp-server-js/
├── src/
│   ├── core/              # Core MCP server logic
│   │   ├── MCPServer.ts   # Main server class
│   │   ├── createMCP.ts   # Factory function
│   │   └── registry.ts    # Tool registry
│   ├── tool/              # Tool management
│   │   ├── createTool.ts
│   │   ├── executeTool.ts
│   │   └── validateInput.ts
│   ├── transport/         # Transport implementations
│   │   ├── http.ts
│   │   ├── stdio.ts
│   │   └── websocket.ts
│   ├── utils/             # Utilities
│   │   ├── errors.ts
│   │   └── logger.ts
│   ├── types/             # Type definitions
│   │   └── index.ts
│   └── index.ts           # Main export
├── examples/              # Usage examples
├── tests/                 # Test suite
└── package.json

Type Definitions

Full TypeScript support with exported types:

export type Tool = ToolDefinition
export type ToolHandler<T = any> = (input: T) => Promise<any> | any
export type ToolDefinition<T = any> = {
  name: string
  schema?: z.ZodSchema<T>
  handler: ToolHandler<T>
}
export type MCPOptions = {
  debug?: boolean
}

Error Handling

The library provides custom error types:

import { MCPError } from "mcp-server-js"

try {
  await app.execute("nonexistent")
} catch (error) {
  if (error instanceof MCPError) {
    console.error("MCP Error:", error.message)
  }
}

License

MIT © 2026

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.

Built with ❤️ for the AI community