Turbo Docs MCP Server

Instructions

Implementation Reference

• src/index.ts:17-45 (registration)

  Dynamically registers an MCP tool named 'reference-frames' (among others from docFiles config) with a parameterless handler that fetches the content of 'reference/frames.md' and returns it as text content block, with error handling.
  docFiles.forEach(({ folder, file, name, description }) => { server.tool( name, description, async () => { try { const content = await readMarkdownFile(path.join(folder, file)); return { content: [ { type: "text", text: content } ] }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error reading ${file}: ${errorMessage}` } ] }; } } ); });
• src/config.ts:82-87 (schema)

  Configuration defining the 'reference-frames' tool: its name, description, and mapping to the documentation file 'reference/frames.md'.
  { folder: 'reference', file: 'frames.md', name: 'reference-frames', description: 'Turbo Frames API reference - detailed frame element attributes, JavaScript methods, lifecycle callbacks, and programmatic frame control' },
• src/documentReader.ts:14-61 (handler)

  Core handler logic for reading the markdown file content, called by the tool handler with filename 'reference/frames.md'. Supports caching, GitHub fetching, and local fallback.
  export async function readMarkdownFile(filename: string): Promise<string> { const filePath = path.join(docsFolder, filename); if (!filePath.startsWith(docsFolder)) { throw new Error("Invalid file path"); } // Get current commit info if we don't have it yet if (!mainBranchInfo) { try { const commitInfo = await fetchMainBranchInformation(); const cacheKey = `${commitInfo.sha.substring(0, 7)}-${commitInfo.timestamp}`; mainBranchInfo = { ...commitInfo, cacheKey }; } catch (shaError) { console.error('Failed to get GitHub commit info, falling back to direct fetch'); } } // Try to read from cache first if we have commit info if (mainBranchInfo) { const cachedFilePath = path.join(cacheFolder, mainBranchInfo.cacheKey, filename); try { const content = await fs.promises.readFile(cachedFilePath, "utf-8"); console.error(`Using cached content for ${mainBranchInfo.cacheKey}: ${filename}`); return content; } catch (cacheError) { // Cache miss, continue to fetch from GitHub } } // Fetch from GitHub try { return await fetchFromGitHub(filename, mainBranchInfo?.cacheKey); } catch (githubError) { console.error(`GitHub fetch failed: ${githubError}, attempting to read from local files...`); // Fallback: read from local files try { return await fs.promises.readFile(filePath, "utf-8"); } catch (localError) { const githubErrorMessage = githubError instanceof Error ? githubError.message : String(githubError); const localErrorMessage = localError instanceof Error ? localError.message : String(localError); throw new Error(`Failed to read file from GitHub (${githubErrorMessage}) and locally (${localErrorMessage})`); } } }
• src/utils.ts:50-76 (helper)

  Helper function to fetch markdown content from GitHub raw URL and handle caching, used by readMarkdownFile.
  export async function fetchFromGitHub(filename: string, cacheKey?: string): Promise<string> { const githubUrl = `${GITHUB_RAW_BASE_URL}/${filename}`; console.error(`Fetching ${filename} from GitHub: ${githubUrl}`); const response = await fetch(githubUrl); if (!response.ok) { throw new Error(`GitHub fetch failed: ${response.status} ${response.statusText}`); } const content = await response.text(); // Cache the content with cache key if available if (cacheKey) { try { const cacheFolder = path.resolve(__dirname, "../cache"); const cachedFilePath = path.join(cacheFolder, cacheKey, filename); await fs.promises.mkdir(path.dirname(cachedFilePath), { recursive: true }); await fs.promises.writeFile(cachedFilePath, content, "utf-8"); console.error(`Cached GitHub content for ${cacheKey}: ${filename}`); } catch (cacheError) { console.error(`Failed to cache content: ${cacheError}`); } } return content; }
• src/utils.ts:23-41 (helper)

  Helper function to fetch current main branch commit SHA and timestamp for cache key generation, used by readMarkdownFile.
  export async function fetchMainBranchInformation(): Promise<{sha: string, timestamp: number}> { try { const response = await fetch(`${GITHUB_API_BASE_URL}/commits/${MAIN_BRANCH}`); if (!response.ok) { throw new Error(`GitHub API failed: ${response.status} ${response.statusText}`); } const data = await response.json(); // Get the commit timestamp (author date) const commitTimestamp = new Date(data.commit.author.date).getTime(); return { sha: data.sha, timestamp: commitTimestamp }; } catch (error) { console.error('Failed to get GitHub SHA:', error); throw error; }