@ezmcpz/core

Core server builder and runtime for the EZMCPZ.

Installation

npm install @ezmcpz/core
# or
pnpm add @ezmcpz/core

Quick Start

import { McpServer } from '@ezmcpz/core';
import { z } from 'zod';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0'
});

// Register a tool
server.tool('greet', {
  description: 'Greet a user',
  schema: z.object({ name: z.string() }),
  handler: async (args, context) => {
    context.logger.info(`Greeting ${args.name}`);
    return { message: `Hello, ${args.name}!` };
  }
});

// Register a resource
server.resource('resource://docs/*', {
  name: 'Documentation',
  description: 'Server documentation',
  mimeType: 'text/markdown',
  handler: async (uri, context) => {
    return {
      uri,
      mimeType: 'text/markdown',
      text: '# Documentation\n\nWelcome!'
    };
  }
});

// Add middleware
server.use(async (context, next) => {
  const start = Date.now();
  const result = await next();
  context.logger.info(`Request took ${Date.now() - start}ms`);
  return result;
});

// Start with a transport (see transport packages)
// server.use(httpTransport({ port: 3000 }));
// await server.start();

Decorator Support

import { McpController, Tool, Resource } from '@ezmcpz/core/decorators';
import { z } from 'zod';

@McpController()
class MyController {
  @Tool({
    description: 'Calculate sum',
    schema: z.object({
      a: z.number(),
      b: z.number()
    })
  })
  async add(args: { a: number; b: number }, context: McpContext) {
    return { result: args.a + args.b };
  }

  @Resource('resource://data/:id')
  async getData(uri: string, context: McpContext) {
    return { uri, content: 'data' };
  }
}

server.controller(MyController);

Testing

import { createTestServer } from '@ezmcpz/core/testing';
import { describe, it, expect } from 'vitest';

describe('My Server', () => {
  it('should execute tool', async () => {
    const server = createTestServer()
      .tool('test', {
        description: 'Test tool',
        schema: z.object({ value: z.string() }),
        handler: async (args) => ({ result: args.value })
      });

    const result = await server.callTool('test', { value: 'hello' });
    expect(result.result).toBe('hello');
  });
});

API Reference

McpServer

Main server class for building MCP servers.

Constructor

new McpServer(options: McpServerOptions)

Methods

• tool(name, options) - Register a tool
• resource(uri, options) - Register a resource
• use(middleware) - Add middleware, transport, or plugin
• plugin(plugin) - Register a plugin
• completion(argumentName, handler) - Register completion handler
• configure(config) - Update configuration
• start() - Start the server
• stop() - Stop the server

Types

See the types documentation for all available types.

License

MIT