filesystem-mcp

Instructions

Implementation Reference

• src/handlers/chown-items.ts:119-140 (handler)

  The main handler function for the 'chown_items' tool. It parses and validates input arguments, performs asynchronous chown operations on multiple file paths using fs.chown, handles errors and results with Promise.allSettled, sorts outputs by original order, and returns a JSON-formatted response.

  const handleChownItemsFunc = async (args: unknown): Promise<McpToolResponse> => {
    const { paths: relativePaths, uid, gid } = parseAndValidateArgs(args);
  
    const chownPromises = relativePaths.map((relativePath) =>
      processSingleChownOperation(relativePath, uid, gid),
    );
    const settledResults = await Promise.allSettled(chownPromises);
  
    const outputResults = processSettledResults(settledResults, relativePaths);
  
    // Sort results by original path order for predictability
    const originalIndexMap = new Map(relativePaths.map((p, i) => [p.replaceAll('\\', '/'), i]));
    outputResults.sort((a, b) => {
      const indexA = originalIndexMap.get(a.path) ?? Infinity;
      const indexB = originalIndexMap.get(b.path) ?? Infinity;
      return indexA - indexB;
    });
  
    return {
      content: [{ type: 'text', text: JSON.stringify(outputResults, undefined, 2) }],
    };
  };

• src/handlers/chown-items.ts:13-22 (schema)

  Zod schema defining the input arguments for the 'chown_items' tool: an array of relative paths (non-empty), integer UID, and integer GID.

  export const ChownItemsArgsSchema = z
    .object({
      paths: z
        .array(z.string())
        .min(1, { message: 'Paths array cannot be empty' })
        .describe('An array of relative paths.'),
      uid: z.number().int({ message: 'UID must be an integer' }).describe('User ID.'),
      gid: z.number().int({ message: 'GID must be an integer' }).describe('Group ID.'),
    })
    .strict();

• src/handlers/chown-items.ts:143-148 (registration)

  The tool definition object for 'chown_items', specifying name, description, input schema, and handler function reference.

  export const chownItemsToolDefinition = {
    name: 'chown_items',
    description: 'Change owner (UID) and group (GID) for multiple specified files/directories.',
    inputSchema: ChownItemsArgsSchema,
    handler: handleChownItemsFunc,
  };

• src/handlers/index.ts:8-56 (registration)

  Import and inclusion of chownItemsToolDefinition in the allToolDefinitions array for tool registration.

  import { chownItemsToolDefinition } from './chown-items.js';
  import { moveItemsToolDefinition } from './move-items.js';
  import { copyItemsToolDefinition } from './copy-items.js';
  import { searchFilesToolDefinition } from './search-files.js';
  import { replaceContentToolDefinition } from './replace-content.js';
  import { handleApplyDiff } from './apply-diff.js';
  import { applyDiffInputSchema, ApplyDiffOutput } from '../schemas/apply-diff-schema.js';
  import fs from 'node:fs';
  import path from 'node:path';
  
  // Define the structure for a tool definition (used internally and for index.ts)
  import type { ZodType } from 'zod';
  import type { McpToolResponse } from '../types/mcp-types.js';
  
  // Define local interfaces based on usage observed in handlers
  // Define the structure for a tool definition
  // Matches the structure in individual tool files like applyDiff.ts
  export interface ToolDefinition<TInput = unknown, TOutput = unknown> {
    name: string;
    description: string;
    inputSchema: ZodType<TInput>;
    outputSchema?: ZodType<TOutput>;
    handler: (args: TInput) => Promise<McpToolResponse>; // Changed _args to args
  }
  
  // Helper type to extract input type from a tool definition
  export type ToolInput<T extends ToolDefinition> =
    T extends ToolDefinition<infer I, unknown> ? I : never;
  
  // Define a more specific type for our tool definitions to avoid naming conflicts
  type HandlerToolDefinition = {
    name: string;
    description: string;
    inputSchema: ZodType<unknown>;
    outputSchema?: ZodType<unknown>;
    handler: (args: unknown) => Promise<{ content: Array<{ type: 'text'; text: string }> }>;
  };
  
  // Aggregate all tool definitions into a single array
  // Use our more specific type to avoid naming conflicts
  export const allToolDefinitions: HandlerToolDefinition[] = [
    listFilesToolDefinition,
    statItemsToolDefinition,
    readContentToolDefinition,
    writeContentToolDefinition,
    deleteItemsToolDefinition,
    createDirectoriesToolDefinition,
    chmodItemsToolDefinition,
    chownItemsToolDefinition,

• src/handlers/chown-items.ts:77-97 (helper)

  Core helper function that resolves the path, checks against project root, and performs the actual fs.chown operation for a single path, with error handling.

  async function processSingleChownOperation(
    relativePath: string,
    uid: number,
    gid: number,
  ): Promise<ChownResult> {
    const pathOutput = relativePath.replaceAll('\\', '/');
    try {
      const targetPath = await resolvePath(relativePath);
      if (targetPath === PROJECT_ROOT) {
        return {
          path: pathOutput,
          success: false,
          error: 'Changing ownership of the project root is not allowed.',
        };
      }
      await fs.chown(targetPath, uid, gid);
      return { path: pathOutput, success: true, uid, gid };
    } catch (error: unknown) {
      return handleChownError(error, relativePath, pathOutput);
    }
  }