How to version your MCP server API

1// src/version.ts
2export const SERVER_VERSION = "2.1.0";
3
4// Version changelog:
5// 2.1.0 - Added search_files tool, added optional 'recursive' param to list_files
6// 2.0.0 - BREAKING: Renamed get_file to read_file, removed legacy_search tool
7// 1.3.0 - Added write_file tool
8// 1.2.0 - Added list_files tool
9// 1.1.0 - Added get_stats tool
10// 1.0.0 - Initial release with get_file tool
11
12// src/index.ts
13import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
14import { SERVER_VERSION } from "./version.js";
15
16const server = new McpServer({
17  name: "versioned-file-server",
18  version: SERVER_VERSION,  // Communicated to clients during handshake
19});

1// src/capabilities.ts
2export const SERVER_CAPABILITIES = {
3  tools: {
4    supported: true,
5    features: {
6      fileOperations: true,
7      searchOperations: true,
8      writeOperations: true,
9      metricsReporting: true,
10    },
11  },
12  versioning: {
13    currentVersion: "2.1.0",
14    minimumClientVersion: "1.0.0",
15    deprecatedTools: ["legacy_search"],
16    removedInNext: ["get_file_v1"],
17  },
18};
19
20// Register a version info tool
21server.tool(
22  "get_server_info",
23  "Get server version, capabilities, and deprecation notices",
24  {},
25  async () => {
26    return {
27      content: [{
28        type: "text",
29        text: JSON.stringify(SERVER_CAPABILITIES, null, 2),
30      }],
31    };
32  }
33);

1// src/deprecated-tool.ts
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4import { logger } from "./logger.js";
5
6export function registerDeprecatedTool(
7  server: McpServer,
8  oldName: string,
9  newName: string,
10  description: string,
11  schema: Record<string, z.ZodTypeAny>,
12  handler: (params: any) => Promise<any>
13) {
14  server.tool(
15    oldName,
16    `[DEPRECATED - Use ${newName} instead] ${description}`,
17    schema,
18    async (params) => {
19      logger.warn({ tool: oldName, replacement: newName }, "Deprecated tool called");
20
21      const result = await handler(params);
22
23      // Prepend deprecation warning to response
24      const warning = `⚠ DEPRECATION WARNING: "${oldName}" will be removed in the next major version. Use "${newName}" instead.\n\n`;
25      const content = result.content.map((c: any) => 
26        c.type === "text" ? { ...c, text: warning + c.text } : c
27      );
28
29      return { ...result, content };
30    }
31  );
32}
33
34// Usage:
35// registerDeprecatedTool(server, "get_file", "read_file", "Read file contents", 
36//   { path: z.string() }, readFileHandler);

1// Before (v2.0.0):
2server.tool("list_files", "List files in a directory", {
3  directory: z.string().default("."),
4}, listFilesHandler);
5
6// After (v2.1.0) — added optional 'recursive' parameter:
7server.tool("list_files", "List files in a directory. Set recursive=true to include subdirectories.", {
8  directory: z.string().default("."),
9  recursive: z.boolean().default(false).describe("Include files from subdirectories"),
10  fileTypes: z.array(z.string()).optional().describe("Filter by file extensions, e.g. ['.ts', '.js']"),
11}, async ({ directory, recursive, fileTypes }) => {
12  // Existing behavior preserved when recursive=false and fileTypes=undefined
13  const fs = await import("fs/promises");
14  const entries = await fs.readdir(directory, { withFileTypes: true, recursive });
15  let files = entries.filter(e => e.isFile());
16  if (fileTypes?.length) {
17    files = files.filter(e => fileTypes.some(ext => e.name.endsWith(ext)));
18  }
19  return { content: [{ type: "text", text: JSON.stringify(files.map(f => f.name), null, 2) }] };
20});

1// src/versioned-tools.ts
2import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
3import { z } from "zod";
4
5export function registerVersionedTools(server: McpServer) {
6  // Current version (v2) — new interface
7  server.tool(
8    "search_files",
9    "Search files by content pattern. Returns matched lines with context.",
10    {
11      pattern: z.string().describe("Regex pattern to search for"),
12      directory: z.string().default("."),
13      contextLines: z.number().default(2).describe("Lines of context around matches"),
14    },
15    searchFilesV2Handler
16  );
17
18  // Legacy version (v1) — deprecated, will be removed in v3.0.0
19  server.tool(
20    "search_files_v1",
21    "[DEPRECATED in v3.0.0 - Use search_files instead] Search files by name pattern.",
22    {
23      query: z.string().describe("File name pattern"),
24    },
25    async ({ query }) => {
26      console.error(`[deprecation] search_files_v1 called — migrate to search_files`);
27      // Delegate to v2 with compatible parameters
28      return searchFilesV2Handler({ pattern: query, directory: ".", contextLines: 0 });
29    }
30  );
31}