file_write

Instructions

Implementation Reference

• src/tools/file-operations.ts:126-168 (handler)

  The async handler function that executes the file_write tool logic. It resolves the path, creates parent directories via fs.mkdir(recursive), writes the file with the specified encoding, and returns a JSON result with success info (path, bytes written, timestamp). On error, returns an error message.

      async ({ filePath, content, encoding }) => {
        try {
          const resolvedPath = path.resolve(filePath);
  
          // Create parent directories if needed
          const dir = path.dirname(resolvedPath);
          await fs.mkdir(dir, { recursive: true });
  
          await fs.writeFile(resolvedPath, content, { encoding: encoding as BufferEncoding });
  
          const stats = await fs.stat(resolvedPath);
  
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(
                  {
                    success: true,
                    path: resolvedPath,
                    bytesWritten: stats.size,
                    timestamp: stats.mtime.toISOString(),
                  },
                  null,
                  2
                ),
              },
            ],
          };
        } catch (err: any) {
          return {
            content: [
              {
                type: "text" as const,
                text: `File Write Error: ${err.message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/tools/file-operations.ts:118-125 (schema)

  Zod schema definitions for file_write tool inputs: filePath (string), content (string), and encoding (string, default utf-8).

  {
    filePath: z.string().describe("Path to the file to write."),
    content: z.string().describe("Content to write to the file."),
    encoding: z
      .string()
      .default("utf-8")
      .describe("Character encoding (default: utf-8)."),
  },

• src/index.ts:48-49 (registration)

  Registration call: registerFileWriteTool(this.server) invoked in the McpToolkitServer.registerTools() method.

  registerFileWriteTool(this.server);
  registerFileListTool(this.server);

• src/tools/file-operations.ts:104-168 (registration)

  The registerFileWriteTool function that registers the tool on the MCP server using server.tool('file_write', ...) with the schema, description, and handler.

  export function registerFileWriteTool(server: McpServer): void {
    server.tool(
      "file_write",
      `Write content to a file on the local filesystem.
  
  Features:
    - Creates parent directories automatically if they don't exist
    - Overwrites existing files or creates new ones
    - Supports any text encoding (default: UTF-8)
  
  Use cases:
    - Saving generated code, configs, or data
    - Creating log files
    - Writing reports or exports`,
      {
        filePath: z.string().describe("Path to the file to write."),
        content: z.string().describe("Content to write to the file."),
        encoding: z
          .string()
          .default("utf-8")
          .describe("Character encoding (default: utf-8)."),
      },
      async ({ filePath, content, encoding }) => {
        try {
          const resolvedPath = path.resolve(filePath);
  
          // Create parent directories if needed
          const dir = path.dirname(resolvedPath);
          await fs.mkdir(dir, { recursive: true });
  
          await fs.writeFile(resolvedPath, content, { encoding: encoding as BufferEncoding });
  
          const stats = await fs.stat(resolvedPath);
  
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(
                  {
                    success: true,
                    path: resolvedPath,
                    bytesWritten: stats.size,
                    timestamp: stats.mtime.toISOString(),
                  },
                  null,
                  2
                ),
              },
            ],
          };
        } catch (err: any) {
          return {
            content: [
              {
                type: "text" as const,
                text: `File Write Error: ${err.message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/utils/helpers.ts:6-34 (helper)

  Helper types (ToolResult) and utility functions (textResult, errorResult, jsonResult) used by the handler for constructing responses. Though the handler inlines its own JSON.stringify(jsonResult-style) patterns.

  export interface ToolResult {
    content: Array<{ type: "text"; text: string }>;
    isError?: boolean;
  }
  
  /** Helper to build a success text response. */
  export function textResult(text: string): ToolResult {
    return { content: [{ type: "text" as const, text }] };
  }
  
  /** Helper to build an error text response. */
  export function errorResult(message: string): ToolResult {
    return {
      content: [{ type: "text" as const, text: message }],
      isError: true,
    };
  }
  
  /** Helper to JSON-stringify and wrap in a text result. */
  export function jsonResult(data: unknown, pretty = true): ToolResult {
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(data, null, pretty ? 2 : 0),
        },
      ],
    };
  }