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