handbook-building
Build a practical clipboard controller example to demonstrate Stimulus patterns, CSS classes, and JavaScript-HTML connections for real-world applications.
Instructions
Build a real-world clipboard controller example - demonstrates practical Stimulus patterns, CSS classes, and connecting JavaScript to HTML elements
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/index.ts:21-43 (handler)The core handler function for the 'handbook-building' tool (shared with other doc tools). It reads the specific markdown file using readMarkdownFile(path.join(folder, file)) where folder/file come from config, and returns the content as MCP text response or error message.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:33-38 (schema)Schema/configuration entry in docFiles array that defines the parameters for the 'handbook-building' tool: folder, file path, name, and description used in registration.{ folder: 'handbook', file: '03_building_something_real.md', name: 'handbook-building', description: 'Build a real-world clipboard controller example - demonstrates practical Stimulus patterns, CSS classes, and connecting JavaScript to HTML elements' },
- src/index.ts:17-45 (registration)Registration code that dynamically registers the 'handbook-building' tool by looping over docFiles config and calling server.tool(name, description, handlerFn) for each documentation tool.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)Supporting helper function readMarkdownFile that implements the file fetching logic (cache first, then GitHub raw, then local fs) called by the tool handler to get the markdown content.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})`); } } }