mcp-server-plus

Introduction

mcp-server-plus is an MCP Server Toolkit — a small TypeScript framework for building Model Context Protocol servers without repeating boilerplate.

Package name note: mcp-server-toolkit was already taken on npm, so this ships as mcp-server-plus.

Why this package exists

Developers starting MCP servers repeatedly re-implement tool registration, prompts, resources, auth, logging, and tests. Popular libraries like Express and Hono succeed because they make the happy path obvious. mcp-server-plus aims for that same DX on top of the official @modelcontextprotocol/sdk.

Installation

npm install mcp-server-plus zod

Requires Node.js 18+.

Features

• Tool registration
• Prompt registry
• Resources
• Authentication / authorization
• Logging
• Metrics
• Streaming (via MCP stdio transport)
• Middleware
• CLI scaffolder
• Testing helpers

Quick Start

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

API Reference

createServer(options) / createMcpServer(options)

Creates an McpKitServer.

Option	Type	Description
name	string	Server name
version	string	Server version
instructions	string?	Optional MCP instructions
auth	AuthOptions?	API key / custom auth
middleware	Middleware[]?	Global middleware
logger	Logger?	Custom logger

server.tool(name, definition)

Registers a tool (also wired into the MCP SDK).

server.prompt(name, definition)

Registers a prompt template.

server.resource(uri, definition)

Registers a resource.

server.use(middleware)

Adds middleware around tool calls.

server.start()

Connects an MCP stdio transport (streaming handled by the SDK).

server.invokeTool(name, args, meta?)

In-process invocation for tests/scripts.

Testing helpers

import { callTool, expectText } from "mcp-server-plus/testing";

Examples

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

Advanced Examples

Auth + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

Middleware + metrics

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

Framework Integration

Works with Cursor, Claude Desktop, and any MCP host that supports stdio servers. Point the host at your node dist/index.js (or npm start) process.

Example MCP host config:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

TypeScript Usage

First-class TypeScript. Tool args are inferred from Zod inputSchema when you type the handler explicitly. Enable strict for best results.

Error Handling

Typed errors: McpKitError, AuthError, ForbiddenError.
Tool failures return { isError: true, content: [...] } so hosts can display them safely.

Performance

• Thin wrapper over the official SDK (no extra network hops)
• Middleware only on tool invocations
• Metrics use simple counters (low overhead)

Best Practices

• Keep tools small and side-effect aware
• Validate inputs with Zod schemas
• Use optional auth for local/dev, required for shared hosts
• Prefer invokeTool in unit tests; use stdio for integration

FAQ

Is this an official SDK?
No — it builds on @modelcontextprotocol/sdk with nicer DX.

Does it support streaming?
Yes via the MCP stdio transport used by server.start().

CJS or ESM?
Dual published; ESM-first.

Migration Guide

From raw SDK McpServer

Replace registerTool boilerplate with server.tool(name, definition) and keep Zod schemas. Call server.start() instead of manually wiring StdioServerTransport.

SemVer

Breaking changes land in major versions and are documented in CHANGELOG.md.

Troubleshooting

Symptom	Fix
Host can’t start server	Ensure start() is called and stdout isn’t polluted with logs
Unauthorized tool calls	Pass meta.apiKey / configure host env MCP_API_KEY
Types missing	Import from mcp-server-plus and use Node 18+

Contributing

See CONTRIBUTING.md.

License

MIT