FedRAMP Docs MCP Server

Instructions

Implementation Reference

• src/tools/get_requirement_by_id.ts:38-94 (handler)

  The main execute function implementing the tool logic: normalizes ID to uppercase, checks KSI items if prefix matches, otherwise recursively searches all FRMR documents for matching ID, returns structured result or throws NOT_FOUND error.

  execute: async (input) => {
    const searchId = input.id.toUpperCase();
  
    // First check KSI items (most common)
    if (searchId.startsWith("KSI-")) {
      const ksiItems = getKsiItems();
      const ksiItem = ksiItems.find(
        (item) => item.id.toUpperCase() === searchId,
      );
      if (ksiItem) {
        return {
          id: ksiItem.id,
          source: "KSI",
          documentPath: ksiItem.docPath,
          documentTitle: "Key Security Indicators",
          title: ksiItem.title,
          statement: ksiItem.statement,
          description: ksiItem.description,
          theme: ksiItem.category,
          impact: ksiItem.impact,
          controlMapping: ksiItem.controlMapping,
          evidenceExamples: ksiItem.evidenceExamples,
        };
      }
    }
  
    // Search in all FRMR documents
    const docs = getFrmrDocuments();
    for (const doc of docs) {
      if (!doc.raw || typeof doc.raw !== "object") continue;
  
      // Recursive search for item with matching ID
      const found = findItemById(doc.raw, searchId);
      if (found) {
        return {
          id: searchId,
          source: doc.type,
          documentPath: doc.path,
          documentTitle: doc.title,
          title: (found as Record<string, unknown>).name as string | undefined,
          statement: (found as Record<string, unknown>).statement as
            | string
            | undefined,
          description: (found as Record<string, unknown>).description as
            | string
            | undefined,
          raw: found,
        };
      }
    }
  
    throw createError({
      code: "NOT_FOUND",
      message: `Requirement not found for ID: ${input.id}`,
      hint: "Try using list_frmr_documents to see available documents, or list_ksi to browse KSI items.",
    });
  },

• src/tools/get_requirement_by_id.ts:22-28 (schema)

  Zod input schema defining the 'id' parameter as a string with description of expected formats (KSI-*, FRR-*, FRD-*).

  const schema = z.object({
    id: z
      .string()
      .describe(
        "Requirement ID (e.g., KSI-IAM-01, FRR-MAS-01, FRR-VDR-01)",
      ),
  });

• src/tools/register.ts:24-53 (registration)

  The registerTools function that registers getRequirementByIdTool (imported at line 10) by including it in the tools array passed to registerToolDefs.

  export function registerTools(server: McpServer): void {
    registerToolDefs(server, [
      // Document discovery
      listFrmrDocumentsTool,
      getFrmrDocumentTool,
      listVersionsTool,
      // KSI tools
      listKsiTool,
      getKsiTool,
      filterByImpactTool,
      getThemeSummaryTool,
      getEvidenceExamplesTool,
      // Control mapping tools
      listControlsTool,
      getControlRequirementsTool,
      analyzeControlCoverageTool,
      // Search & lookup tools
      searchMarkdownTool,
      readMarkdownTool,
      searchDefinitionsTool,
      getRequirementByIdTool,
      // Analysis tools
      diffFrmrTool,
      grepControlsTool,
      significantChangeTool,
      // System tools
      healthCheckTool,
      updateRepositoryTool,
    ]);
  }

• src/tools/get_requirement_by_id.ts:97-124 (helper)

  Recursive helper function to search for an item with matching ID in nested objects or arrays, used in FRMR document search.

  function findItemById(obj: unknown, targetId: string): unknown | null {
    if (!obj || typeof obj !== "object") return null;
  
    if (Array.isArray(obj)) {
      for (const item of obj) {
        if (
          item &&
          typeof item === "object" &&
          "id" in item &&
          String((item as Record<string, unknown>).id).toUpperCase() === targetId
        ) {
          return item;
        }
        const found = findItemById(item, targetId);
        if (found) return found;
      }
    } else {
      const record = obj as Record<string, unknown>;
      if ("id" in record && String(record.id).toUpperCase() === targetId) {
        return record;
      }
      for (const value of Object.values(record)) {
        const found = findItemById(value, targetId);
        if (found) return found;
      }
    }
    return null;
  }