The findVersion tool helps you identify which version of a library is available in your Grounded Docs server, supporting both exact version matches and X-Range patterns.
MCP Tool Name: find_version
Source: src/tools/FindVersionTool.ts
Description: Find the best matching version for a library. Supports exact version matches and X-Range patterns (e.g., ‘5.x’, ‘5.2.x’).
Parameters
Library name to search for
Version pattern to match (exact or X-Range). If omitted, finds the latest version or checks for unversioned docs.
Version Pattern Support
Exact Version Match
library: "react", targetVersion: "18.2.0"
X-Range Pattern
library: "typescript", targetVersion: "5.x"
library: "typescript", targetVersion: "5.2.x"
No Version
library: "lodash", targetVersion: undefined
Response Structure
The best matching version found, or null if no match
Whether unversioned documentation exists for this library
Human-readable description of the result
TypeScript Types
interface FindVersionToolOptions {
library: string;
targetVersion?: string;
}
interface FindVersionToolResult {
bestMatch: string | null;
hasUnversioned: boolean;
message: string;
}
src/tools/FindVersionTool.ts:4-13 for complete type definitions.
Example Requests
Find Exact Version
{
"name": "find_version",
"arguments": {
"library": "react",
"targetVersion": "18.2.0"
}
}
Find X-Range Version
{
"name": "find_version",
"arguments": {
"library": "typescript",
"targetVersion": "5.x"
}
}
Find Latest or Unversioned
{
"name": "find_version",
"arguments": {
"library": "lodash"
}
}
Example Responses
Exact Match Found
{
"bestMatch": "18.2.0",
"hasUnversioned": false,
"message": "Best match: 18.2.0."
}
X-Range Match with Unversioned
{
"bestMatch": "5.4.2",
"hasUnversioned": true,
"message": "Best match: 5.4.2. Unversioned docs also available."
}
Only Unversioned Available
{
"bestMatch": null,
"hasUnversioned": true,
"message": "No matching version found for [email protected], but unversioned docs exist."
}
No Match
{
"bestMatch": null,
"hasUnversioned": false,
"message": "No matching version or unversioned documents found for [email protected]."
}
Error Cases
Invalid Library Name
Throws ValidationError:
{
"error": "Library name is required and must be a non-empty string."
}
Library Not Found
Throws VersionNotFoundInStoreError with available versions:
{
"error": "Library 'nonexistent' not found in store.",
"availableVersions": []
}
MCP Output
When called through MCP (see src/mcp/mcpServer.ts:270), the response is the message field:
or
Best match: 5.4.2. Unversioned docs also available.
Usage from MCP Clients
Claude Desktop
Find the best version of TypeScript 5.x in the indexed documentation.
Direct MCP Call
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
const result = await client.callTool({
name: 'find_version',
arguments: {
library: 'typescript',
targetVersion: '5.x'
}
});
Implementation Details
The tool validates input and delegates to the document service:
async execute(options: FindVersionToolOptions): Promise<FindVersionToolResult> {
const { library, targetVersion } = options;
// Validate library name
if (!library || typeof library !== "string" || library.trim() === "") {
throw new ValidationError(
"Library name is required and must be a non-empty string.",
this.constructor.name,
);
}
const libraryAndVersion = `${library}${targetVersion ? `@${targetVersion}` : ""}`;
// Find best version using document service
const { bestMatch, hasUnversioned } = await this.docService.findBestVersion(
library,
targetVersion,
);
// Build descriptive message
let message = "";
if (bestMatch) {
message = `Best match: ${bestMatch}.`;
if (hasUnversioned) {
message += " Unversioned docs also available.";
}
} else if (hasUnversioned) {
message = `No matching version found for ${libraryAndVersion}, but unversioned docs exist.`;
} else {
message = `No matching version or unversioned documents found for ${libraryAndVersion}.`;
}
return {
bestMatch,
hasUnversioned,
message,
};
}
src/tools/FindVersionTool.ts:32 for the complete implementation.
Version Matching Logic
The version matching follows semantic versioning rules:
- Exact Match: Returns the exact version if available
- X-Range Match: Returns the highest matching version
5.x matches 5.0.0, 5.1.0, 5.4.2 → returns 5.4.25.2.x matches 5.2.0, 5.2.1 → returns 5.2.1
- No Version: Checks for unversioned docs (version = empty string)
- Fallback: Returns null if no matches found
Use Cases
Before Searching
Check if a version exists before attempting to search:
const { bestMatch } = await findVersion({
library: "react",
targetVersion: "18.x"
});
if (bestMatch) {
await searchDocs({
library: "react",
version: bestMatch,
query: "useState hooks"
});
}
Version Discovery
Find what versions are available:
const result = await findVersion({
library: "typescript"
});
console.log(result.message);
// "Best match: 5.4.2. Unversioned docs also available."
Graceful Degradation
Fall back to unversioned docs if specific version not available:
const { bestMatch, hasUnversioned } = await findVersion({
library: "lodash",
targetVersion: "4.17.x"
});
const versionToUse = bestMatch || (hasUnversioned ? null : undefined);
