@ubuligan/server

A thin DX layer over the MCP SDK server. Create an McpServer, register your tools / resources / prompts with the standard SDK methods, then boot it over stdio (local) or Streamable HTTP (production) with a single serve() call.

Part of the MCP Toolkit.

Install

npm install @ubuligan/server zod

(zod is used to declare tool input schemas — recommended but not required.)

Quick start

import { createMCPServer, serve } from "@ubuligan/server";
import { z } from "zod";

const server = createMCPServer({ name: "my-server", version: "1.0.0" });

server.registerTool(
  "add",
  {
    title: "Add two numbers",
    inputSchema: { a: z.number(), b: z.number() },
  },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

// stdio for Claude Desktop / local clients:
await serve(server, { transport: "stdio" });

Run over Streamable HTTP

// Pass a factory so each request gets a fresh server (stateless mode).
await serve(() => buildServer(), { transport: "http", port: 3000, path: "/mcp" });

API

createMCPServer({ name, version? }): McpServer

Returns the SDK McpServer. Register capabilities with registerTool / registerResource / registerPrompt — see the MCP SDK docs.

serve(serverOrFactory, options): Promise<void>

Boot over the chosen transport.

| Option | Type | Default | | --- | --- | --- | | transport | "stdio" \| "http" | — (required) | | port | number | 3000 (http) | | path | string | "/mcp" (http) | | logger | Logger \| LogLevel | silent |

For http, pass a factory () => McpServer to get a fresh server per request.

Lower-level helpers

• startStdio(server, logger?) — connect a server over stdio.
• startHttp(serverOrFactory, opts?) — start the HTTP listener; resolves to { port, close }. Supports port: 0 (OS-assigned port, returned as the actual port).

McpServer is re-exported for convenience.

License

MIT