handbook-streams
Enable real-time UI updates using 9 stream actions like append, replace, and remove. Integrate WebSocket/SSE and reuse server-side templates for dynamic content rendering.
Instructions
Turbo Streams for live updates - learn about the 9 stream actions (append, prepend, replace, update, remove, before, after, morph, refresh), WebSocket/SSE integration, and server-side template reuse
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/index.ts:21-43 (handler)Handler function executed when the 'handbook-streams' tool is called. It fetches the content of the associated markdown file using readMarkdownFile and returns it formatted as an MCP text content block, with error handling.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:38-43 (schema)Configuration schema entry for the 'handbook-streams' tool, specifying the source folder/file and description used in registration.{ folder: 'handbook', file: '05_streams.md', name: 'handbook-streams', description: 'Turbo Streams for live updates - learn about the 9 stream actions (append, prepend, replace, update, remove, before, after, morph, refresh), WebSocket/SSE integration, and server-side template reuse' },
- src/index.ts:17-45 (registration)Dynamic registration code that creates and registers the 'handbook-streams' tool (and others) by iterating over docFiles config and calling server.tool with name, description, and shared handler.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/documentReader.ts:14-61 (helper)Helper function that implements the core logic for reading/streaming the markdown file content from cache, GitHub raw, or local fallback, called by the tool handler.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})`); } } }