Vale MCP Server

Instructions

Implementation Reference

• src/index.ts:258-281 (handler)

  Handler logic for the 'vale_status' tool. Calls checkValeInstalled() helper and formats the response with installation status, version, platform info, and instructions if needed.
  case "vale_status": { debug("Checking Vale installation status..."); const valeCheck = await checkValeInstalled(); debug(`Vale installed: ${valeCheck.installed}, version: ${valeCheck.version}`); return { content: [ { type: "text", text: JSON.stringify({ installed: valeCheck.installed, version: valeCheck.version, platform: process.platform, installation_instructions: valeCheck.installed ? null : getInstallationInstructions(), message: valeCheck.installed ? `Vale is installed and ready to use (${valeCheck.version})` : "Vale is not installed. Please install it to use Vale linting tools.", }, null, 2), }, ], }; }
• src/index.ts:203-211 (schema)

  Input schema and metadata definition for the 'vale_status' tool, including name, description, and empty properties object indicating no input parameters required.
  { name: "vale_status", description: "Check if Vale (vale.sh) is installed and accessible. Use this first if other Vale tools fail. Returns installation status, version if available, and installation instructions for the current platform.", inputSchema: { type: "object", properties: {}, }, },
• src/vale-runner.ts:29-67 (helper)

  Helper function that implements the core logic: executes 'vale --version' command, caches the result, and returns installation status and version.
  export async function checkValeInstalled(): Promise<{ installed: boolean; version?: string; error?: string; }> { // Return cached result if already checked if (valeInstallCache.checked) { return { installed: valeInstallCache.installed, version: valeInstallCache.version, error: valeInstallCache.error, }; } // Perform the check try { const { stdout } = await execAsync("vale --version"); valeInstallCache = { checked: true, installed: true, version: stdout.trim(), }; } catch (error) { valeInstallCache = { checked: true, installed: false, error: error instanceof Error ? error.message : "Vale not found in PATH. To install Vale, go to https://vale.sh/docs/vale-cli/installation/", }; } return { installed: valeInstallCache.installed, version: valeInstallCache.version, error: valeInstallCache.error, }; }
• src/index.ts:244-248 (registration)

  Registration of tool list handler which exposes the 'vale_status' tool schema via the MCP ListToolsRequest.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: TOOLS, }; });
• src/index.ts:251-446 (registration)

  Registration of the general tool execution handler (CallToolRequestSchema) which dispatches to vale_status case based on tool name.
  server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; debug(`Tool called: ${name}`, JSON.stringify(args, null, 2)); try { switch (name) { case "vale_status": { debug("Checking Vale installation status..."); const valeCheck = await checkValeInstalled(); debug(`Vale installed: ${valeCheck.installed}, version: ${valeCheck.version}`); return { content: [ { type: "text", text: JSON.stringify({ installed: valeCheck.installed, version: valeCheck.version, platform: process.platform, installation_instructions: valeCheck.installed ? null : getInstallationInstructions(), message: valeCheck.installed ? `Vale is installed and ready to use (${valeCheck.version})` : "Vale is not installed. Please install it to use Vale linting tools.", }, null, 2), }, ], }; } case "vale_sync": { const { config_path } = args as { config_path?: string }; debug(`vale_sync called - config_path: ${config_path}`); // Check if Vale is available const valeCheck = await checkValeInstalled(); if (!valeCheck.installed) { return createValeNotInstalledResponse(); } // Determine which config to use const effectiveConfigPath = config_path || valeConfigPath; // Run vale sync const syncResult = await syncValeStyles(effectiveConfigPath); debug(`vale_sync result - success: ${syncResult.success}`); if (syncResult.success) { return { content: [ { type: "text", text: `✅ **Vale Sync Successful** ${syncResult.message} ${syncResult.output ? `**Output:**\n\`\`\`\n${syncResult.output}\n\`\`\`` : ""} The styles have been downloaded and are ready to use. You can now run \`check_file\` again.`, }, ], }; } else { return { content: [ { type: "text", text: `❌ **Vale Sync Failed** ${syncResult.message} ${syncResult.error ? `**Error:**\n\`\`\`\n${syncResult.error}\n\`\`\`` : ""} Please check your .vale.ini configuration and ensure: 1. The StylesPath is correct 2. Packages are properly defined 3. You have internet connectivity to download packages See Vale documentation: https://vale.sh/docs/topics/packages/`, }, ], }; } } 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, }, }, }; } default: debug(`Unknown tool called: ${name}`); return { content: [ { type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}`, }), }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; const errorDetails = error instanceof Error ? error.stack : "No details available"; // Check if this is an E100 error about missing styles (Fix #4: efficient detection) if (isStylesDirectoryError(errorMessage)) { return { content: [ { type: "text", text: `❌ **Vale Configuration Error** ${errorMessage} This error indicates that Vale's styles directory is missing or the configured packages haven't been downloaded yet. **Solution:** Run the \`vale_sync\` tool to download the required style packages: \`\`\` vale_sync \`\`\` This will: 1. Read your .vale.ini configuration 2. Download all configured style packages 3. Create the necessary styles directory After running \`vale_sync\`, you can try \`check_file\` again. For more information, see: https://vale.sh/docs/topics/packages/`, }, ], }; } return { content: [ { type: "text", text: JSON.stringify({ error: errorMessage, details: errorDetails, }), }, ], }; } });