Enhance MCP Server Support with 2025-06-18 Specification Updates

[azu]

Overview

The textlint MCP server should be enhanced to support the latest MCP specification changes from 2025-06-18. This will improve LLM integration and user experience significantly.

Current Implementation Status

• MCP SDK Version: @modelcontextprotocol/sdk@^1.12.3
• Available Tools: 4 tools (lintFile, lintText, getLintFixedFileContent, getLintFixedTextContent)
• Transport: stdio
• Current Issue: All tools return JSON.stringify(result) as plain text, making it difficult for LLMs to parse results effectively

Proposed Improvements

🎯 High Priority

1. Structured Tool Output Support

Problem: Currently all tools return serialized JSON as text
Solution: Implement structured content alongside text content

// Current
return { 
  content: [{ type: "text", text: JSON.stringify(result) }] 
};

// Proposed
return {
  content: [{ 
    type: "text", 
    text: `Found ${result.messages.length} issues in ${result.filePath}` 
  }],
  structuredContent: {
    filePath: result.filePath,
    messages: result.messages,
    errorCount: result.errorCount,
    warningCount: result.warningCount,
    fixableErrorCount: result.fixableErrorCount,
    fixableWarningCount: result.fixableWarningCount
  }
};

2. Output Schema Definition

Add outputSchema to each tool for better type safety and LLM understanding:

const lintFileOutputSchema = {
  type: "object",
  properties: {
    filePath: { type: "string" },
    messages: {
      type: "array",
      items: {
        type: "object",
        properties: {
          ruleId: { type: ["string", "null"] },
          severity: { type: "number" },
          message: { type: "string" },
          line: { type: "number" },
          column: { type: "number" }
        }
      }
    },
    errorCount: { type: "number" },
    warningCount: { type: "number" }
  }
};

3. Enhanced Error Handling

Proper use of isError flag and detailed error information:

try {
  const results = await linter.lintFiles(filePaths);
  return { content: [...], structuredContent: {...} };
} catch (error) {
  return {
    content: [{
      type: "text",
      text: `Error: ${error.message}`
    }],
    isError: true
  };
}

📋 Medium Priority

4. Title Field Addition

Add human-friendly display names for tools:

server.tool(
  "lintFile",
  "File Linter", // title field
  "Lint files using textlint configuration and rules",
  // ...
);

5. Resource Links Support

Include links to linted files in results:

return {
  content: [
    { type: "text", text: "Linting completed" },
    {
      type: "resource_link",
      uri: `file://${path.resolve(filePath)}`,
      name: path.basename(filePath),
      description: "Linted file",
      mimeType: "text/plain"
    }
  ],
  structuredContent: { /* ... */ }
};

6. New Tool Addition

• Config Info Tool: getConfigInfo - Get current textlint configuration
• Available Rules Tool: listAvailableRules - List all available rules
• Rule Documentation Tool: getRuleDocumentation - Get documentation for specific rules

🔧 Low Priority

7. _meta Field Addition

Add metadata to tool definitions:

const toolDefinition = {
  name: "lintFile",
  title: "File Linter",
  description: "Lint files using textlint",
  inputSchema: { /* ... */ },
  outputSchema: { /* ... */ },
  _meta: {
    category: "linting",
    tags: ["text", "markdown", "lint"],
    version: "1.0.0"
  }
};

Implementation Phases

Phase 1 (Essential Improvements)

1. Structured Tool Output implementation
2. Output Schema definition
3. Error Handling enhancement

Phase 2 (Feature Expansion)

1. Title Field addition
2. Resource Links implementation
3. New Tools addition

Phase 3 (Optimization)

1. _meta Field addition
2. Performance optimization
3. Detailed logging features

Expected Benefits

• 🤖 Improved LLM Experience: Structured data makes result parsing easier
• 🔍 Better Debugging: More detailed error information and resource links
• 📚 Enhanced Usability: Better tool discoverability and understanding
• 🚀 Extensibility: Foundation for easier future feature additions

MCP 2025-06-18 Specification References

• Structured Tool Output
• Resource Links
• Output Schema
• Changelog

Next Steps

1. Update MCP SDK to latest version
2. Start Phase 1 implementation
3. Enhance test coverage
4. Update documentation

This enhancement will make textlint's MCP support compliant with the latest specification and significantly improve LLM integration effectiveness.

[azu]

Phase 1 is implemented.