fixing documentation links (file ids versus reflection ids)

Author: yGuy

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-typescribe",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "An MCP server that answers questions about TypeScript APIs using TypeDoc JSON documentation",
   "main": "dist/mcp-server/index.js",
   "type": "module",
@@ -72,7 +72,7 @@
     "kuzu": "^0.10.0",
     "langchain": "0.3.26",
     "object-hash": "^3.0.0",
-    "typedoc": "^0.28.4",
+    "typedoc": "0.28.5",
     "yaml": "^2.8.0",
     "zod": "^3.24.4",
     "zod-to-json-schema": "^3.24.5"

package.json

@@ -990,7 +990,7 @@ export class TypeScriptApiHandlers {
     offset: number = 0,
     section?: string,
   ): Promise<string> {
-    const result = this.project.getReflectionById(id);
+    const result = this.project.files.resolve(id, this.project);
     if (result instanceof ProjectReflection && result.readme) {
       return await extractDocument(
         offset,

src/mcp-server/core/typescript-api-handlers.ts

@@ -19,6 +19,7 @@ import {
   DeclarationReflection,
   DocumentReflection,
   ParameterReflection,
+  ProjectReflection,
   ReferenceReflection,
   Reflection,
   ReflectionKind,
@@ -381,6 +382,20 @@ export function extractSection(content: string, section: string) {
   return { filteredContent, breadcrumbs };
 }
 
+function convertReflectionToDocumentId(
+  walker: ProjectReflection | undefined,
+  child: DocumentReflection,
+) {
+  let id = 1;
+  let resolved = walker?.project.files.resolve(id, walker?.project);
+  while (typeof resolved !== "undefined" && resolved !== child) {
+    id++;
+    resolved = walker?.project.files.resolve(id, walker?.project);
+  }
+  if (resolved === child) return id;
+  return undefined;
+}
+
 export async function extractDocument(
   offset: number,
   id: number,
@@ -395,13 +410,18 @@ export async function extractDocument(
 
   //breadcrumbs
   let walker = parent;
+  const breadCrumbs: string[] = [];
   while (walker instanceof DocumentReflection) {
-    finalResult += `[${walker.name}](${createDocLink(walker.id)}) > `;
+    const id = convertReflectionToDocumentId(walker.project, walker);
+    if (id) {
+      breadCrumbs.push(`[${walker.name}](${createDocLink(id)}) `);
+    } else {
+      breadCrumbs.push(walker.name);
+    }
     walker = walker.parent;
   }
-
-  if (finalResult.length > 0) {
-    finalResult += "\n\n";
+  if (breadCrumbs.length > 0) {
+    finalResult += "Breadcrumbs: >> " + breadCrumbs.join(" >> ") + "\n\n";
   }
 
   if (offset == 0) {
@@ -423,10 +443,20 @@ export async function extractDocument(
           finalResult += `**Tags:** ${frontmatter.tags.join(", ")}\n\n`;
         }
       }
+      /*
+      We cannot link to child ids because we need a file id and we only get a reflection id.
+       */
       if (Array.isArray(children) && children.length > 0) {
         finalResult += "## Child Pages\n\n";
         finalResult += children
-          .map((child) => `- [${child.name}](${createDocLink(child.id)})`)
+          .map((child) => {
+            const id = convertReflectionToDocumentId(walker?.project, child);
+            if (id) {
+              return `- [${child.name}](${createDocLink(id)})`;
+            } else {
+              return `- ${child.name}`;
+            }
+          })
           .join("\n");
       }
     }

src/mcp-server/utils/format-utils.ts

@@ -148,27 +148,36 @@ Some text 7
   describe("getDocumentation", () => {
     it("should return the documentation page", async () => {
       const result = await handlers.handleGetDocumentation(
-        19,
+        1,
         0,
         "introduction",
       );
       expect(result).toBeDefined();
       expect(result).toContain("## Introduction");
-      expect(result).toContain("Complete File [here](api://doc/19)");
+      expect(result).toContain("Complete File [here](api://doc/1)");
       expect(result).toContain("Breadcrumbs: >> [Welcome to Our Project]");
       expect(result).not.toContain("# Welcome to Our Project");
       expect(result).not.toContain("Getting Started");
       expect(result).not.toContain("Thank you");
     });
     it("should return a documentation page section", async () => {
-      const result = await handlers.handleGetDocumentation(19);
+      const result = await handlers.handleGetDocumentation(1);
       expect(result).toBeDefined();
       expect(result).toContain("# External Markdown");
     });
-    it("should return the README page", async () => {
-      const result = await handlers.handleGetDocumentation(0);
+    it("should properly link between api docs", async () => {
+      const result = await handlers.handleGetDocumentation(1);
       expect(result).toBeDefined();
-      expect(result).toContain("README");
+      expect(result).toContain("api://doc/");
+      expect(result).toMatch(/api:\/\/doc\/(\d+)/);
+      const id = Number.parseInt(
+        result.match(/\[links]\(api:\/\/doc\/(\d+)/)![1],
+      );
+      const linkedDocument = await handlers.handleGetDocumentation(id);
+      expect(linkedDocument).toBeDefined();
+
+      expect(linkedDocument).toContain("External");
+      expect(linkedDocument).toContain("[External Markdown](api://doc/1)");
     });
     it("should include api-doc links in descriptions", async () => {
       const result = handlers.handleGetSymbolDetails({ name: "Kerle" });