mcp-hooks

# 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 ```bash # Using npm npm install mcp-hooks # Using Bun (recommended) bun add mcp-hooks ``` ## Basic Usage ```typescript 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](https://bun.sh) (1.0.0 or newer) ### Setup ```bash # 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 ```bash # 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](./examples) for various usage examples: ```bash # 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. ```typescript 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. ```typescript interface ServerWithHooksOptions { beforeHook?: BeforeHook; afterHook?: AfterHook; } ``` ### Hook Types ```typescript 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