feat(mcp): add detailed descriptions to Zod schemas for better API documentation #1613
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
There was a problem hiding this comment.
Pull Request Overview
This PR enriches API documentation by adding descriptive metadata to Zod schemas in the textlint MCP server.
- Added
.describe()calls to input schema fields to clarify expected values. - Added
.describe()calls to output schema fields (line, column, severity, fix, output) for better client understanding. - Applied these enhancements uniformly across four MCP endpoints without altering validation logic.
Comments suppressed due to low confidence (3)
packages/textlint/src/mcp/server.ts:231
- This description is inconsistent with other endpoints. Consider using "Fixed content if available" to match the pattern used elsewhere.
output: z.string().optional().describe("Fixed content")
packages/textlint/src/mcp/server.ts:295
- This description is inconsistent with other endpoints. Consider using "Fixed content if available" for consistency.
output: z.string().optional().describe("Fixed content"),
packages/textlint/src/mcp/server.ts:152
- The
filePathfield in this output schema lacks a.describe()call; adding one would improve API documentation consistency.
filePath: z.string(),
Comment on lines
90
to
103
| z.object({ | ||
| ruleId: z.string().optional(), | ||
| message: z.string(), | ||
| line: z.number(), | ||
| column: z.number(), | ||
| severity: z.number(), | ||
| line: z.number().describe("Line number (1-based)"), | ||
| column: z.number().describe("Column number (1-based)"), | ||
| severity: z.number().describe("Severity level: 1=warning, 2=error, 3=info"), | ||
| fix: z | ||
| .object({ | ||
| range: z.array(z.number()), | ||
| text: z.string() | ||
| range: z.array(z.number()).describe("Text range [start, end] (0-based)"), | ||
| text: z.string().describe("Replacement text") | ||
| }) | ||
| .optional() | ||
| .describe("Fix suggestion if available") | ||
| }) |
There was a problem hiding this comment.
[nitpick] The message object schema is duplicated across multiple endpoints; consider extracting it into a shared constant to reduce repetition.
Copilot uses AI. Check for mistakes.
- Update outputSchema snapshot to include new descriptions for severity, line, column, fix fields - Add comprehensive validation for input schema descriptions - Add test to verify all tools have proper descriptions for severity levels - Verify 1-based vs 0-based indexing documentation is correct
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
This PR enhances the MCP (Model Context Protocol) server by adding detailed descriptions to all Zod schemas in the textlint MCP server. These descriptions improve API documentation and make the server more user-friendly for MCP clients.
Changes
Schema Descriptions Added
Input Schemas:
filePaths: Added descriptions for file path arrays and individual file pathstext: Added description for text content to be linted/fixedstdinFilename: Added description explaining its purpose as context (e.g., 'stdin.md')Output Schemas:
severity: Added detailed description explaining the severity levels:1: warning - Issues that should be addressed but don't prevent processing2: error - Critical issues that need to be fixed3: info - Informational messages for guidance or suggestionsline: Added description clarifying it's 1-based indexingcolumn: Added description clarifying it's 1-based indexingfix.range: Added description explaining it's 0-based text range [start, end]fix.text: Added description as "Replacement text"fix: Added description as "Fix suggestion if available"output: Added descriptions for fixed content availabilityBenefits
Tools Updated
All four MCP tools have been enhanced:
lintFile- Lint files using textlintlintText- Lint text using textlintgetLintFixedFileContent- Get lint-fixed content of filesgetLintFixedTextContent- Get lint-fixed content of textCompatibility
This change is fully backward compatible as it only adds
.describe()calls to existing Zod schemas without changing the actual validation logic or API structure.References