How to build a multi-tool MCP server

1# Project structure:
2# src/
3#   index.ts           <- entry point
4#   context.ts         <- shared state
5#   tools/
6#     list-files.ts
7#     read-file.ts
8#     search-files.ts
9#     get-stats.ts
10#     write-file.ts
11#   helpers/
12#     format-response.ts
13#     validate-path.ts
14
15npm init -y
16npm install @modelcontextprotocol/sdk zod
17npm install -D typescript @types/node
18npx tsc --init

1// src/context.ts
2import fs from "fs/promises";
3import path from "path";
4
5export interface ServerContext {
6  basePath: string;
7  maxFileSize: number;
8  allowedExtensions: string[];
9  stats: { toolCalls: Record<string, number> };
10}
11
12export function createContext(basePath: string): ServerContext {
13  return {
14    basePath: path.resolve(basePath),
15    maxFileSize: 10 * 1024 * 1024, // 10MB
16    allowedExtensions: [".ts", ".js", ".json", ".md", ".txt"],
17    stats: { toolCalls: {} },
18  };
19}
20
21export function trackCall(ctx: ServerContext, toolName: string): void {
22  ctx.stats.toolCalls[toolName] = (ctx.stats.toolCalls[toolName] || 0) + 1;
23}

1// src/tools/list-files.ts
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4import fs from "fs/promises";
5import path from "path";
6import { ServerContext, trackCall } from "../context.js";
7
8export function registerListFiles(server: McpServer, ctx: ServerContext) {
9  server.tool(
10    "list_files",
11    "List files in a directory within the project",
12    {
13      directory: z.string().default(".").describe("Relative path from project root"),
14      recursive: z.boolean().default(false).describe("Include subdirectories"),
15    },
16    async ({ directory, recursive }) => {
17      trackCall(ctx, "list_files");
18      const fullPath = path.join(ctx.basePath, directory);
19      
20      if (!fullPath.startsWith(ctx.basePath)) {
21        return { content: [{ type: "text", text: "Error: Path traversal not allowed" }], isError: true };
22      }
23
24      const entries = await fs.readdir(fullPath, { withFileTypes: true, recursive });
25      const files = entries.map(e => ({
26        name: e.name,
27        type: e.isDirectory() ? "directory" : "file",
28      }));
29
30      return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
31    }
32  );
33}

1// src/index.ts
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
4import { createContext } from "./context.js";
5import { registerListFiles } from "./tools/list-files.js";
6import { registerReadFile } from "./tools/read-file.js";
7import { registerSearchFiles } from "./tools/search-files.js";
8import { registerGetStats } from "./tools/get-stats.js";
9import { registerWriteFile } from "./tools/write-file.js";
10
11const server = new McpServer({
12  name: "multi-tool-file-server",
13  version: "1.0.0",
14});
15
16const ctx = createContext(process.env.PROJECT_PATH || ".");
17
18// Register all tools
19registerListFiles(server, ctx);
20registerReadFile(server, ctx);
21registerSearchFiles(server, ctx);
22registerGetStats(server, ctx);
23registerWriteFile(server, ctx);
24
25async function main() {
26  const transport = new StdioServerTransport();
27  await server.connect(transport);
28  console.error(`Multi-tool server running with ${Object.keys(ctx.stats.toolCalls).length || 5} tools`);
29}
30
31main().catch((error) => {
32  console.error("Fatal error:", error);
33  process.exit(1);
34});

1// src/helpers/format-response.ts
2export function textResult(text: string) {
3  return { content: [{ type: "text" as const, text }] };
4}
5
6export function errorResult(message: string) {
7  return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true as const };
8}
9
10export function jsonResult(data: unknown) {
11  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
12}
13
14// src/helpers/validate-path.ts
15import path from "path";
16
17export function validatePath(basePath: string, relativePath: string): string | null {
18  const resolved = path.resolve(basePath, relativePath);
19  if (!resolved.startsWith(basePath)) return null;
20  return resolved;
21}

1# Build the project
2npx tsc
3
4# Run with MCP Inspector
5npx @modelcontextprotocol/inspector node dist/index.js
6
7# The inspector opens a browser UI where you can:
8# 1. See all 5 registered tools
9# 2. Fill in parameters and call each tool
10# 3. Inspect JSON-RPC messages
11# 4. Verify error handling