MCP Hooks

A TypeScript library that adds hook functionality to MCP (Model Context Protocol) servers, allowing you to intercept and modify tool calls.

Overview

MCP Hooks provides a simple wrapper around the standard MCP server that preserves 100% API compatibility while adding powerful hook capabilities. With MCP Hooks, you can:

• Add logging and telemetry to tool calls
• Track performance metrics
• Implement authorization and validation
• Debug tool execution
• Capture errors

Installation

# Using npm
npm install mcp-hooks

# Using Bun (recommended)
bun add mcp-hooks

Basic Usage

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { ServerWithHooks } from "mcp-hooks";
import { z } from "zod";

// Create a standard MCP server
const server = new McpServer({
  name: "My Server",
  version: "1.0.0"
});

// Define hooks
const beforeHook = async (context) => {
  console.log(`[BEFORE] Tool '${context.name}' called with:`, context.args);
};

const afterHook = async (context) => {
  console.log(`[AFTER] Tool '${context.name}' returned:`, context.result);
};

// Wrap the server with hooks
const wrappedServer = new ServerWithHooks(server, {
  beforeHook,
  afterHook
});

// Use the wrapped server exactly like a regular MCP server
wrappedServer.tool(
  "hello",
  "Generates a greeting",
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }]
  })
);

// Connect to a transport
const transport = new StdioServerTransport();
await wrappedServer.connect(transport);

Development

This project uses Bun for development, testing, and execution.

Prerequisites

• Bun (1.0.0 or newer)

Setup

# Clone the repository
git clone https://github.com/yourusername/mcp-hooks.git
cd mcp-hooks

# Install dependencies
bun install

# Build the project
bun run build

Testing

# Run all tests (including compiled tests)
bun test

# Run only source tests (faster)
bun test:fast

# Run with coverage
bun test --coverage

Examples

Check out the examples directory for various usage examples:

# Run the greeting example
bun run examples:greeting

# Run the analytics example
bun run examples:analytics

# Run the webhook example
bun run examples:webhook

API Reference

ServerWithHooks

The main class that wraps an MCP server and adds hook functionality.

class ServerWithHooks {
  constructor(server: McpServer, options: ServerWithHooksOptions);
  
  connect(transport: Transport): Promise<void>;
  tool(...args: any[]): void;
  resource(name: string, template: string | ResourceTemplate, handler: any): void;
  prompt(name: string, schema: Record<string, z.ZodType<any>>, handler: any): void;
}

ServerWithHooksOptions

Options for configuring the hooks.

interface ServerWithHooksOptions {
  beforeHook?: BeforeHook;
  afterHook?: AfterHook;
}

Hook Types

type HookContext<T = any, R = any> = {
  name: string;
  args: T;
  result?: R;
  isError?: boolean;
  extra?: RequestHandlerExtra;
};

type BeforeHook = (context: HookContext) => Promise<void> | void;
type AfterHook = (context: HookContext) => Promise<void> | void;

License

ISC