manage_sitemap

Generate, validate, and manage sitemap.xml files for documentation sites to improve SEO, enable search engine submission, and track deployment changes.

Instructions

Generate, validate, and manage sitemap.xml as the source of truth for documentation links. Sitemap.xml is used for SEO, search engine submission, and deployment tracking.

Input Schema

TableJSON Schema

Name	Required	Description
`action`	Yes	Action to perform: generate (create new), validate (check structure), update (sync with docs), list (show all URLs)
`docsPath`	Yes	Path to documentation root directory
`baseUrl`	No	Base URL for the site (e.g., https://user.github.io/repo). Required for generate/update actions.
`includePatterns`	No	File patterns to include (default: */.md, */.html, */.mdx)
`excludePatterns`	No	File patterns to exclude (default: node_modules, .git, dist, build, .documcp)
`updateFrequency`	No	Default change frequency for pages
`useGitHistory`	No	Use git history for last modified dates (default: true)
`sitemapPath`	No	Custom path for sitemap.xml (default: docsPath/sitemap.xml)

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(),
    },
  });
}

documcp

manage_sitemap

Instructions

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API