check_file

Instructions

Implementation Reference

• src/vale-runner.ts:270-336 (handler)

  The core handler function that implements the check_file tool logic. It validates the file path, executes 'vale --output=JSON' on the file, handles output parsing, normalizes issues, generates a summary, and formats a Markdown response with structured data.

  export async function checkFile(
    filePath: string,
    configPath?: string
  ): Promise<CheckFileResult> {
    // Verify file exists and is readable (Fix #9: async file operations)
    try {
      await fs.access(filePath, fsSync.constants.R_OK);
    } catch {
      throw new Error(`File not found or not readable: ${filePath}`);
    }
  
    // Resolve to absolute path
    const absolutePath = path.isAbsolute(filePath)
      ? filePath
      : path.resolve(process.cwd(), filePath);
  
    // Build Vale command
    let command = `vale --output=JSON`;
    
    // Only use --config if explicitly provided (e.g., from VALE_CONFIG_PATH env var)
    // Otherwise let Vale do its natural upward search from the file's location
    if (configPath) {
      command += ` --config="${configPath}"`;
      console.error(`Using explicit config: ${configPath}`);
    } else {
      console.error(`Letting Vale search for config from: ${path.dirname(absolutePath)}`);
    }
    
    command += ` "${absolutePath}"`;
  
    // Run Vale from the file's directory so it searches upward from there
    const execOptions: any = { 
      encoding: 'utf-8',
      cwd: path.dirname(absolutePath)
    };
  
    // Execute Vale
    let stdout = "";
    try {
      const result = await execAsync(command, execOptions);
      stdout = typeof result.stdout === 'string' ? result.stdout : result.stdout.toString('utf-8');
    } catch (error: any) {
      // Vale returns non-zero exit code when there are issues
      // But it still outputs JSON to stdout
      if (error.stdout) {
        stdout = error.stdout;
      } else {
        const errorMessage = error.stderr || error.message || "Unknown error";
        throw new Error(
          `Vale execution failed: ${errorMessage}`
        );
      }
    }
  
    // Parse output
    const rawOutput = parseValeOutput(stdout);
    const issues = normalizeIssues(rawOutput);
    const summary = generateSummary(issues);
    const formatted = formatValeResults(issues, summary, absolutePath);
  
    return {
      formatted,
      file: absolutePath,
      issues,
      summary,
    };
  }

• src/index.ts:227-240 (registration)

  Registration of the 'check_file' tool in the MCP server's TOOLS array, including name, description, and input schema.

    name: "check_file",
    description:
      "Lint a file at a specific path against Vale style rules. Returns issues found with their locations and severity. If Vale is not installed, returns error with installation guidance.",
    inputSchema: {
      type: "object",
      properties: {
        path: {
          type: "string",
          description: "Absolute or relative path to the file to check",
        },
      },
      required: ["path"],
    },
  },

• src/index.ts:340-383 (handler)

  The MCP protocol request handler (switch case) for executing the 'check_file' tool: parameter validation, Vale availability check, delegates to checkFile implementation, and response formatting.

  case "check_file": {
    const { path: filePath } = args as { path: string };
  
    debug(`check_file called - path: ${filePath}`);
  
    if (!filePath) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: "Missing required parameter: path",
            }),
          },
        ],
      };
    }
  
    // Check if Vale is available
    const valeCheck = await checkValeInstalled();
    if (!valeCheck.installed) {
      return createValeNotInstalledResponse();
    }
  
    const result = await checkFile(filePath, valeConfigPath);
  
    debug(`check_file result - file: ${result.file}, issues found: ${result.issues.length}, errors: ${result.summary.errors}, warnings: ${result.summary.warnings}, suggestions: ${result.summary.suggestions}`);
  
    return {
      content: [
        {
          type: "text",
          text: result.formatted,
        },
      ],
      _meta: {
        structured_data: {
          file: result.file,
          issues: result.issues,
          summary: result.summary,
        },
      },
    };
  }

• src/types.ts:54-61 (schema)

  TypeScript interface defining the return type of the checkFile function, used for input/output structure of the check_file tool.

   * Result structure for check_file tool
   */
  export interface CheckFileResult {
    formatted: string;
    file: string;
    issues: NormalizedValeIssue[];
    summary: ValeSummary;
  }

• src/index.ts:230-239 (schema)

  JSON Schema for input validation of the check_file tool (path parameter).

  inputSchema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "Absolute or relative path to the file to check",
      },
    },
    required: ["path"],
  },