mcp

Build MCP servers with typed tools and resources

Overview

The mcp module wraps the Model Context Protocol SDK for building MCP servers with Zod-validated tools and resources. Includes a test harness for verification without a running server.

Peer dependencies: @modelcontextprotocol/sdk, zod

npm install @modelcontextprotocol/sdk zod

yarn add @modelcontextprotocol/sdk zod

pnpm add @modelcontextprotocol/sdk zod

Quick Start

import { McpServerBuilder } from '@jamaalbuilds/ai-toolkit/mcp';
import { z } from 'zod';

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

server.defineTool({
  name: 'search',
  description: 'Search the knowledge base',
  schema: {
    query: z.string().describe('Search query'),
    limit: z.number().optional().describe('Max results'),
  },
  handler: async ({ query, limit }) => {
    const results = await searchKnowledgeBase(query, limit);
    return results;
  },
});

API Reference

McpServerBuilder

Builder class for creating MCP servers.

new McpServerBuilder(config: McpServerConfig)

.defineTool(definition)

Register a tool with Zod schema validation.

server.defineTool({
  name: 'get-weather',
  description: 'Get current weather for a location',
  schema: {
    location: z.string(),
    units: z.enum(['celsius', 'fahrenheit']).optional(),
  },
  handler: async ({ location, units }) => {
    return `Weather in ${location}: 72F`;
  },
});

.defineResource(definition)

Register a resource that clients can read.

server.defineResource({
  uri: 'config://app-settings',
  name: 'Application Settings',
  description: 'Current application configuration',
  handler: async () => config,
});

McpTestHarness

Test MCP servers without starting a transport.

const harness = server.createTestHarness();
const result = await harness.callTool('search', { query: 'test' });
const resource = await harness.readResource('config://app-settings');

Types

• McpServerBuilder — builder with defineTool(), defineResource()
• McpServerConfig — name, version
• McpToolResponse — content array of McpContent
• McpContent — text content or image content
• ToolDefinition — name, description, schema, handler
• ResourceDefinition — uri, name, description, handler
• McpTestHarness — test helper with callTool(), readResource()