@rog0x/mcp-file-tools 1.0.0

package/src/index.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+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 { dirTree } from "./tools/dir-tree.js";
+import { fileStats } from "./tools/file-stats.js";
+import { duplicateFinder } from "./tools/duplicate-finder.js";
+import { codeCounter } from "./tools/code-counter.js";
+import { fileSearch } from "./tools/file-search.js";
+
+const server = new Server(
+  {
+    name: "mcp-file-tools",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "dir_tree",
+      description:
+        "Generate a visual directory tree structure (like the `tree` command). Shows files and folders with configurable depth and ignore patterns.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          dir_path: { type: "string", description: "Absolute path to the directory" },
+          max_depth: {
+            type: "number",
+            description: "Maximum depth to traverse (default: 5, 0 = unlimited)",
+          },
+          ignore_patterns: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Patterns to ignore (default: node_modules, .git, dist, __pycache__, .next, .cache, coverage)",
+          },
+        },
+        required: ["dir_path"],
+      },
+    },
+    {
+      name: "file_stats",
+      description:
+        "Analyze a directory: total files, total size, file count by extension, largest files, newest/oldest files.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          dir_path: { type: "string", description: "Absolute path to the directory" },
+          max_depth: {
+            type: "number",
+            description: "Maximum depth to traverse (default: 10, 0 = unlimited)",
+          },
+        },
+        required: ["dir_path"],
+      },
+    },
+    {
+      name: "duplicate_finder",
+      description:
+        "Find duplicate files by comparing size and MD5 hash. Returns groups of duplicates with paths and wasted space.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          dir_path: { type: "string", description: "Absolute path to the directory" },
+          min_size: {
+            type: "number",
+            description: "Minimum file size in bytes to consider (default: 1)",
+          },
+          max_depth: {
+            type: "number",
+            description: "Maximum depth to traverse (default: 10)",
+          },
+        },
+        required: ["dir_path"],
+      },
+    },
+    {
+      name: "code_counter",
+      description:
+        "Count lines of code by programming language: total lines, code lines, comment lines, blank lines (like cloc/scc).",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          dir_path: { type: "string", description: "Absolute path to the directory" },
+          max_depth: {
+            type: "number",
+            description: "Maximum depth to traverse (default: 10)",
+          },
+        },
+        required: ["dir_path"],
+      },
+    },
+    {
+      name: "file_search",
+      description:
+        "Search for files by name pattern (glob), content (regex), size range, and/or date range.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          dir_path: { type: "string", description: "Absolute path to the directory to search" },
+          name_pattern: {
+            type: "string",
+            description: 'Glob pattern for file names (e.g. "**/*.ts", "*.json")',
+          },
+          content_pattern: {
+            type: "string",
+            description: "Regex pattern to search within file contents",
+          },
+          min_size: {
+            type: "number",
+            description: "Minimum file size in bytes",
+          },
+          max_size: {
+            type: "number",
+            description: "Maximum file size in bytes",
+          },
+          modified_after: {
+            type: "string",
+            description: "ISO date string - only files modified after this date",
+          },
+          modified_before: {
+            type: "string",
+            description: "ISO date string - only files modified before this date",
+          },
+          max_results: {
+            type: "number",
+            description: "Maximum number of results to return (default: 100)",
+          },
+        },
+        required: ["dir_path"],
+      },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "dir_tree": {
+        const result = await dirTree({
+          dirPath: args?.dir_path as string,
+          maxDepth: args?.max_depth as number | undefined,
+          ignorePatterns: args?.ignore_patterns as string[] | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "file_stats": {
+        const result = await fileStats({
+          dirPath: args?.dir_path as string,
+          maxDepth: args?.max_depth as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "duplicate_finder": {
+        const result = await duplicateFinder({
+          dirPath: args?.dir_path as string,
+          minSize: args?.min_size as number | undefined,
+          maxDepth: args?.max_depth as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "code_counter": {
+        const result = await codeCounter({
+          dirPath: args?.dir_path as string,
+          maxDepth: args?.max_depth as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      case "file_search": {
+        const result = await fileSearch({
+          dirPath: args?.dir_path as string,
+          namePattern: args?.name_pattern as string | undefined,
+          contentPattern: args?.content_pattern as string | undefined,
+          minSize: args?.min_size as number | undefined,
+          maxSize: args?.max_size as number | undefined,
+          modifiedAfter: args?.modified_after as string | undefined,
+          modifiedBefore: args?.modified_before as string | undefined,
+          maxResults: args?.max_results as number | undefined,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("MCP File Tools server running on stdio");
+}
+
+main().catch(console.error);

package/src/tools/code-counter.ts

@@ -0,0 +1,208 @@
+import * as fs from "fs";
+import * as path from "path";
+
+interface CodeCounterOptions {
+  dirPath: string;
+  maxDepth?: number;
+}
+
+interface LanguageStats {
+  files: number;
+  totalLines: number;
+  codeLines: number;
+  commentLines: number;
+  blankLines: number;
+}
+
+interface CodeCounterResult {
+  directory: string;
+  totalFiles: number;
+  totalLines: number;
+  totalCodeLines: number;
+  totalCommentLines: number;
+  totalBlankLines: number;
+  languages: Record<string, LanguageStats>;
+}
+
+interface LangDef {
+  name: string;
+  extensions: string[];
+  singleLineComment: string[];
+  blockCommentStart?: string;
+  blockCommentEnd?: string;
+}
+
+const LANGUAGES: LangDef[] = [
+  { name: "TypeScript", extensions: [".ts", ".tsx"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "JavaScript", extensions: [".js", ".jsx", ".mjs", ".cjs"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Python", extensions: [".py", ".pyw"], singleLineComment: ["#"], blockCommentStart: '"""', blockCommentEnd: '"""' },
+  { name: "Java", extensions: [".java"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "C/C++", extensions: [".c", ".cpp", ".cc", ".h", ".hpp"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "C#", extensions: [".cs"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Go", extensions: [".go"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Rust", extensions: [".rs"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Ruby", extensions: [".rb"], singleLineComment: ["#"], blockCommentStart: "=begin", blockCommentEnd: "=end" },
+  { name: "PHP", extensions: [".php"], singleLineComment: ["//", "#"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Swift", extensions: [".swift"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Kotlin", extensions: [".kt", ".kts"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "HTML", extensions: [".html", ".htm"], singleLineComment: [], blockCommentStart: "<!--", blockCommentEnd: "-->" },
+  { name: "CSS", extensions: [".css", ".scss", ".sass", ".less"], singleLineComment: ["//"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "JSON", extensions: [".json"], singleLineComment: [], },
+  { name: "YAML", extensions: [".yml", ".yaml"], singleLineComment: ["#"] },
+  { name: "Markdown", extensions: [".md", ".mdx"], singleLineComment: [] },
+  { name: "Shell", extensions: [".sh", ".bash", ".zsh"], singleLineComment: ["#"] },
+  { name: "SQL", extensions: [".sql"], singleLineComment: ["--"], blockCommentStart: "/*", blockCommentEnd: "*/" },
+  { name: "Lua", extensions: [".lua"], singleLineComment: ["--"], blockCommentStart: "--[[", blockCommentEnd: "]]" },
+];
+
+const EXT_TO_LANG: Record<string, LangDef> = {};
+for (const lang of LANGUAGES) {
+  for (const ext of lang.extensions) {
+    EXT_TO_LANG[ext] = lang;
+  }
+}
+
+function countLines(
+  filePath: string,
+  lang: LangDef
+): { totalLines: number; codeLines: number; commentLines: number; blankLines: number } {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return { totalLines: 0, codeLines: 0, commentLines: 0, blankLines: 0 };
+  }
+
+  const lines = content.split(/\r?\n/);
+  let blankLines = 0;
+  let commentLines = 0;
+  let codeLines = 0;
+  let inBlockComment = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === "") {
+      blankLines++;
+      continue;
+    }
+
+    if (inBlockComment) {
+      commentLines++;
+      if (lang.blockCommentEnd && trimmed.includes(lang.blockCommentEnd)) {
+        inBlockComment = false;
+      }
+      continue;
+    }
+
+    if (lang.blockCommentStart && trimmed.startsWith(lang.blockCommentStart)) {
+      commentLines++;
+      if (!lang.blockCommentEnd || !trimmed.includes(lang.blockCommentEnd, lang.blockCommentStart.length)) {
+        inBlockComment = true;
+      }
+      continue;
+    }
+
+    const isSingleComment = lang.singleLineComment.some((prefix) => trimmed.startsWith(prefix));
+    if (isSingleComment) {
+      commentLines++;
+    } else {
+      codeLines++;
+    }
+  }
+
+  return {
+    totalLines: lines.length,
+    codeLines,
+    commentLines,
+    blankLines,
+  };
+}
+
+function collectFiles(
+  dirPath: string,
+  depth: number,
+  maxDepth: number,
+  files: string[]
+): void {
+  if (maxDepth > 0 && depth >= maxDepth) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      if (["node_modules", ".git", "dist", "__pycache__", ".next", "coverage", "build"].includes(entry.name)) continue;
+      collectFiles(fullPath, depth + 1, maxDepth, files);
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (EXT_TO_LANG[ext]) {
+        files.push(fullPath);
+      }
+    }
+  }
+}
+
+export async function codeCounter(options: CodeCounterOptions): Promise<CodeCounterResult> {
+  const { dirPath, maxDepth = 10 } = options;
+  const resolvedPath = path.resolve(dirPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Directory not found: ${resolvedPath}`);
+  }
+
+  const files: string[] = [];
+  collectFiles(resolvedPath, 0, maxDepth, files);
+
+  const langStats: Record<string, LanguageStats> = {};
+  let totalLines = 0;
+  let totalCodeLines = 0;
+  let totalCommentLines = 0;
+  let totalBlankLines = 0;
+
+  for (const filePath of files) {
+    const ext = path.extname(filePath).toLowerCase();
+    const lang = EXT_TO_LANG[ext];
+    if (!lang) continue;
+
+    const counts = countLines(filePath, lang);
+
+    if (!langStats[lang.name]) {
+      langStats[lang.name] = { files: 0, totalLines: 0, codeLines: 0, commentLines: 0, blankLines: 0 };
+    }
+
+    langStats[lang.name].files++;
+    langStats[lang.name].totalLines += counts.totalLines;
+    langStats[lang.name].codeLines += counts.codeLines;
+    langStats[lang.name].commentLines += counts.commentLines;
+    langStats[lang.name].blankLines += counts.blankLines;
+
+    totalLines += counts.totalLines;
+    totalCodeLines += counts.codeLines;
+    totalCommentLines += counts.commentLines;
+    totalBlankLines += counts.blankLines;
+  }
+
+  // Sort languages by code lines descending
+  const sortedLangs: Record<string, LanguageStats> = {};
+  const sorted = Object.entries(langStats).sort((a, b) => b[1].codeLines - a[1].codeLines);
+  for (const [name, stats] of sorted) {
+    sortedLangs[name] = stats;
+  }
+
+  return {
+    directory: resolvedPath,
+    totalFiles: files.length,
+    totalLines,
+    totalCodeLines,
+    totalCommentLines,
+    totalBlankLines,
+    languages: sortedLangs,
+  };
+}

package/src/tools/dir-tree.ts

@@ -0,0 +1,108 @@
+import * as fs from "fs";
+import * as path from "path";
+
+interface DirTreeOptions {
+  dirPath: string;
+  maxDepth?: number;
+  ignorePatterns?: string[];
+}
+
+interface TreeResult {
+  tree: string;
+  totalDirs: number;
+  totalFiles: number;
+}
+
+const DEFAULT_IGNORE = ["node_modules", ".git", "dist", "__pycache__", ".next", ".cache", "coverage"];
+
+function shouldIgnore(name: string, ignorePatterns: string[]): boolean {
+  return ignorePatterns.some((pattern) => {
+    if (pattern.includes("*")) {
+      const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$");
+      return regex.test(name);
+    }
+    return name === pattern;
+  });
+}
+
+function buildTree(
+  dirPath: string,
+  prefix: string,
+  depth: number,
+  maxDepth: number,
+  ignorePatterns: string[],
+  stats: { dirs: number; files: number }
+): string[] {
+  if (maxDepth > 0 && depth >= maxDepth) {
+    return [];
+  }
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [`${prefix}[permission denied]`];
+  }
+
+  entries = entries.filter((e) => !shouldIgnore(e.name, ignorePatterns));
+  entries.sort((a, b) => {
+    if (a.isDirectory() && !b.isDirectory()) return -1;
+    if (!a.isDirectory() && b.isDirectory()) return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  const lines: string[] = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const isLast = i === entries.length - 1;
+    const connector = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    const childPrefix = isLast ? "    " : "\u2502   ";
+
+    if (entry.isDirectory()) {
+      stats.dirs++;
+      lines.push(`${prefix}${connector}${entry.name}/`);
+      const childLines = buildTree(
+        path.join(dirPath, entry.name),
+        prefix + childPrefix,
+        depth + 1,
+        maxDepth,
+        ignorePatterns,
+        stats
+      );
+      lines.push(...childLines);
+    } else {
+      stats.files++;
+      lines.push(`${prefix}${connector}${entry.name}`);
+    }
+  }
+
+  return lines;
+}
+
+export async function dirTree(options: DirTreeOptions): Promise<TreeResult> {
+  const { dirPath, maxDepth = 5, ignorePatterns = DEFAULT_IGNORE } = options;
+
+  const resolvedPath = path.resolve(dirPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Directory not found: ${resolvedPath}`);
+  }
+
+  const stat = fs.statSync(resolvedPath);
+  if (!stat.isDirectory()) {
+    throw new Error(`Not a directory: ${resolvedPath}`);
+  }
+
+  const stats = { dirs: 0, files: 0 };
+  const rootName = path.basename(resolvedPath);
+  const lines = [`${rootName}/`];
+  const childLines = buildTree(resolvedPath, "", 0, maxDepth, ignorePatterns, stats);
+  lines.push(...childLines);
+
+  return {
+    tree: lines.join("\n"),
+    totalDirs: stats.dirs,
+    totalFiles: stats.files,
+  };
+}

package/src/tools/duplicate-finder.ts

@@ -0,0 +1,145 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+
+interface DuplicateFinderOptions {
+  dirPath: string;
+  minSize?: number;
+  maxDepth?: number;
+}
+
+interface DuplicateGroup {
+  hash: string;
+  size: string;
+  sizeBytes: number;
+  files: string[];
+}
+
+interface DuplicateResult {
+  directory: string;
+  totalFilesScanned: number;
+  duplicateGroups: number;
+  totalDuplicateFiles: number;
+  wastedSpace: string;
+  wastedSpaceBytes: number;
+  groups: DuplicateGroup[];
+}
+
+function formatSize(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return (bytes / Math.pow(1024, i)).toFixed(2) + " " + units[i];
+}
+
+function collectFiles(
+  dirPath: string,
+  depth: number,
+  maxDepth: number,
+  files: { path: string; size: number }[]
+): void {
+  if (maxDepth > 0 && depth >= maxDepth) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      if (["node_modules", ".git", "dist", "__pycache__"].includes(entry.name)) continue;
+      collectFiles(fullPath, depth + 1, maxDepth, files);
+    } else if (entry.isFile()) {
+      try {
+        const stat = fs.statSync(fullPath);
+        files.push({ path: fullPath, size: stat.size });
+      } catch {
+        // Skip inaccessible files
+      }
+    }
+  }
+}
+
+function hashFile(filePath: string): string {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash("md5").update(content).digest("hex");
+}
+
+export async function duplicateFinder(options: DuplicateFinderOptions): Promise<DuplicateResult> {
+  const { dirPath, minSize = 1, maxDepth = 10 } = options;
+  const resolvedPath = path.resolve(dirPath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`Directory not found: ${resolvedPath}`);
+  }
+
+  const allFiles: { path: string; size: number }[] = [];
+  collectFiles(resolvedPath, 0, maxDepth, allFiles);
+
+  // Filter by minimum size
+  const filteredFiles = allFiles.filter((f) => f.size >= minSize);
+
+  // Group by size first (optimization: only hash files with matching sizes)
+  const sizeGroups: Record<number, { path: string; size: number }[]> = {};
+  for (const file of filteredFiles) {
+    if (!sizeGroups[file.size]) {
+      sizeGroups[file.size] = [];
+    }
+    sizeGroups[file.size].push(file);
+  }
+
+  // Hash only files that share a size
+  const hashGroups: Record<string, { path: string; size: number }[]> = {};
+  for (const [, group] of Object.entries(sizeGroups)) {
+    if (group.length < 2) continue;
+
+    for (const file of group) {
+      try {
+        const hash = hashFile(file.path);
+        if (!hashGroups[hash]) {
+          hashGroups[hash] = [];
+        }
+        hashGroups[hash].push(file);
+      } catch {
+        // Skip files that can't be read
+      }
+    }
+  }
+
+  // Build result groups (only actual duplicates)
+  const groups: DuplicateGroup[] = [];
+  let totalDuplicateFiles = 0;
+  let wastedSpaceBytes = 0;
+
+  for (const [hash, files] of Object.entries(hashGroups)) {
+    if (files.length < 2) continue;
+
+    const sizeBytes = files[0].size;
+    groups.push({
+      hash,
+      size: formatSize(sizeBytes),
+      sizeBytes,
+      files: files.map((f) => f.path),
+    });
+
+    totalDuplicateFiles += files.length;
+    wastedSpaceBytes += sizeBytes * (files.length - 1);
+  }
+
+  // Sort by wasted space descending
+  groups.sort((a, b) => b.sizeBytes * (b.files.length - 1) - a.sizeBytes * (a.files.length - 1));
+
+  return {
+    directory: resolvedPath,
+    totalFilesScanned: filteredFiles.length,
+    duplicateGroups: groups.length,
+    totalDuplicateFiles,
+    wastedSpace: formatSize(wastedSpaceBytes),
+    wastedSpaceBytes,
+    groups: groups.slice(0, 50),
+  };
+}