filesystem-mcp

Instructions

Implementation Reference

• src/tools/stat.ts:56-71 (handler)

  The `handleGetFileInfo` function executes the logic to retrieve and format file information using `getFileInfo`.

  async function handleGetFileInfo(
    args: z.infer<typeof GetFileInfoInputSchema>,
    signal?: AbortSignal
  ): Promise<ToolResponse<z.infer<typeof GetFileInfoOutputSchema>>> {
    const info = await getFileInfo(args.path, {
      includeMimeType: true,
      ...(signal ? { signal } : {}),
    });
  
    const structured: z.infer<typeof GetFileInfoOutputSchema> = {
      ok: true,
      info: buildFileInfoPayload(info),
    };
  
    return buildToolResponse(formatFileInfoDetails(info), structured);
  }

• src/tools/stat.ts:73-125 (registration)

  The `registerGetFileInfoTool` function registers the 'stat' tool with the MCP server, wrapping the handler with validation and tool registration options.

  export function registerGetFileInfoTool(
    server: McpServer,
    options: ToolRegistrationOptions = {}
  ): void {
    const handler = (
      args: z.infer<typeof GetFileInfoInputSchema>,
      extra: ToolExtra
    ): Promise<ToolResult<z.infer<typeof GetFileInfoOutputSchema>>> =>
      executeToolWithDiagnostics({
        toolName: 'stat',
        extra,
        outputSchema: GetFileInfoOutputSchema,
        timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
        context: { path: args.path },
        run: (signal) => handleGetFileInfo(args, signal),
        onError: (error) =>
          buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
      });
  
    const wrappedHandler = wrapToolHandler(handler, {
      guard: options.isInitialized,
      progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
      completionMessage: (args, result) => {
        const name = path.basename(args.path);
        if (result.isError) return `🕮 stat: ${name} • failed`;
        const sc = result.structuredContent;
        if (!sc.info) return `🕮 stat: ${name} • failed`;
        return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
      },
    });
  
    const validatedHandler = withValidatedArgs(
      GetFileInfoInputSchema,
      wrappedHandler
    );
  
    if (
      registerToolTaskIfAvailable(
        server,
        'stat',
        GET_FILE_INFO_TOOL,
        validatedHandler,
        options.iconInfo,
        options.isInitialized
      )
    )
      return;
    server.registerTool(
      'stat',
      withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo),
      validatedHandler
    );
  }

• src/tools/stat.ts:30-40 (schema)

  The `GET_FILE_INFO_TOOL` constant defines the tool's name, description, and schema configuration.

  export const GET_FILE_INFO_TOOL: ToolContract = {
    name: 'stat',
    title: 'Get File Info',
    description:
      'Get file/directory metadata: size, modified, permissions, mime, tokenEstimate. ' +
      'Use `tokenEstimate` (size\u00f74) to pre-screen token cost before reading.',
    inputSchema: GetFileInfoInputSchema,
    outputSchema: GetFileInfoOutputSchema,
    annotations: READ_ONLY_TOOL_ANNOTATIONS,
    taskSupport: 'forbidden',
  } as const;