@mofaggolhoshen/dev-assist-mcp 1.0.4 → 1.0.6

package/dist/storage/markdownKnowledgeStore.js

@@ -0,0 +1,267 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import Fuse from "fuse.js";
+import { glob } from "glob";
+import { resolveSafePath } from "../tools/fs/safePath.js";
+import { markdownDocFrontmatterSchema, markdownSnippetFrontmatterSchema, } from "../schemas/markdownKnowledge.js";
+const TOKEN_SYNONYMS = {
+    jwt: ["bearer", "token", "auth"],
+    bearer: ["jwt", "token"],
+    polly: ["resilience", "retry", "circuit-breaker"],
+    resiliency: ["resilience", "polly"],
+    efcore: ["entityframework", "entity-framework"],
+    entityframework: ["efcore", "entity-framework"],
+    redis: ["cache", "caching"],
+    masstransit: ["messaging", "bus", "saga"],
+    saga: ["state-machine", "workflow"],
+};
+async function readMarkdownFile(filePath) {
+    return fs.readFile(filePath, "utf-8");
+}
+export async function loadSnippetDocuments() {
+    const snippetsRoot = resolveSafePath("snippets");
+    const files = await glob("**/*.md", {
+        cwd: snippetsRoot,
+        nodir: true,
+        ignore: ["**/node_modules/**", "**/.git/**"],
+    });
+    const docs = [];
+    for (const relativePath of files) {
+        const absolutePath = path.join(snippetsRoot, relativePath);
+        const raw = await readMarkdownFile(absolutePath);
+        const parsed = matter(raw);
+        const fm = markdownSnippetFrontmatterSchema.parse(parsed.data);
+        const stat = await fs.stat(absolutePath);
+        const updatedAt = fm.updatedAt ?? stat.mtime.toISOString();
+        docs.push({
+            id: fm.id,
+            name: fm.name ?? fm.id,
+            title: fm.title,
+            summary: fm.summary,
+            updatedAt,
+            framework: fm.framework,
+            version: fm.version,
+            language: fm.language,
+            category: fm.category,
+            tags: fm.tags ?? [],
+            difficulty: fm.difficulty,
+            bestPractices: fm.bestPractices ?? [],
+            pitfalls: fm.pitfalls ?? [],
+            securityNotes: fm.securityNotes ?? [],
+            body: parsed.content.trim(),
+            path: `snippets/${relativePath.replace(/\\/g, "/")}`,
+        });
+    }
+    return docs;
+}
+export async function findSnippetByName(snippetName) {
+    const docs = await loadSnippetDocuments();
+    return (docs.find((d) => d.name === snippetName || d.id === snippetName) ?? null);
+}
+export async function searchSnippetDocuments(query) {
+    return searchSnippetDocumentsWithOptions(query, {});
+}
+function normalize(value) {
+    return value.trim().toLowerCase();
+}
+function normalizeText(value) {
+    return normalize(value).replace(/[^a-z0-9.+-]+/g, " ").replace(/\s+/g, " ");
+}
+function tokenize(value) {
+    return normalizeText(value)
+        .split(" ")
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function expandQuery(query) {
+    const tokens = tokenize(query);
+    const expanded = new Set(tokens);
+    for (const token of tokens) {
+        const synonyms = TOKEN_SYNONYMS[token] ?? [];
+        for (const synonym of synonyms)
+            expanded.add(synonym);
+    }
+    const expandedQuery = Array.from(expanded).join(" ");
+    return {
+        normalized: normalizeText(query),
+        expanded: expandedQuery,
+        tokens,
+    };
+}
+function extractVersionHints(query, explicitVersion) {
+    const hints = new Set();
+    if (explicitVersion)
+        hints.add(normalize(explicitVersion));
+    const normalizedQuery = normalizeText(query);
+    const patterns = [
+        /\.net\s*\d+/g,
+        /dotnet\s*\d+/g,
+        /asp\.net\s*\d+/g,
+        /net\s*\d+/g,
+    ];
+    for (const pattern of patterns) {
+        const matches = normalizedQuery.match(pattern) ?? [];
+        for (const match of matches) {
+            hints.add(normalize(match).replace(/\s+/g, ""));
+        }
+    }
+    return Array.from(hints);
+}
+function matchesVersion(docVersion, requested) {
+    if (!docVersion)
+        return false;
+    const a = normalize(docVersion).replace(/\s+/g, "");
+    const b = normalize(requested).replace(/\s+/g, "");
+    return a.includes(b) || b.includes(a);
+}
+function computeFreshnessScore(updatedAt) {
+    if (!updatedAt)
+        return 0;
+    const date = new Date(updatedAt);
+    if (Number.isNaN(date.getTime()))
+        return 0;
+    const ageDays = (Date.now() - date.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageDays <= 7)
+        return 1;
+    if (ageDays <= 30)
+        return 0.8;
+    if (ageDays <= 90)
+        return 0.6;
+    if (ageDays <= 180)
+        return 0.4;
+    if (ageDays <= 365)
+        return 0.2;
+    return 0;
+}
+function toConfidence(score) {
+    if (score >= 0.75)
+        return "high";
+    if (score >= 0.5)
+        return "medium";
+    return "low";
+}
+export async function searchSnippetDocumentsWithOptions(query, options) {
+    const docs = await loadSnippetDocuments();
+    if (!docs.length)
+        return [];
+    const { normalized: normalizedQuery, expanded: expandedQuery, tokens } = expandQuery(query);
+    const versionHints = extractVersionHints(query, options.version);
+    const filteredDocs = docs.filter((doc) => {
+        if (options.category) {
+            if (normalize(doc.category ?? "") !== normalize(options.category))
+                return false;
+        }
+        if (options.framework) {
+            if (!normalize(doc.framework ?? "").includes(normalize(options.framework))) {
+                return false;
+            }
+        }
+        if (options.version) {
+            if (!matchesVersion(doc.version, options.version))
+                return false;
+        }
+        if (options.difficulty) {
+            if (doc.difficulty !== options.difficulty)
+                return false;
+        }
+        return true;
+    });
+    if (!filteredDocs.length)
+        return [];
+    const fuse = new Fuse(filteredDocs, {
+        includeScore: true,
+        threshold: 0.4,
+        keys: ["title", "summary", "tags", "framework", "category", "body"],
+    });
+    const results = fuse.search(expandedQuery || query, {
+        limit: Math.max(options.limit ?? 10, 50),
+    });
+    const scored = results.map((r) => {
+        const doc = r.item;
+        const fuseScore = r.score ?? 1;
+        const baseRelevance = 1 - Math.min(Math.max(fuseScore, 0), 1);
+        const reasons = [];
+        const titleNormalized = normalizeText(doc.title);
+        const exactTitleMatch = titleNormalized === normalizedQuery || titleNormalized.includes(normalizedQuery);
+        if (exactTitleMatch)
+            reasons.push("title_match");
+        const tagMatches = doc.tags.filter((tag) => tokens.some((token) => normalize(tag).includes(token))).length;
+        if (tagMatches > 0)
+            reasons.push(`tag_matches:${tagMatches}`);
+        const frameworkMatch = options.framework
+            ? normalize(doc.framework ?? "").includes(normalize(options.framework))
+            : false;
+        if (frameworkMatch)
+            reasons.push("framework_match");
+        const versionMatch = versionHints.some((hint) => matchesVersion(doc.version, hint));
+        if (versionMatch)
+            reasons.push("version_precedence");
+        const freshnessScore = computeFreshnessScore(doc.updatedAt);
+        if (freshnessScore >= 0.6)
+            reasons.push("fresh_content");
+        const rankScore = baseRelevance * 0.55 +
+            (exactTitleMatch ? 1 : 0) * 0.15 +
+            Math.min(tagMatches, 3) / 3 * 0.1 +
+            (frameworkMatch ? 1 : 0) * 0.08 +
+            (versionMatch ? 1 : 0) * 0.07 +
+            freshnessScore * 0.05;
+        return {
+            ...doc,
+            score: fuseScore,
+            rankScore,
+            confidence: toConfidence(rankScore),
+            reasons,
+        };
+    });
+    scored.sort((a, b) => {
+        if (b.rankScore !== a.rankScore)
+            return b.rankScore - a.rankScore;
+        const titleCmp = a.title.localeCompare(b.title);
+        if (titleCmp !== 0)
+            return titleCmp;
+        return a.id.localeCompare(b.id);
+    });
+    return scored.slice(0, options.limit ?? 10);
+}
+export async function loadNamedMarkdownDocument(folder, id) {
+    const root = resolveSafePath(folder);
+    const idPattern = /^[A-Za-z0-9-]+$/;
+    if (!idPattern.test(id)) {
+        throw new Error("Identifier can only contain letters, numbers, and hyphens");
+    }
+    const filePath = path.join(root, `${id}.md`);
+    try {
+        const raw = await readMarkdownFile(filePath);
+        const parsed = matter(raw);
+        const fm = markdownDocFrontmatterSchema.parse(parsed.data);
+        return {
+            id: fm.id ?? id,
+            title: fm.title,
+            summary: fm.summary,
+            framework: fm.framework,
+            version: fm.version,
+            tags: fm.tags ?? [],
+            body: parsed.content.trim(),
+            path: `${folder}/${id}.md`,
+        };
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+export async function listMarkdownDocNames(folder) {
+    const root = resolveSafePath(folder);
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith(".md"))
+            .map((e) => e.name.replace(/\.md$/i, ""))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}

package/dist/tools/knowledge/explainConcept.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { textResponse } from "../../shared/response.js";
+import { listMarkdownDocNames, loadNamedMarkdownDocument, searchSnippetDocumentsWithOptions, } from "../../storage/markdownKnowledgeStore.js";
+export const explainConceptTool = {
+    name: "explain_concept",
+    description: "Explain engineering concepts with practical guidance",
+    inputSchema: z.object({
+        concept: z
+            .string()
+            .regex(/^[A-Za-z0-9-]+$/)
+            .describe("Concept id, e.g. circuit-breaker"),
+    }),
+    async execute(input) {
+        const doc = await loadNamedMarkdownDocument("content/concepts", input.concept);
+        if (!doc) {
+            const available = await listMarkdownDocNames("content/concepts");
+            return textResponse(`Concept '${input.concept}' was not found. Available concepts: ${available.join(", ") || "none"}`);
+        }
+        const lines = [
+            `# ${doc.title}`,
+            "",
+            doc.summary ?? "",
+            "",
+            "## Metadata",
+            `- Framework: ${doc.framework ?? "n/a"}`,
+            `- Version: ${doc.version ?? "n/a"}`,
+            `- Tags: ${doc.tags.length ? doc.tags.join(", ") : "n/a"}`,
+            "",
+            `Path: ${doc.path}`,
+            "",
+            doc.body,
+        ];
+        const related = await searchSnippetDocumentsWithOptions(`${doc.title} ${doc.tags.join(" ")}`, {
+            framework: doc.framework,
+            version: doc.version,
+            limit: 3,
+        });
+        if (related.length) {
+            lines.push("", "## Related Snippets");
+            related.forEach((item) => {
+                lines.push(`- ${item.id}: ${item.title} (${item.confidence}, score=${item.rankScore.toFixed(2)})`);
+            });
+        }
+        return textResponse(lines.join("\n"));
+    },
+};

package/dist/tools/knowledge/generateSetup.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { textResponse } from "../../shared/response.js";
+import { listMarkdownDocNames, loadNamedMarkdownDocument, } from "../../storage/markdownKnowledgeStore.js";
+function normalize(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export const generateSetupTool = {
+    name: "generate_setup",
+    description: "Generate production-ready setup guidance for a technology type",
+    inputSchema: z.object({
+        type: z.string().min(2).describe("Setup type, e.g. jwt"),
+        framework: z.string().optional().describe("Framework hint, e.g. dotnet9"),
+    }),
+    async execute(input) {
+        const normalizedType = normalize(input.type);
+        const normalizedFramework = input.framework
+            ? normalize(input.framework)
+            : undefined;
+        const candidateNames = [
+            normalizedFramework
+                ? `${normalizedType}-${normalizedFramework}`
+                : undefined,
+            normalizedType,
+        ].filter((n) => Boolean(n));
+        for (const candidate of candidateNames) {
+            const doc = await loadNamedMarkdownDocument("content/setups", candidate);
+            if (doc) {
+                const lines = [
+                    `# ${doc.title}`,
+                    "",
+                    doc.summary ?? "",
+                    "",
+                    `Path: ${doc.path}`,
+                    "",
+                    doc.body,
+                ];
+                return textResponse(lines.join("\n"));
+            }
+        }
+        const available = await listMarkdownDocNames("content/setups");
+        return textResponse(`No setup found for type='${input.type}'${input.framework ? ` framework='${input.framework}'` : ""}. Available setups: ${available.join(", ") || "none"}`);
+    },
+};

package/dist/tools/knowledge/getSnippet.js

@@ -1,20 +1,19 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { glob } from "glob";
 import { resolveSafePath } from "../fs/safePath.js";
-const snippetFileSchema = z.object({
-    name: z.string(),
-    title: z.string(),
-    language: z.string(),
-    description: z.string(),
-    code: z.string(),
-});
-async function listAvailableSnippetNames(snippetsDir) {
+import { textResponse } from "../../shared/response.js";
+import { findSnippetByName } from "../../storage/markdownKnowledgeStore.js";
+async function listAvailableMarkdownSnippetNames() {
+    const snippetsDir = resolveSafePath("snippets");
     try {
-        const entries = await fs.readdir(snippetsDir, { withFileTypes: true });
-        return entries
-            .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
-            .map((entry) => entry.name.replace(/\.json$/i, ""))
+        const files = await glob("**/*.md", {
+            cwd: snippetsDir,
+            nodir: true,
+            ignore: ["**/node_modules/**", "**/.git/**"],
+        });
+        return files
+            .map((file) => path.basename(file).replace(/\.md$/i, ""))
             .sort();
     }
     catch {
@@ -31,34 +30,48 @@ export const getSnippetTool = {
             .describe("Snippet name, e.g. 'polly-retry', 'jwt-setup'"),
     }),
     async execute(input) {
-        const snippetsDir = resolveSafePath("snippets");
-        const filePath = path.join(snippetsDir, `${input.name}.json`);
-        try {
-            const raw = await fs.readFile(filePath, "utf-8");
-            const snippet = snippetFileSchema.parse(JSON.parse(raw));
-            const text = [
-                `# ${snippet.title}`,
+        const markdownSnippet = await findSnippetByName(input.name);
+        if (markdownSnippet) {
+            const lines = [
+                `# ${markdownSnippet.title}`,
                 "",
-                snippet.description,
+                markdownSnippet.summary,
                 "",
-                `Language: ${snippet.language}`,
-                "",
-                `\`\`\`${snippet.language}`,
-                snippet.code,
-                "\`\`\`",
-            ].join("\n");
-            return { content: [{ type: "text", text }] };
-        }
-        catch (err) {
-            const available = await listAvailableSnippetNames(snippetsDir);
-            const availableText = available.length
-                ? available.join(", ")
-                : "No snippets found. Add JSON files under snippets/.";
-            const notFound = err?.code === "ENOENT";
-            const text = notFound
-                ? `Snippet '${input.name}' was not found. Available snippets: ${availableText}`
-                : `Could not load snippet '${input.name}': ${err.message}. Available snippets: ${availableText}`;
-            return { content: [{ type: "text", text }] };
+            ];
+            const meta = [];
+            if (markdownSnippet.language)
+                meta.push(`Language: ${markdownSnippet.language}`);
+            if (markdownSnippet.framework)
+                meta.push(`Framework: ${markdownSnippet.framework}`);
+            if (markdownSnippet.version)
+                meta.push(`Version: ${markdownSnippet.version}`);
+            if (markdownSnippet.difficulty)
+                meta.push(`Difficulty: ${markdownSnippet.difficulty}`);
+            if (markdownSnippet.category)
+                meta.push(`Category: ${markdownSnippet.category}`);
+            if (markdownSnippet.tags.length)
+                meta.push(`Tags: ${markdownSnippet.tags.join(", ")}`);
+            if (meta.length)
+                lines.push(meta.join(" | "), "");
+            lines.push(markdownSnippet.body);
+            if (markdownSnippet.bestPractices.length) {
+                lines.push("", "## Best Practices");
+                markdownSnippet.bestPractices.forEach((bp) => lines.push(`- ${bp}`));
+            }
+            if (markdownSnippet.pitfalls.length) {
+                lines.push("", "## Pitfalls");
+                markdownSnippet.pitfalls.forEach((p) => lines.push(`- ${p}`));
+            }
+            if (markdownSnippet.securityNotes.length) {
+                lines.push("", "## Security Notes");
+                markdownSnippet.securityNotes.forEach((s) => lines.push(`- ${s}`));
+            }
+            return textResponse(lines.join("\n"));
         }
+        const markdownAvailable = await listAvailableMarkdownSnippetNames();
+        const availableText = markdownAvailable.length
+            ? markdownAvailable.join(", ")
+            : "No snippets found. Add markdown files under snippets/.";
+        return textResponse(`Snippet '${input.name}' was not found. Available snippets: ${availableText}`);
     },
 };

package/dist/tools/knowledge/getTemplate.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { textResponse } from "../../shared/response.js";
+import { listMarkdownDocNames, loadNamedMarkdownDocument, searchSnippetDocumentsWithOptions, } from "../../storage/markdownKnowledgeStore.js";
+export const getTemplateTool = {
+    name: "get_template",
+    description: "Return complete implementation templates",
+    inputSchema: z.object({
+        template: z
+            .string()
+            .regex(/^[A-Za-z0-9-]+$/)
+            .describe("Template id, e.g. clean-architecture"),
+    }),
+    async execute(input) {
+        const doc = await loadNamedMarkdownDocument("content/templates", input.template);
+        if (!doc) {
+            const available = await listMarkdownDocNames("content/templates");
+            return textResponse(`Template '${input.template}' was not found. Available templates: ${available.join(", ") || "none"}`);
+        }
+        const lines = [
+            `# ${doc.title}`,
+            "",
+            doc.summary ?? "",
+            "",
+            "## Metadata",
+            `- Framework: ${doc.framework ?? "n/a"}`,
+            `- Version: ${doc.version ?? "n/a"}`,
+            `- Tags: ${doc.tags.length ? doc.tags.join(", ") : "n/a"}`,
+            "",
+            `Path: ${doc.path}`,
+            "",
+            doc.body,
+        ];
+        const related = await searchSnippetDocumentsWithOptions(`${doc.title} ${doc.tags.join(" ")}`, {
+            framework: doc.framework,
+            version: doc.version,
+            limit: 3,
+        });
+        if (related.length) {
+            lines.push("", "## Related Snippets");
+            related.forEach((item) => {
+                lines.push(`- ${item.id}: ${item.title} (${item.confidence}, score=${item.rankScore.toFixed(2)})`);
+            });
+        }
+        return textResponse(lines.join("\n"));
+    },
+};

package/dist/tools/knowledge/index.js

@@ -1 +1,5 @@
 export * from "./getSnippet.js";
+export * from "./searchSnippet.js";
+export * from "./getTemplate.js";
+export * from "./explainConcept.js";
+export * from "./generateSetup.js";

package/dist/tools/knowledge/searchSnippet.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { textResponse } from "../../shared/response.js";
+import { searchSnippetDocumentsWithOptions } from "../../storage/markdownKnowledgeStore.js";
+export const searchSnippetTool = {
+    name: "search_snippet",
+    description: "Search reusable engineering snippets by query text",
+    inputSchema: z.object({
+        query: z.string().min(2).describe("Snippet search query"),
+        framework: z.string().optional().describe("Optional framework filter"),
+        version: z.string().optional().describe("Optional version filter"),
+        category: z.string().optional().describe("Optional category filter"),
+        difficulty: z
+            .enum(["beginner", "medium", "advanced"])
+            .optional()
+            .describe("Optional difficulty filter"),
+        limit: z.number().int().min(1).max(50).optional().describe("Max results"),
+    }),
+    async execute(input) {
+        const results = await searchSnippetDocumentsWithOptions(input.query, {
+            framework: input.framework,
+            version: input.version,
+            category: input.category,
+            difficulty: input.difficulty,
+            limit: input.limit,
+        });
+        const payload = {
+            query: input.query,
+            filters: {
+                framework: input.framework,
+                version: input.version,
+                category: input.category,
+                difficulty: input.difficulty,
+                limit: input.limit ?? 10,
+            },
+            total: results.length,
+            results: results.map((r) => ({
+                id: r.id,
+                name: r.name,
+                title: r.title,
+                summary: r.summary,
+                updatedAt: r.updatedAt,
+                framework: r.framework,
+                version: r.version,
+                category: r.category,
+                difficulty: r.difficulty,
+                tags: r.tags,
+                fuseScore: r.score,
+                rankScore: Number(r.rankScore.toFixed(4)),
+                confidence: r.confidence,
+                reasons: r.reasons,
+                path: r.path,
+            })),
+        };
+        return textResponse(JSON.stringify(payload, null, 2));
+    },
+};

package/examples/basic-search/README.md

@@ -0,0 +1,13 @@
+# Basic Search Example
+
+This example demonstrates how to call the `search_snippet` MCP tool for practical snippet discovery.
+
+## Scenario
+
+You need JWT setup guidance for ASP.NET 9 and want ranked, confidence-labeled results.
+
+## Run
+
+1. Start an MCP client connected to this server.
+2. Execute `search-snippet.ts`.
+3. Inspect the structured output fields (`rankScore`, `confidence`, `reasons`).

package/examples/claude-desktop/README.md

@@ -0,0 +1,10 @@
+# Claude Desktop Integration
+
+Use this folder to configure DevAssist MCP in Claude Desktop.
+
+## Steps
+
+1. Open Claude Desktop settings for MCP servers.
+2. Merge or copy `claude_desktop_config.json` into your app config.
+3. Restart Claude Desktop.
+4. Verify tools like `search_snippet` and `explain_concept` are available.

package/examples/claude-desktop/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dev-assist-mcp": {
+      "command": "npx",
+      "args": ["@mofaggolhoshen/dev-assist-mcp"]
+    }
+  }
+}

package/examples/cursor/README.md

@@ -0,0 +1,15 @@
+# Cursor Integration
+
+This folder documents a minimal setup approach for Cursor IDE MCP usage.
+
+## Suggested Setup
+
+1. Install Node.js 18+.
+2. Add MCP server command using `npx @mofaggolhoshen/dev-assist-mcp`.
+3. Reload Cursor and verify tool discovery.
+
+## Suggested First Calls
+
+- `search_snippet` with: `jwt authentication asp.net 9`
+- `explain_concept` with: `circuit-breaker`
+- `generate_setup` with: `jwt`

package/examples/explain-mode/expected-response.md

@@ -0,0 +1,16 @@
+# Circuit Breaker
+
+Circuit Breaker prevents repeated calls to a failing dependency by opening the circuit after failure thresholds are crossed.
+
+## Metadata
+- Framework: dotnet
+- Version: .net8
+- Tags: resilience, retry, faults
+
+## Why it matters
+- Reduces cascading failures
+- Improves recovery behavior under downstream outages
+
+## Related Snippets
+- polly-retry: Polly Retry Policy (high, score=0.82)
+- polly-circuit-breaker: Polly Circuit Breaker Policy (high, score=0.80)

package/examples/jwt-setup/expected-response.json

@@ -0,0 +1,16 @@
+{
+  "total": 1,
+  "results": [
+    {
+      "id": "jwt-setup-dotnet9",
+      "title": "JWT Setup (.NET 9)",
+      "category": "auth",
+      "framework": "aspnet",
+      "version": ".net9",
+      "difficulty": "medium",
+      "confidence": "high",
+      "rankScore": 0.87,
+      "reasons": ["tag_matches:2", "version_precedence", "fresh_content"]
+    }
+  ]
+}