@asoviche/mcp-builder

A declarative, type-safe library for building MCP (Model Context Protocol) servers.

Features

• 🎯 Declarative API — Define tools and resources with minimal boilerplate
• 🔒 Type-safe — Full TypeScript support with Zod schema validation
• ⚡ Zero config — Sensible defaults, just define and serve
• 🔌 Extensible — Custom transports supported

Installation

npm install @asoviche/mcp-builder zod

Quick Start

import { createMCP } from "@asoviche/mcp-builder";
import { z } from "zod";

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

// Define a tool
mcp.tool("greet", {
  description: "Greet someone by name",
  parameters: z.object({
    name: z.string().describe("Name to greet"),
  }),
  execute: ({ name }) => {
    return `Hello, ${name}!`;
  },
});

// Define a resource
mcp.resource("config://app", {
  description: "Application configuration",
  read: () => JSON.stringify({ debug: true }),
});

// Start the server
mcp.serve();

API

createMCP(config)

Creates a new MCP server builder.

const mcp = createMCP({
  name: "my-server",      // Required: Server name
  version: "1.0.0",       // Required: Server version
  description: "...",     // Optional: Server description
});

mcp.tool(name, definition)

Registers a tool with the server.

mcp.tool("calculate", {
  description: "Perform calculations",
  parameters: z.object({
    a: z.number(),
    b: z.number(),
    op: z.enum(["add", "subtract"]),
  }),
  execute: async ({ a, b, op }) => {
    return op === "add" ? a + b : a - b;
  },
});

mcp.resource(uri, definition)

Registers a resource with the server.

mcp.resource("file://config.json", {
  description: "Configuration file",
  mimeType: "application/json",
  read: async () => {
    return await fs.readFile("config.json", "utf-8");
  },
});

mcp.serve(options?)

Starts the MCP server.

// Default: stdio transport
mcp.serve();

// Custom transport
mcp.serve({ transport: myCustomTransport });

Using with Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "path/to/your/server.ts"]
    }
  }
}

Supported Zod Types

The library automatically converts Zod schemas to JSON Schema for MCP:

| Zod Type | JSON Schema | |----------|-------------| | z.string() | { type: "string" } | | z.number() | { type: "number" } | | z.boolean() | { type: "boolean" } | | z.enum([...]) | { type: "string", enum: [...] } | | z.array(...) | { type: "array", items: {...} } | | z.object({...}) | { type: "object", properties: {...} } | | z.optional(...) | Removes from required | | z.default(...) | Adds default value | | .describe(...) | Adds description |

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT