get_project_files

Instructions

Implementation Reference

• src/tools/project-tools.ts:1732-1750 (handler)

  The main handler function for the get_project_files tool. Normalizes args, validates project args, builds a recursive file tree (with optional maxDepth and extensions filter), and returns the tree as JSON.

  export async function handleGetProjectFiles(args: OperationParams) {
    args = normalizeParameters(args);
    const v = validateProjectArgs(args);
    if ('isError' in v) return v;
  
    try {
      const maxDepth = typeof args.maxDepth === 'number' ? args.maxDepth : -1;
      const extensions = Array.isArray(args.extensions)
        ? (args.extensions as string[]).map((e) => e.toLowerCase().replace(/^\./, ''))
        : null;
      const tree = buildFilesystemTree(v.projectPath, '', maxDepth, 0, extensions);
      return { content: [{ type: 'text', text: JSON.stringify(tree) }] };
    } catch (error: unknown) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      return createErrorResponse(`Failed to get project files: ${errorMessage}`, [
        'Check if the project directory is accessible',
      ]);
    }
  }

• src/tools/project-tools.ts:1455-1495 (helper)

  Recursive helper function that builds a nested FileTreeNode structure for the project directory. Skips hidden (dot-prefixed) entries, respects maxDepth, and filters by extensions if provided.

  function buildFilesystemTree(
    currentPath: string,
    relativePath: string,
    maxDepth: number,
    currentDepth: number,
    extensions: string[] | null,
  ): FileTreeNode {
    const name = basename(currentPath);
    const node: FileTreeNode = { name, type: 'dir', path: relativePath || '.' };
    if (maxDepth !== -1 && currentDepth >= maxDepth) {
      node.children = [];
      return node;
    }
    const children: FileTreeNode[] = [];
    try {
      const entries = readdirSync(currentPath, { withFileTypes: true });
      for (const entry of entries) {
        if (entry.name.startsWith('.')) continue;
        const childRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
        if (entry.isDirectory()) {
          children.push(
            buildFilesystemTree(
              join(currentPath, entry.name),
              childRelPath,
              maxDepth,
              currentDepth + 1,
              extensions,
            ),
          );
        } else if (entry.isFile()) {
          const ext = entry.name.includes('.') ? entry.name.split('.').pop()!.toLowerCase() : '';
          if (extensions && !extensions.includes(ext)) continue;
          children.push({ name: entry.name, type: 'file', path: childRelPath, extension: ext });
        }
      }
    } catch (err) {
      logDebug(`buildFilesystemTree error at ${currentPath}: ${err}`);
    }
    node.children = children;
    return node;
  }

• src/tools/project-tools.ts:1447-1453 (helper)

  TypeScript interface for the file tree node used by buildFilesystemTree and returned by handleGetProjectFiles.

  interface FileTreeNode {
    name: string;
    type: 'file' | 'dir';
    path: string;
    extension?: string;
    children?: FileTreeNode[];
  }

• src/tools/project-tools.ts:476-497 (schema)

  Tool definition (schema) for get_project_files, registered in projectToolDefinitions. Declares inputSchema with projectPath (required), maxDepth, and extensions.

    name: 'get_project_files',
    description:
      'Return a recursive file tree of a Godot project as nested { name, type, path, extension?, children? } objects. Use to discover project structure when paths are unknown. Pass extensions to filter (e.g. ["gd","tscn"]); maxDepth caps recursion (-1 unlimited). Skips hidden (dot-prefixed) entries and the .mcp directory.',
    annotations: { readOnlyHint: true },
    inputSchema: {
      type: 'object',
      properties: {
        projectPath: { type: 'string', description: 'Path to the Godot project directory' },
        maxDepth: {
          type: 'number',
          description: 'Maximum recursion depth. -1 means unlimited (default: -1)',
        },
        extensions: {
          type: 'array',
          items: { type: 'string' },
          description:
            'Filter to only these file extensions (e.g. ["gd", "tscn"]). Omit to include all.',
        },
      },
      required: ['projectPath'],
    },
  },

• src/dispatch.ts:95-95 (registration)

  Registration of the get_project_files tool in the dispatch table, mapping the tool name to the handleGetProjectFiles handler.

  get_project_files: (_runner, args) => handleGetProjectFiles(args),