@ebowwa/mcp-nm 1.0.2

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ebowwa/mcp-nm",
+  "version": "1.0.2",
+  "description": "Binary symbol analysis MCP server using nm tool - analyze exports, imports, and symbols in ELF/Mach-O binaries",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nm-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node && chmod +x dist/index.js",
+    "dev": "bun run src/index.ts",
+    "watch": "bun build src/index.ts --outdir dist --target node --watch",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "mcp",
+    "nm",
+    "binary",
+    "symbols",
+    "elf",
+    "mach-o",
+    "analysis",
+    "reverse-engineering",
+    "abi"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  },
+  "ownership": {
+    "domain": "mcp",
+    "responsibilities": [
+      "network-manager-mcp",
+      "network-configuration"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,610 @@
+#!/usr/bin/env node
+/**
+ * @ebowwa/nm-mcp - Binary symbol analysis MCP server
+ *
+ * Provides tools for analyzing symbols in ELF/Mach-O binaries using nm
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.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",
+});
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface NmSymbol {
+  value: string;
+  type: string;
+  name: string;
+  size?: string;
+}
+
+interface NmResult {
+  filePath: string;
+  symbols: NmSymbol[];
+  totalCount: number;
+  filteredCount: number;
+}
+
+// ============================================================================
+// nm execution
+// ============================================================================
+
+async function runNm(
+  filePath: string,
+  options: {
+    externalOnly?: boolean;
+    undefinedOnly?: boolean;
+    definedOnly?: boolean;
+    dynamicSymbols?: boolean;
+    showSize?: boolean;
+    demangle?: boolean;
+    noSort?: boolean;
+    reverseSort?: boolean;
+    radix?: "hex" | "decimal" | "octal";
+  } = {}
+): Promise<NmResult> {
+  const args: string[] = [];
+
+  // Symbol filtering
+  if (options.externalOnly) args.push("-g");
+  if (options.undefinedOnly) args.push("-u");
+  if (options.definedOnly) args.push("--defined-only");
+  if (options.dynamicSymbols) args.push("-D");
+
+  // Output formatting
+  if (options.showSize) args.push("-S");
+  if (options.demangle) args.push("--demangle");
+  if (options.noSort) args.push("-p");
+  if (options.reverseSort) args.push("-r");
+
+  // Radix for values
+  if (options.radix === "hex") args.push("-t");
+  if (options.radix === "decimal") args.push("-t");
+  if (options.radix === "octal") args.push("-to");
+
+  // Build command
+  const cmd = `nm ${args.join(" ")} "${filePath}"`;
+
+  try {
+    const { stdout, stderr } = await execAsync(cmd, {
+      maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+    });
+
+    if (stderr && !stdout) {
+      throw new Error(stderr);
+    }
+
+    // Parse nm output
+    const symbols: NmSymbol[] = stdout
+      .trim()
+      .split("\n")
+      .filter((line) => line.trim())
+      .map((line) => {
+        // nm output format: "value type name" or "         type name" (for undefined)
+        const match = line.match(
+          /^\s*([0-9a-fA-F]+)?\s+([a-zA-Z?])\s+(.+?)(?:\s+(\d+))?$/
+        );
+        if (match) {
+          return {
+            value: match[1] || "0",
+            type: match[2],
+            name: match[3],
+            size: match[4],
+          };
+        }
+        // Alternative format (just symbol name for some cases)
+        const parts = line.trim().split(/\s+/);
+        if (parts.length >= 2) {
+          return {
+            value: parts[0] === "U" ? "0" : parts[0] || "0",
+            type: parts.length >= 2 ? parts[parts.length - 2] : "?",
+            name: parts[parts.length - 1] || "",
+          };
+        }
+        return { value: "0", type: "?", name: line.trim() };
+      })
+      .filter((s) => s.name);
+
+    return {
+      filePath,
+      symbols,
+      totalCount: symbols.length,
+      filteredCount: symbols.length,
+    };
+  } catch (error) {
+    throw new Error(
+      `nm command failed: ${error instanceof Error ? error.message : error}`
+    );
+  }
+}
+
+// ============================================================================
+// Symbol type descriptions
+// ============================================================================
+
+const SYMBOL_TYPE_DESCRIPTIONS: Record<string, string> = {
+  A: "Global absolute symbol",
+  B: "Global BSS (uninitialized data)",
+  b: "Local BSS (uninitialized data)",
+  C: "Common symbol (uninitialized)",
+  D: "Global initialized data",
+  d: "Local initialized data",
+  G: "Global small initialized data",
+  g: "Local small initialized data",
+  i: "Indirect function reference",
+  N: "Debugging symbol",
+  p: "Stack unwind section",
+  R: "Global read-only data",
+  r: "Local read-only data",
+  S: "Global small BSS",
+  s: "Local small BSS",
+  T: "Global text (code)",
+  t: "Local text (code)",
+  U: "Undefined symbol",
+  u: "Unique global symbol",
+  V: "Weak object",
+  v: "Weak object",
+  W: "Weak symbol",
+  w: "Weak symbol",
+  "?": "Unknown symbol type",
+};
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+// 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 });
+
+    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 }],
+    };
+  }
+);
+
+// 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,
+    });
+
+    // 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);
+    }
+
+    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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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,
+    });
+
+    const summary = [
+      `File: ${result.filePath}`,
+      `Undefined symbols (imports): ${result.totalCount}`,
+      "",
+      "Dependencies:",
+      ...result.symbols.map((s) => `  - ${s.name}`),
+    ].join("\n");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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,
+    });
+
+    // 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)
+    );
+
+    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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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,
+    });
+
+    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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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 regex = new RegExp(
+      pattern,
+      caseSensitive ? "g" : "gi"
+    );
+    const matches = result.symbols.filter((s) => regex.test(s.name));
+
+    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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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 symbols1 = new Set(result1.symbols.map((s) => s.name));
+    const symbols2 = new Set(result2.symbols.map((s) => s.name));
+
+    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 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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// 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(
+      (s) =>
+        s.name === symbolName ||
+        s.name.includes(symbolName)
+    );
+
+    if (matches.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Symbol "${symbolName}" not found in ${filePath}`,
+          },
+        ],
+      };
+    }
+
+    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");
+
+    return {
+      content: [{ type: "text", text: summary }],
+    };
+  }
+);
+
+// nm_summary - Quick binary overview
+server.tool(
+  "nm_summary",
+  "Get a quick summary of a binary's symbol table - counts by type",
+  {
+    filePath: z.string().describe("Path to the binary file"),
+  },
+  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);
+      }
+    }
+
+    // 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: ${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 }],
+    };
+  }
+);
+
+// ============================================================================
+// Start server
+// ============================================================================
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("nm-mcp server running on stdio");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}