@ebowwa/mcp-nm 1.0.2 → 1.1.0

package/src/index.ts

@@ -1,23 +1,33 @@
 #!/usr/bin/env node
 /**
- * @ebowwa/nm-mcp - Binary symbol analysis MCP server
+ * @ebowwa/nm-mcp - Binary analysis MCP server
  *
- * Provides tools for analyzing symbols in ELF/Mach-O binaries using nm
+ * Provides tools for analyzing binaries using nm (symbols) and xxd (hex dumps)
  */
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 import { exec } from "child_process";
 import { promisify } from "util";
-import { z } from "zod";
 
 const execAsync = promisify(exec);
 
 // Server instance
-const server = new McpServer({
-  name: "@ebowwa/nm-mcp",
-  version: "1.0.0",
-});
+const server = new Server(
+  {
+    name: "@ebowwa/nm-mcp",
+    version: "1.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
 
 // ============================================================================
 // Types
@@ -37,6 +47,13 @@ interface NmResult {
   filteredCount: number;
 }
 
+interface XxdResult {
+  filePath: string;
+  output: string;
+  bytesProcessed: number;
+  startOffset: number;
+}
+
 // ============================================================================
 // nm execution
 // ============================================================================
@@ -130,6 +147,365 @@ async function runNm(
   }
 }
 
+// ============================================================================
+// xxd execution
+// ============================================================================
+
+async function runXxd(
+  filePath: string,
+  options: {
+    length?: number;
+    seek?: number;
+    cols?: number;
+    groupSize?: number;
+    plainHex?: boolean;
+    cInclude?: boolean;
+    binary?: boolean;
+    uppercase?: boolean;
+    littleEndian?: boolean;
+    reverse?: boolean;
+  } = {}
+): Promise<XxdResult> {
+  const args: string[] = [];
+
+  // Length (how many bytes to read)
+  if (options.length !== undefined) {
+    args.push("-l", options.length.toString());
+  }
+
+  // Seek offset (where to start)
+  if (options.seek !== undefined) {
+    args.push("-s", options.seek.toString());
+  }
+
+  // Columns per line
+  if (options.cols !== undefined) {
+    args.push("-c", options.cols.toString());
+  }
+
+  // Group size
+  if (options.groupSize !== undefined) {
+    args.push("-g", options.groupSize.toString());
+  }
+
+  // Output formats (mutually exclusive)
+  if (options.plainHex) args.push("-p");
+  if (options.cInclude) args.push("-i");
+  if (options.binary) args.push("-b");
+  if (options.reverse) args.push("-r");
+
+  // Other options
+  if (options.uppercase) args.push("-u");
+  if (options.littleEndian) args.push("-e");
+
+  // Build command
+  const cmd = `xxd ${args.join(" ")} "${filePath}"`;
+
+  try {
+    const { stdout, stderr } = await execAsync(cmd, {
+      maxBuffer: 50 * 1024 * 1024, // 50MB buffer for larger files
+    });
+
+    if (stderr && !stdout) {
+      throw new Error(stderr);
+    }
+
+    // Estimate bytes processed
+    let bytesProcessed = 0;
+    if (options.length !== undefined) {
+      bytesProcessed = options.length;
+    } else if (options.plainHex) {
+      // Plain hex: 2 chars per byte
+      bytesProcessed = Math.floor(stdout.length / 2);
+    } else {
+      // Standard hexdump: estimate from output lines
+      const cols = options.cols || 16;
+      const lines = stdout.split("\n").filter((l) => l.trim()).length;
+      bytesProcessed = lines * cols;
+    }
+
+    return {
+      filePath,
+      output: stdout,
+      bytesProcessed,
+      startOffset: options.seek || 0,
+    };
+  } catch (error) {
+    throw new Error(
+      `xxd command failed: ${error instanceof Error ? error.message : error}`
+    );
+  }
+}
+
+// ============================================================================
+// xxd tool handlers
+// ============================================================================
+
+async function handleXxdHexdump(args: {
+  filePath: string;
+  length?: number;
+  seek?: number;
+  cols?: number;
+  groupSize?: number;
+  uppercase?: boolean;
+}) {
+  const result = await runXxd(args.filePath, {
+    length: args.length,
+    seek: args.seek,
+    cols: args.cols,
+    groupSize: args.groupSize,
+    uppercase: args.uppercase,
+  });
+
+  const summary = [
+    `Hex dump: ${result.filePath}`,
+    `Start offset: 0x${result.startOffset.toString(16)} (${result.startOffset})`,
+    `Bytes shown: ~${result.bytesProcessed.toLocaleString()}`,
+    "",
+    result.output,
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleXxdPlain(args: {
+  filePath: string;
+  length?: number;
+  seek?: number;
+  uppercase?: boolean;
+}) {
+  const result = await runXxd(args.filePath, {
+    length: args.length,
+    seek: args.seek,
+    uppercase: args.uppercase,
+    plainHex: true,
+  });
+
+  const summary = [
+    `Plain hex: ${result.filePath}`,
+    `Start offset: 0x${result.startOffset.toString(16)}`,
+    `Bytes: ~${result.bytesProcessed.toLocaleString()}`,
+    "",
+    result.output.slice(0, 10000),
+    result.output.length > 10000
+      ? `\n... truncated (${result.output.length - 10000} more chars)`
+      : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleXxdCInclude(args: {
+  filePath: string;
+  length?: number;
+  seek?: number;
+  variableName?: string;
+}) {
+  const result = await runXxd(args.filePath, {
+    length: args.length,
+    seek: args.seek,
+    cInclude: true,
+  });
+
+  // Optionally rename the variable
+  let output = result.output;
+  if (args.variableName) {
+    output = output.replace(/unsigned char/g, `unsigned char ${args.variableName}`);
+  }
+
+  const summary = [
+    `C include style: ${result.filePath}`,
+    `Bytes: ~${result.bytesProcessed.toLocaleString()}`,
+    "",
+    output,
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleXxdBinary(args: {
+  filePath: string;
+  length?: number;
+  seek?: number;
+  cols?: number;
+}) {
+  const result = await runXxd(args.filePath, {
+    length: args.length,
+    seek: args.seek,
+    cols: args.cols || 8,
+    binary: true,
+  });
+
+  const summary = [
+    `Binary dump: ${result.filePath}`,
+    `Start offset: 0x${result.startOffset.toString(16)}`,
+    `Bytes: ~${result.bytesProcessed.toLocaleString()}`,
+    "",
+    result.output,
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleXxdReverse(args: {
+  inputHex: string;
+  outputPath: string;
+}) {
+  // Write hex to temp file, then use xxd -r
+  const tempFile = `/tmp/xxd_input_${Date.now()}.hex`;
+
+  try {
+    // Write hex input to temp file
+    await execAsync(`echo '${args.inputHex}' > "${tempFile}"`);
+
+    // Convert hex to binary
+    const cmd = `xxd -r -p "${tempFile}" > "${args.outputPath}"`;
+    await execAsync(cmd);
+
+    // Get file info
+    const { stdout: fileInfo } = await execAsync(
+      `ls -la "${args.outputPath}" | awk '{print $5}'`
+    );
+    const bytesWritten = parseInt(fileInfo.trim(), 10);
+
+    const summary = [
+      `Converted hex to binary`,
+      `Output: ${args.outputPath}`,
+      `Bytes written: ${bytesWritten.toLocaleString()}`,
+      "",
+      "Success!",
+    ].join("\n");
+
+    return { content: [{ type: "text", text: summary }] };
+  } finally {
+    // Cleanup temp file
+    await execAsync(`rm -f "${tempFile}"`).catch(() => {});
+  }
+}
+
+async function handleXxdExtract(args: {
+  filePath: string;
+  offset: number;
+  length: number;
+  format?: "hex" | "binary" | "decimal" | "c-array";
+}) {
+  const format = args.format || "hex";
+  const result = await runXxd(args.filePath, {
+    seek: args.offset,
+    length: args.length,
+    plainHex: format === "hex" || format === "c-array",
+    cols: args.length,
+    groupSize: 1,
+  });
+
+  let output: string;
+  const rawHex = result.output.replace(/\s/g, "");
+
+  switch (format) {
+    case "hex":
+      output = rawHex;
+      break;
+    case "binary": {
+      // Convert hex to binary string
+      let bin = "";
+      for (let i = 0; i < rawHex.length; i += 2) {
+        const byte = parseInt(rawHex.slice(i, i + 2), 16);
+        bin += byte.toString(2).padStart(8, "0") + " ";
+      }
+      output = bin.trim();
+      break;
+    }
+    case "decimal": {
+      // Convert hex to decimal bytes
+      const decimals: string[] = [];
+      for (let i = 0; i < rawHex.length; i += 2) {
+        const byte = parseInt(rawHex.slice(i, i + 2), 16);
+        decimals.push(byte.toString().padStart(3, " "));
+      }
+      output = decimals.join(" ");
+      break;
+    }
+    case "c-array": {
+      // Format as C array
+      const bytes: string[] = [];
+      for (let i = 0; i < rawHex.length; i += 2) {
+        bytes.push(`0x${rawHex.slice(i, i + 2)}`);
+      }
+      output = `{ ${bytes.join(", ")} }`;
+      break;
+    }
+    default:
+      output = rawHex;
+  }
+
+  const summary = [
+    `Extracted bytes from: ${result.filePath}`,
+    `Offset: 0x${args.offset.toString(16)} (${args.offset})`,
+    `Length: ${args.length} bytes`,
+    `Format: ${format}`,
+    "",
+    output,
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleXxdFindPattern(args: {
+  filePath: string;
+  pattern: string;
+  patternFormat?: "hex" | "text";
+  maxLength?: number;
+}) {
+  // Read file as hex
+  const result = await runXxd(args.filePath, {
+    plainHex: true,
+    length: args.maxLength,
+  });
+
+  const fileHex = result.output.replace(/\s/g, "").toLowerCase();
+  let searchPattern: string;
+
+  if (args.patternFormat === "text" || !args.patternFormat) {
+    // Convert text to hex
+    searchPattern = args.pattern
+      .split("")
+      .map((c) => c.charCodeAt(0).toString(16).padStart(2, "0"))
+      .join("");
+  } else {
+    searchPattern = args.pattern.replace(/\s/g, "").toLowerCase();
+  }
+
+  const matches: { offset: number; context: string }[] = [];
+  let idx = 0;
+  while ((idx = fileHex.indexOf(searchPattern, idx)) !== -1) {
+    const byteOffset = Math.floor(idx / 2);
+    // Get context (10 bytes before and after)
+    const contextStart = Math.max(0, idx - 20);
+    const contextEnd = Math.min(fileHex.length, idx + searchPattern.length + 20);
+    const contextHex = fileHex.slice(contextStart, contextEnd);
+
+    matches.push({
+      offset: byteOffset,
+      context: contextHex.match(/.{1,2}/g)?.join(" ") || contextHex,
+    });
+    idx++;
+  }
+
+  const summary = [
+    `Pattern search in: ${args.filePath}`,
+    `Pattern: ${args.pattern} (${args.patternFormat || "text"})`,
+    `Hex pattern: ${searchPattern}`,
+    `Matches found: ${matches.length}`,
+    "",
+    ...matches.slice(0, 50).map(
+      (m) => `  Offset 0x${m.offset.toString(16).padStart(8, "0")}: ...${m.context}...`
+    ),
+    matches.length > 50 ? `  ... and ${matches.length - 50} more` : "",
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
 // ============================================================================
 // Symbol type descriptions
 // ============================================================================
@@ -162,437 +538,644 @@ const SYMBOL_TYPE_DESCRIPTIONS: Record<string, string> = {
 };
 
 // ============================================================================
-// Tools
+// Tool handlers
 // ============================================================================
 
-// nm_list_symbols - Basic symbol listing
-server.tool(
-  "nm_list_symbols",
-  "List all symbols in a binary file",
-  {
-    filePath: z.string().describe("Path to the binary file to analyze"),
-    demangle: z
-      .boolean()
-      .optional()
-      .default(false)
-      .describe("Demangle C++ symbol names"),
-  },
-  async ({ filePath, demangle }) => {
-    const result = await runNm(filePath, { demangle });
+async function handleListSymbols(args: { filePath: string; demangle?: boolean }) {
+  const result = await runNm(args.filePath, { demangle: args.demangle ?? false });
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `Total symbols: ${result.totalCount}`,
-      "",
-      "Symbols:",
-      ...result.symbols.slice(0, 100).map(
-        (s) =>
-          `  ${s.value} ${s.type} ${s.name}${
-            SYMBOL_TYPE_DESCRIPTIONS[s.type]
-              ? ` (${SYMBOL_TYPE_DESCRIPTIONS[s.type]})`
-              : ""
-          }`
-      ),
-      result.symbols.length > 100
-        ? `  ... and ${result.symbols.length - 100} more`
-        : "",
-    ].join("\n");
+  const summary = [
+    `File: ${result.filePath}`,
+    `Total symbols: ${result.totalCount}`,
+    "",
+    "Symbols:",
+    ...result.symbols.slice(0, 100).map(
+      (s) =>
+        `  ${s.value} ${s.type} ${s.name}${
+          SYMBOL_TYPE_DESCRIPTIONS[s.type]
+            ? ` (${SYMBOL_TYPE_DESCRIPTIONS[s.type]})`
+            : ""
+        }`
+    ),
+    result.symbols.length > 100
+      ? `  ... and ${result.symbols.length - 100} more`
+      : "",
+  ].join("\n");
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
+  return { content: [{ type: "text", text: summary }] };
+}
+
+async function handleExternalSymbols(args: { filePath: string; demangle?: boolean; showSize?: boolean }) {
+  const result = await runNm(args.filePath, {
+    externalOnly: true,
+    demangle: args.demangle ?? true,
+    showSize: args.showSize ?? false,
+  });
+
+  // Group by type
+  const byType: Record<string, NmSymbol[]> = {};
+  for (const sym of result.symbols) {
+    const type = sym.type;
+    if (!byType[type]) byType[type] = [];
+    byType[type].push(sym);
   }
-);
 
-// nm_external_symbols - List only external (global) symbols
-server.tool(
-  "nm_external_symbols",
-  "List external (global) symbols in a binary file - symbols visible to other modules",
-  {
-    filePath: z.string().describe("Path to the binary file"),
-    demangle: z
-      .boolean()
-      .optional()
-      .default(true)
-      .describe("Demangle C++ symbol names"),
-    showSize: z
-      .boolean()
-      .optional()
-      .default(false)
-      .describe("Show symbol sizes"),
-  },
-  async ({ filePath, demangle, showSize }) => {
-    const result = await runNm(filePath, {
-      externalOnly: true,
-      demangle,
-      showSize,
-    });
+  const summary = [
+    `File: ${result.filePath}`,
+    `External symbols: ${result.totalCount}`,
+    "",
+    "By type:",
+    ...Object.entries(byType).map(([type, syms]) => {
+      const desc = SYMBOL_TYPE_DESCRIPTIONS[type] || "Unknown";
+      return `\n  ${type} (${desc}): ${syms.length} symbols`;
+    }),
+    "",
+    "All external symbols:",
+    ...result.symbols.slice(0, 50).map(
+      (s) =>
+        `  ${s.value} ${s.type} ${s.name}${
+          s.size ? ` [${s.size} bytes]` : ""
+        }`
+    ),
+    result.symbols.length > 50
+      ? `  ... and ${result.symbols.length - 50} more`
+      : "",
+  ].join("\n");
 
-    // Group by type
-    const byType: Record<string, NmSymbol[]> = {};
-    for (const sym of result.symbols) {
-      const type = sym.type;
-      if (!byType[type]) byType[type] = [];
-      byType[type].push(sym);
-    }
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `External symbols: ${result.totalCount}`,
-      "",
-      "By type:",
-      ...Object.entries(byType).map(([type, syms]) => {
-        const desc = SYMBOL_TYPE_DESCRIPTIONS[type] || "Unknown";
-        return `\n  ${type} (${desc}): ${syms.length} symbols`;
-      }),
-      "",
-      "All external symbols:",
-      ...result.symbols.slice(0, 50).map(
-        (s) =>
-          `  ${s.value} ${s.type} ${s.name}${
-            s.size ? ` [${s.size} bytes]` : ""
-          }`
-      ),
-      result.symbols.length > 50
-        ? `  ... and ${result.symbols.length - 50} more`
-        : "",
-    ].join("\n");
+async function handleUndefinedSymbols(args: { filePath: string; demangle?: boolean }) {
+  const result = await runNm(args.filePath, {
+    undefinedOnly: true,
+    demangle: args.demangle ?? true,
+  });
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
-  }
-);
+  const summary = [
+    `File: ${result.filePath}`,
+    `Undefined symbols (imports): ${result.totalCount}`,
+    "",
+    "Dependencies:",
+    ...result.symbols.map((s) => `  - ${s.name}`),
+  ].join("\n");
 
-// nm_undefined_symbols - List undefined symbols (imports)
-server.tool(
-  "nm_undefined_symbols",
-  "List undefined symbols in a binary - these are external dependencies the binary needs",
-  {
-    filePath: z.string().describe("Path to the binary file"),
-    demangle: z.boolean().optional().default(true),
-  },
-  async ({ filePath, demangle }) => {
-    const result = await runNm(filePath, {
-      undefinedOnly: true,
-      demangle,
-    });
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `Undefined symbols (imports): ${result.totalCount}`,
-      "",
-      "Dependencies:",
-      ...result.symbols.map((s) => `  - ${s.name}`),
-    ].join("\n");
+async function handleDefinedSymbols(args: { filePath: string; demangle?: boolean; showSize?: boolean }) {
+  const result = await runNm(args.filePath, {
+    definedOnly: true,
+    demangle: args.demangle ?? true,
+    showSize: args.showSize ?? true,
+  });
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
-  }
-);
+  // Separate code and data symbols
+  const codeSymbols = result.symbols.filter(
+    (s) => s.type === "T" || s.type === "t" || s.type === "W" || s.type === "w"
+  );
+  const dataSymbols = result.symbols.filter(
+    (s) =>
+      s.type === "D" ||
+      s.type === "d" ||
+      s.type === "B" ||
+      s.type === "b" ||
+      s.type === "R" ||
+      s.type === "r"
+  );
+  const otherSymbols = result.symbols.filter(
+    (s) =>
+      !codeSymbols.includes(s) && !dataSymbols.includes(s)
+  );
 
-// nm_defined_symbols - List defined symbols (exports)
-server.tool(
-  "nm_defined_symbols",
-  "List defined symbols in a binary - symbols this binary provides to others",
-  {
-    filePath: z.string().describe("Path to the binary file"),
-    demangle: z.boolean().optional().default(true),
-    showSize: z.boolean().optional().default(true),
-  },
-  async ({ filePath, demangle, showSize }) => {
-    const result = await runNm(filePath, {
-      definedOnly: true,
-      demangle,
-      showSize,
-    });
+  const summary = [
+    `File: ${result.filePath}`,
+    `Defined symbols: ${result.totalCount}`,
+    "",
+    `Code symbols (${codeSymbols.length}):`,
+    ...codeSymbols.slice(0, 30).map(
+      (s) => `  ${s.value} ${s.type} ${s.name}${s.size ? ` [${s.size}]` : ""}`
+    ),
+    codeSymbols.length > 30
+      ? `  ... and ${codeSymbols.length - 30} more`
+      : "",
+    "",
+    `Data symbols (${dataSymbols.length}):`,
+    ...dataSymbols.slice(0, 20).map(
+      (s) => `  ${s.value} ${s.type} ${s.name}${s.size ? ` [${s.size}]` : ""}`
+    ),
+    dataSymbols.length > 20
+      ? `  ... and ${dataSymbols.length - 20} more`
+      : "",
+    "",
+    `Other symbols (${otherSymbols.length}):`,
+    ...otherSymbols.slice(0, 10).map(
+      (s) => `  ${s.value} ${s.type} ${s.name}`
+    ),
+  ].join("\n");
 
-    // Separate code and data symbols
-    const codeSymbols = result.symbols.filter(
-      (s) => s.type === "T" || s.type === "t" || s.type === "W" || s.type === "w"
-    );
-    const dataSymbols = result.symbols.filter(
-      (s) =>
-        s.type === "D" ||
-        s.type === "d" ||
-        s.type === "B" ||
-        s.type === "b" ||
-        s.type === "R" ||
-        s.type === "r"
-    );
-    const otherSymbols = result.symbols.filter(
-      (s) =>
-        !codeSymbols.includes(s) && !dataSymbols.includes(s)
-    );
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `Defined symbols: ${result.totalCount}`,
-      "",
-      `Code symbols (${codeSymbols.length}):`,
-      ...codeSymbols.slice(0, 30).map(
-        (s) => `  ${s.value} ${s.type} ${s.name}${s.size ? ` [${s.size}]` : ""}`
-      ),
-      codeSymbols.length > 30
-        ? `  ... and ${codeSymbols.length - 30} more`
-        : "",
-      "",
-      `Data symbols (${dataSymbols.length}):`,
-      ...dataSymbols.slice(0, 20).map(
-        (s) => `  ${s.value} ${s.type} ${s.name}${s.size ? ` [${s.size}]` : ""}`
-      ),
-      dataSymbols.length > 20
-        ? `  ... and ${dataSymbols.length - 20} more`
-        : "",
-      "",
-      `Other symbols (${otherSymbols.length}):`,
-      ...otherSymbols.slice(0, 10).map(
-        (s) => `  ${s.value} ${s.type} ${s.name}`
-      ),
-    ].join("\n");
+async function handleDynamicSymbols(args: { filePath: string; demangle?: boolean; definedOnly?: boolean }) {
+  const result = await runNm(args.filePath, {
+    dynamicSymbols: true,
+    demangle: args.demangle ?? true,
+    definedOnly: args.definedOnly ?? false,
+  });
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
-  }
-);
+  const summary = [
+    `File: ${result.filePath}`,
+    `Dynamic symbols: ${result.totalCount}`,
+    "",
+    "Symbols:",
+    ...result.symbols.slice(0, 100).map(
+      (s) => `  ${s.value} ${s.type} ${s.name}`
+    ),
+    result.symbols.length > 100
+      ? `  ... and ${result.symbols.length - 100} more`
+      : "",
+  ].join("\n");
 
-// nm_dynamic_symbols - List dynamic symbols (shared libraries)
-server.tool(
-  "nm_dynamic_symbols",
-  "List dynamic symbols from shared libraries (.so, .dylib)",
-  {
-    filePath: z.string().describe("Path to the shared library"),
-    demangle: z.boolean().optional().default(true),
-    definedOnly: z.boolean().optional().default(false),
-  },
-  async ({ filePath, demangle, definedOnly }) => {
-    const result = await runNm(filePath, {
-      dynamicSymbols: true,
-      demangle,
-      definedOnly,
-    });
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `Dynamic symbols: ${result.totalCount}`,
-      "",
-      "Symbols:",
-      ...result.symbols.slice(0, 100).map(
-        (s) => `  ${s.value} ${s.type} ${s.name}`
-      ),
-      result.symbols.length > 100
-        ? `  ... and ${result.symbols.length - 100} more`
-        : "",
-    ].join("\n");
+async function handleSearchSymbols(args: { filePath: string; pattern: string; demangle?: boolean; caseSensitive?: boolean }) {
+  const result = await runNm(args.filePath, { demangle: args.demangle ?? true });
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
-  }
-);
+  const regex = new RegExp(
+    args.pattern,
+    (args.caseSensitive ?? false) ? "g" : "gi"
+  );
+  const matches = result.symbols.filter((s) => regex.test(s.name));
 
-// nm_search_symbols - Search for specific symbols
-server.tool(
-  "nm_search_symbols",
-  "Search for symbols matching a pattern in a binary",
-  {
-    filePath: z.string().describe("Path to the binary file"),
-    pattern: z
-      .string()
-      .describe("Regex pattern to search for in symbol names"),
-    demangle: z.boolean().optional().default(true),
-    caseSensitive: z.boolean().optional().default(false),
-  },
-  async ({ filePath, pattern, demangle, caseSensitive }) => {
-    const result = await runNm(filePath, { demangle });
+  const summary = [
+    `File: ${result.filePath}`,
+    `Pattern: /${args.pattern}/${(args.caseSensitive ?? false) ? "" : "i"}`,
+    `Matches: ${matches.length} of ${result.totalCount} symbols`,
+    "",
+    "Matching symbols:",
+    ...matches.map(
+      (s) =>
+        `  ${s.value} ${s.type} ${s.name}${
+          SYMBOL_TYPE_DESCRIPTIONS[s.type]
+            ? ` (${SYMBOL_TYPE_DESCRIPTIONS[s.type]})`
+            : ""
+        }`
+    ),
+  ].join("\n");
 
-    const regex = new RegExp(
-      pattern,
-      caseSensitive ? "g" : "gi"
-    );
-    const matches = result.symbols.filter((s) => regex.test(s.name));
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `File: ${result.filePath}`,
-      `Pattern: /${pattern}/${caseSensitive ? "" : "i"}`,
-      `Matches: ${matches.length} of ${result.totalCount} symbols`,
-      "",
-      "Matching symbols:",
-      ...matches.map(
-        (s) =>
-          `  ${s.value} ${s.type} ${s.name}${
-            SYMBOL_TYPE_DESCRIPTIONS[s.type]
-              ? ` (${SYMBOL_TYPE_DESCRIPTIONS[s.type]})`
-              : ""
-          }`
-      ),
-    ].join("\n");
+async function handleCompareBinaries(args: { file1: string; file2: string; demangle?: boolean }) {
+  const dm = args.demangle ?? true;
+  const [result1, result2] = await Promise.all([
+    runNm(args.file1, { demangle: dm, definedOnly: true }),
+    runNm(args.file2, { demangle: dm, definedOnly: true }),
+  ]);
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
-  }
-);
+  const symbols1 = new Set(result1.symbols.map((s) => s.name));
+  const symbols2 = new Set(result2.symbols.map((s) => s.name));
 
-// nm_compare_binaries - Compare symbols between two binaries
-server.tool(
-  "nm_compare_binaries",
-  "Compare symbols between two binary files - find unique and shared symbols",
-  {
-    file1: z.string().describe("First binary file"),
-    file2: z.string().describe("Second binary file"),
-    demangle: z.boolean().optional().default(true),
-  },
-  async ({ file1, file2, demangle }) => {
-    const [result1, result2] = await Promise.all([
-      runNm(file1, { demangle, definedOnly: true }),
-      runNm(file2, { demangle, definedOnly: true }),
-    ]);
+  const onlyIn1 = result1.symbols.filter((s) => !symbols2.has(s.name));
+  const onlyIn2 = result2.symbols.filter((s) => !symbols1.has(s.name));
+  const inBoth = result1.symbols.filter((s) => symbols2.has(s.name));
 
-    const symbols1 = new Set(result1.symbols.map((s) => s.name));
-    const symbols2 = new Set(result2.symbols.map((s) => s.name));
+  const summary = [
+    `Comparison: ${args.file1} vs ${args.file2}`,
+    "",
+    `File 1: ${result1.totalCount} symbols`,
+    `File 2: ${result2.totalCount} symbols`,
+    "",
+    `Shared symbols: ${inBoth.length}`,
+    `Only in file 1: ${onlyIn1.length}`,
+    `Only in file 2: ${onlyIn2.length}`,
+    "",
+    "Only in file 1:",
+    ...onlyIn1.slice(0, 20).map((s) => `  - ${s.name}`),
+    onlyIn1.length > 20 ? `  ... and ${onlyIn1.length - 20} more` : "",
+    "",
+    "Only in file 2:",
+    ...onlyIn2.slice(0, 20).map((s) => `  - ${s.name}`),
+    onlyIn2.length > 20 ? `  ... and ${onlyIn2.length - 20} more` : "",
+  ].join("\n");
 
-    const onlyIn1 = result1.symbols.filter((s) => !symbols2.has(s.name));
-    const onlyIn2 = result2.symbols.filter((s) => !symbols1.has(s.name));
-    const inBoth = result1.symbols.filter((s) => symbols2.has(s.name));
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `Comparison: ${file1} vs ${file2}`,
-      "",
-      `File 1: ${result1.totalCount} symbols`,
-      `File 2: ${result2.totalCount} symbols`,
-      "",
-      `Shared symbols: ${inBoth.length}`,
-      `Only in file 1: ${onlyIn1.length}`,
-      `Only in file 2: ${onlyIn2.length}`,
-      "",
-      "Only in file 1:",
-      ...onlyIn1.slice(0, 20).map((s) => `  - ${s.name}`),
-      onlyIn1.length > 20 ? `  ... and ${onlyIn1.length - 20} more` : "",
-      "",
-      "Only in file 2:",
-      ...onlyIn2.slice(0, 20).map((s) => `  - ${s.name}`),
-      onlyIn2.length > 20 ? `  ... and ${onlyIn2.length - 20} more` : "",
-    ].join("\n");
+async function handleSymbolInfo(args: { filePath: string; symbolName: string; demangle?: boolean }) {
+  const result = await runNm(args.filePath, { demangle: args.demangle ?? true, showSize: true });
 
+  const matches = result.symbols.filter(
+    (s) =>
+      s.name === args.symbolName ||
+      s.name.includes(args.symbolName)
+  );
+
+  if (matches.length === 0) {
     return {
-      content: [{ type: "text", text: summary }],
+      content: [
+        {
+          type: "text",
+          text: `Symbol "${args.symbolName}" not found in ${args.filePath}`,
+        },
+      ],
     };
   }
-);
 
-// nm_symbol_info - Get detailed info about a specific symbol
-server.tool(
-  "nm_symbol_info",
-  "Get detailed information about a specific symbol by name",
-  {
-    filePath: z.string().describe("Path to the binary file"),
-    symbolName: z.string().describe("Name of the symbol to look up"),
-    demangle: z.boolean().optional().default(true),
-  },
-  async ({ filePath, symbolName, demangle }) => {
-    const result = await runNm(filePath, { demangle, showSize: true });
-
-    const matches = result.symbols.filter(
+  const summary = [
+    `Symbol: ${args.symbolName}`,
+    `File: ${args.filePath}`,
+    "",
+    "Matches:",
+    ...matches.map(
       (s) =>
-        s.name === symbolName ||
-        s.name.includes(symbolName)
-    );
+        [
+          `  Name: ${s.name}`,
+          `  Value: 0x${s.value}`,
+          `  Type: ${s.type} (${SYMBOL_TYPE_DESCRIPTIONS[s.type] || "Unknown"})`,
+          s.size ? `  Size: ${s.size} bytes` : "",
+          "",
+        ].join("\n")
+    ),
+  ].join("\n");
 
-    if (matches.length === 0) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Symbol "${symbolName}" not found in ${filePath}`,
-          },
-        ],
-      };
-    }
+  return { content: [{ type: "text", text: summary }] };
+}
 
-    const summary = [
-      `Symbol: ${symbolName}`,
-      `File: ${filePath}`,
-      "",
-      "Matches:",
-      ...matches.map(
-        (s) =>
-          [
-            `  Name: ${s.name}`,
-            `  Value: 0x${s.value}`,
-            `  Type: ${s.type} (${SYMBOL_TYPE_DESCRIPTIONS[s.type] || "Unknown"})`,
-            s.size ? `  Size: ${s.size} bytes` : "",
-            "",
-          ].join("\n")
-      ),
-    ].join("\n");
+async function handleSummary(args: { filePath: string }) {
+  const result = await runNm(args.filePath, { showSize: true });
 
-    return {
-      content: [{ type: "text", text: summary }],
-    };
+  // Count by type
+  const byType: Record<string, { count: number; totalSize: number }> = {};
+  for (const sym of result.symbols) {
+    const type = sym.type;
+    if (!byType[type]) byType[type] = { count: 0, totalSize: 0 };
+    byType[type].count++;
+    if (sym.size) {
+      byType[type].totalSize += parseInt(sym.size, 10);
+    }
   }
-);
 
-// nm_summary - Quick binary overview
-server.tool(
-  "nm_summary",
-  "Get a quick summary of a binary's symbol table - counts by type",
+  // Classify
+  const external = result.symbols.filter(
+    (s) => s.type === s.type.toUpperCase() && s.type !== "?"
+  ).length;
+  const local = result.symbols.filter(
+    (s) => s.type === s.type.toLowerCase()
+  ).length;
+  const undefined = result.symbols.filter((s) => s.type === "U").length;
+  const weak = result.symbols.filter(
+    (s) => s.type === "W" || s.type === "w" || s.type === "V" || s.type === "v"
+  ).length;
+
+  const summary = [
+    `Binary Summary: ${args.filePath}`,
+    "",
+    `Total symbols: ${result.totalCount}`,
+    `External: ${external}`,
+    `Local: ${local}`,
+    `Undefined: ${undefined}`,
+    `Weak: ${weak}`,
+    "",
+    "By symbol type:",
+    ...Object.entries(byType)
+      .sort((a, b) => b[1].count - a[1].count)
+      .map(([type, data]) => {
+        const desc = SYMBOL_TYPE_DESCRIPTIONS[type] || "Unknown";
+        return `  ${type} (${desc}): ${data.count} symbols${
+          data.totalSize ? `, ${data.totalSize.toLocaleString()} bytes` : ""
+        }`;
+      }),
+  ].join("\n");
+
+  return { content: [{ type: "text", text: summary }] };
+}
+
+// ============================================================================
+// Tool definitions
+// ============================================================================
+
+const TOOLS = [
   {
-    filePath: z.string().describe("Path to the binary file"),
+    name: "nm_list_symbols",
+    description: "List all symbols in a binary file",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file to analyze" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+      },
+      required: ["filePath"],
+    },
   },
-  async ({ filePath }) => {
-    const result = await runNm(filePath, { showSize: true });
-
-    // Count by type
-    const byType: Record<string, { count: number; totalSize: number }> = {};
-    for (const sym of result.symbols) {
-      const type = sym.type;
-      if (!byType[type]) byType[type] = { count: 0, totalSize: 0 };
-      byType[type].count++;
-      if (sym.size) {
-        byType[type].totalSize += parseInt(sym.size, 10);
-      }
-    }
+  {
+    name: "nm_external_symbols",
+    description: "List external (global) symbols in a binary file - symbols visible to other modules",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+        showSize: { type: "boolean", description: "Show symbol sizes" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "nm_undefined_symbols",
+    description: "List undefined symbols in a binary - these are external dependencies the binary needs",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "nm_defined_symbols",
+    description: "List defined symbols in a binary - symbols this binary provides to others",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+        showSize: { type: "boolean", description: "Show symbol sizes" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "nm_dynamic_symbols",
+    description: "List dynamic symbols from shared libraries (.so, .dylib)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the shared library" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+        definedOnly: { type: "boolean", description: "Show only defined symbols" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "nm_search_symbols",
+    description: "Search for symbols matching a pattern in a binary",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+        pattern: { type: "string", description: "Regex pattern to search for in symbol names" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+        caseSensitive: { type: "boolean", description: "Case sensitive search" },
+      },
+      required: ["filePath", "pattern"],
+    },
+  },
+  {
+    name: "nm_compare_binaries",
+    description: "Compare symbols between two binary files - find unique and shared symbols",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        file1: { type: "string", description: "First binary file" },
+        file2: { type: "string", description: "Second binary file" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+      },
+      required: ["file1", "file2"],
+    },
+  },
+  {
+    name: "nm_symbol_info",
+    description: "Get detailed information about a specific symbol by name",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+        symbolName: { type: "string", description: "Name of the symbol to look up" },
+        demangle: { type: "boolean", description: "Demangle C++ symbol names" },
+      },
+      required: ["filePath", "symbolName"],
+    },
+  },
+  {
+    name: "nm_summary",
+    description: "Get a quick summary of a binary's symbol table - counts by type",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the binary file" },
+      },
+      required: ["filePath"],
+    },
+  },
+  // xxd tools
+  {
+    name: "xxd_hexdump",
+    description: "Create a hex dump of a file with offset and ASCII representation",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file to dump" },
+        length: { type: "number", description: "Number of bytes to read" },
+        seek: { type: "number", description: "Start offset in bytes" },
+        cols: { type: "number", description: "Columns (bytes) per line (default: 16)" },
+        groupSize: { type: "number", description: "Number of bytes to group together (default: 2)" },
+        uppercase: { type: "boolean", description: "Use uppercase hex letters" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "xxd_plain",
+    description: "Output continuous plain hex string (no offsets or ASCII)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file" },
+        length: { type: "number", description: "Number of bytes to read" },
+        seek: { type: "number", description: "Start offset in bytes" },
+        uppercase: { type: "boolean", description: "Use uppercase hex letters" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "xxd_c_include",
+    description: "Output in C include file style (unsigned char array)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file" },
+        length: { type: "number", description: "Number of bytes to read" },
+        seek: { type: "number", description: "Start offset in bytes" },
+        variableName: { type: "string", description: "Custom variable name for the array" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "xxd_binary",
+    description: "Output binary digit dump (ones and zeros)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file" },
+        length: { type: "number", description: "Number of bytes to read" },
+        seek: { type: "number", description: "Start offset in bytes" },
+        cols: { type: "number", description: "Columns per line (default: 8)" },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "xxd_reverse",
+    description: "Convert hex string back to binary and save to file",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        inputHex: { type: "string", description: "Hex string to convert" },
+        outputPath: { type: "string", description: "Path to save the binary output" },
+      },
+      required: ["inputHex", "outputPath"],
+    },
+  },
+  {
+    name: "xxd_extract",
+    description: "Extract bytes at a specific offset with multiple format options",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file" },
+        offset: { type: "number", description: "Byte offset to start reading" },
+        length: { type: "number", description: "Number of bytes to extract" },
+        format: {
+          type: "string",
+          enum: ["hex", "binary", "decimal", "c-array"],
+          description: "Output format (default: hex)",
+        },
+      },
+      required: ["filePath", "offset", "length"],
+    },
+  },
+  {
+    name: "xxd_find_pattern",
+    description: "Search for a byte pattern in a file (hex or text)",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        filePath: { type: "string", description: "Path to the file to search" },
+        pattern: { type: "string", description: "Pattern to search for" },
+        patternFormat: {
+          type: "string",
+          enum: ["hex", "text"],
+          description: "Format of the pattern (default: text)",
+        },
+        maxLength: { type: "number", description: "Maximum bytes to search (for large files)" },
+      },
+      required: ["filePath", "pattern"],
+    },
+  },
+];
 
-    // Classify
-    const external = result.symbols.filter(
-      (s) => s.type === s.type.toUpperCase() && s.type !== "?"
-    ).length;
-    const local = result.symbols.filter(
-      (s) => s.type === s.type.toLowerCase()
-    ).length;
-    const undefined = result.symbols.filter((s) => s.type === "U").length;
-    const weak = result.symbols.filter(
-      (s) => s.type === "W" || s.type === "w" || s.type === "V" || s.type === "v"
-    ).length;
+// ============================================================================
+// Server handlers
+// ============================================================================
 
-    const summary = [
-      `Binary Summary: ${filePath}`,
-      "",
-      `Total symbols: ${result.totalCount}`,
-      `External: ${external}`,
-      `Local: ${local}`,
-      `Undefined: ${undefined}`,
-      `Weak: ${weak}`,
-      "",
-      "By symbol type:",
-      ...Object.entries(byType)
-        .sort((a, b) => b[1].count - a[1].count)
-        .map(([type, data]) => {
-          const desc = SYMBOL_TYPE_DESCRIPTIONS[type] || "Unknown";
-          return `  ${type} (${desc}): ${data.count} symbols${
-            data.totalSize ? `, ${data.totalSize.toLocaleString()} bytes` : ""
-          }`;
-        }),
-    ].join("\n");
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
 
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "nm_list_symbols":
+        return await handleListSymbols(args as { filePath: string; demangle?: boolean });
+      case "nm_external_symbols":
+        return await handleExternalSymbols(args as { filePath: string; demangle?: boolean; showSize?: boolean });
+      case "nm_undefined_symbols":
+        return await handleUndefinedSymbols(args as { filePath: string; demangle?: boolean });
+      case "nm_defined_symbols":
+        return await handleDefinedSymbols(args as { filePath: string; demangle?: boolean; showSize?: boolean });
+      case "nm_dynamic_symbols":
+        return await handleDynamicSymbols(args as { filePath: string; demangle?: boolean; definedOnly?: boolean });
+      case "nm_search_symbols":
+        return await handleSearchSymbols(args as { filePath: string; pattern: string; demangle?: boolean; caseSensitive?: boolean });
+      case "nm_compare_binaries":
+        return await handleCompareBinaries(args as { file1: string; file2: string; demangle?: boolean });
+      case "nm_symbol_info":
+        return await handleSymbolInfo(args as { filePath: string; symbolName: string; demangle?: boolean });
+      case "nm_summary":
+        return await handleSummary(args as { filePath: string });
+      // xxd handlers
+      case "xxd_hexdump":
+        return await handleXxdHexdump(args as {
+          filePath: string;
+          length?: number;
+          seek?: number;
+          cols?: number;
+          groupSize?: number;
+          uppercase?: boolean;
+        });
+      case "xxd_plain":
+        return await handleXxdPlain(args as {
+          filePath: string;
+          length?: number;
+          seek?: number;
+          uppercase?: boolean;
+        });
+      case "xxd_c_include":
+        return await handleXxdCInclude(args as {
+          filePath: string;
+          length?: number;
+          seek?: number;
+          variableName?: string;
+        });
+      case "xxd_binary":
+        return await handleXxdBinary(args as {
+          filePath: string;
+          length?: number;
+          seek?: number;
+          cols?: number;
+        });
+      case "xxd_reverse":
+        return await handleXxdReverse(args as {
+          inputHex: string;
+          outputPath: string;
+        });
+      case "xxd_extract":
+        return await handleXxdExtract(args as {
+          filePath: string;
+          offset: number;
+          length: number;
+          format?: "hex" | "binary" | "decimal" | "c-array";
+        });
+      case "xxd_find_pattern":
+        return await handleXxdFindPattern(args as {
+          filePath: string;
+          pattern: string;
+          patternFormat?: "hex" | "text";
+          maxLength?: number;
+        });
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
     return {
-      content: [{ type: "text", text: summary }],
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
     };
   }
-);
+});
 
 // ============================================================================
 // Start server