documcp

Instructions

Implementation Reference

• src/tools/manage-sitemap.ts:69-139 (handler)

  The main handler function for the 'manage_sitemap' tool. It parses input, validates directories, and dispatches to action-specific handlers (generate, validate, update, list) based on the 'action' parameter.
  export async function manageSitemap( input: ManageSitemapInput, ): Promise<{ content: any[] }> { const { action, docsPath, sitemapPath } = input; // Resolve sitemap path const resolvedSitemapPath = sitemapPath || path.join(docsPath, "sitemap.xml"); try { // Verify docs directory exists try { await fs.access(docsPath); } catch { return formatMCPResponse({ success: false, error: { code: "DOCS_DIR_NOT_FOUND", message: `Documentation directory not found: ${docsPath}`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } switch (action) { case "generate": return await generateSitemapAction(input, resolvedSitemapPath); case "validate": return await validateSitemapAction(resolvedSitemapPath); case "update": return await updateSitemapAction(input, resolvedSitemapPath); case "list": return await listSitemapAction(resolvedSitemapPath); default: return formatMCPResponse({ success: false, error: { code: "UNKNOWN_ACTION", message: `Unknown action: ${action}`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } } catch (error) { return formatMCPResponse({ success: false, error: { code: "SITEMAP_ERROR", message: `Error managing sitemap: ${ error instanceof Error ? error.message : String(error) }`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } }
• src/tools/manage-sitemap.ts:24-62 (schema)

  Zod schema defining the input parameters for the manage_sitemap tool, including action types and optional configurations.
  export const ManageSitemapInputSchema = z.object({ action: z .enum(["generate", "validate", "update", "list"]) .describe( "Action to perform: generate (create new), validate (check structure), update (sync with docs), list (show all URLs)", ), docsPath: z.string().describe("Path to documentation root directory"), baseUrl: z .string() .optional() .describe( "Base URL for the site (e.g., https://user.github.io/repo). Required for generate/update actions.", ), includePatterns: z .array(z.string()) .optional() .describe( "File patterns to include (default: **/*.md, **/*.html, **/*.mdx)", ), excludePatterns: z .array(z.string()) .optional() .describe( "File patterns to exclude (default: node_modules, .git, dist, build, .documcp)", ), updateFrequency: z .enum(["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]) .optional() .describe("Default change frequency for pages"), useGitHistory: z .boolean() .optional() .default(true) .describe("Use git history for last modified dates (default: true)"), sitemapPath: z .string() .optional() .describe("Custom path for sitemap.xml (default: docsPath/sitemap.xml)"), });
• src/tools/manage-sitemap.ts:144-202 (helper)

  Helper function that handles the 'generate' action: validates baseUrl, generates sitemap XML using generateSitemap utility, writes to file, and formats output.
  async function generateSitemapAction( input: ManageSitemapInput, sitemapPath: string, ): Promise<{ content: any[] }> { const { docsPath, baseUrl, includePatterns, excludePatterns, updateFrequency, } = input; if (!baseUrl) { return formatMCPResponse({ success: false, error: { code: "BASE_URL_REQUIRED", message: "baseUrl is required for generate action", }, metadata: { toolVersion: "1.0.0", executionTime: 0, timestamp: new Date().toISOString(), }, }); } // Generate sitemap const { xml, urls, stats } = await generateSitemap({ baseUrl, docsPath, includePatterns, excludePatterns, useGitHistory: input.useGitHistory, defaultChangeFreq: updateFrequency || "monthly", }); // Write sitemap.xml await fs.writeFile(sitemapPath, xml, "utf-8"); // Format output const output = formatGenerateOutput(sitemapPath, urls, stats); return formatMCPResponse({ success: true, data: { action: "generate", sitemapPath, totalUrls: stats.totalUrls, categories: stats.byCategory, output, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); }
• src/tools/manage-sitemap.ts:66-139 (helper)

  Entry point handler dispatching to action-specific helpers.
  /** * Manage sitemap.xml for documentation */ export async function manageSitemap( input: ManageSitemapInput, ): Promise<{ content: any[] }> { const { action, docsPath, sitemapPath } = input; // Resolve sitemap path const resolvedSitemapPath = sitemapPath || path.join(docsPath, "sitemap.xml"); try { // Verify docs directory exists try { await fs.access(docsPath); } catch { return formatMCPResponse({ success: false, error: { code: "DOCS_DIR_NOT_FOUND", message: `Documentation directory not found: ${docsPath}`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } switch (action) { case "generate": return await generateSitemapAction(input, resolvedSitemapPath); case "validate": return await validateSitemapAction(resolvedSitemapPath); case "update": return await updateSitemapAction(input, resolvedSitemapPath); case "list": return await listSitemapAction(resolvedSitemapPath); default: return formatMCPResponse({ success: false, error: { code: "UNKNOWN_ACTION", message: `Unknown action: ${action}`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } } catch (error) { return formatMCPResponse({ success: false, error: { code: "SITEMAP_ERROR", message: `Error managing sitemap: ${ error instanceof Error ? error.message : String(error) }`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); } }
• src/tools/manage-sitemap.ts:207-256 (helper)

  Helper for 'validate' action: checks sitemap existence, validates using validateSitemap utility, formats output.
  async function validateSitemapAction( sitemapPath: string, ): Promise<{ content: any[] }> { // Check if sitemap exists try { await fs.access(sitemapPath); } catch { return formatMCPResponse({ success: false, error: { code: "SITEMAP_NOT_FOUND", message: `Sitemap not found: ${sitemapPath}. Use action: "generate" to create a new sitemap.`, }, metadata: { toolVersion: "1.0.0", executionTime: 0, timestamp: new Date().toISOString(), }, }); } // Validate sitemap const validation = await validateSitemap(sitemapPath); // Format output const output = formatValidationOutput(sitemapPath, validation); return formatMCPResponse({ success: validation.valid, data: { action: "validate", valid: validation.valid, errorCount: validation.errors.length, warningCount: validation.warnings.length, urlCount: validation.urlCount, output, }, error: validation.valid ? undefined : { code: "VALIDATION_FAILED", message: `Sitemap validation failed with ${validation.errors.length} error(s)`, }, metadata: { toolVersion: "1.0.0", executionTime: Date.now(), timestamp: new Date().toISOString(), }, }); }