FedRAMP Docs MCP Server

Instructions

Implementation Reference

• src/search.ts:36-74 (handler)

  Core implementation of the search logic for markdown documents using Lunr index. Handles query validation, searching, snippet extraction, pagination, and returns structured results with path, line, snippet, and score.

  export function searchMarkdown(
    query: string,
    limit: number,
    offset: number,
  ): MarkdownSearchResult {
    if (!query.trim()) {
      throw createError({
        code: "BAD_REQUEST",
        message: "Query must not be empty.",
      });
    }
  
    const index = getMarkdownIndex();
    let results: lunr.Index.Result[];
    try {
      results = index.search(query);
    } catch {
      results = index.search(query.replace(/[~*:^+-]/g, " "));
    }
  
    const hits: MarkdownSearchHit[] = [];
    for (const result of results) {
      const doc = getMarkdownDoc(result.ref);
      if (!doc) {
        continue;
      }
      const { line, snippet } = findLineAndSnippet(doc, query);
      hits.push({
        path: doc.path,
        line,
        snippet,
        score: result.score,
      });
    }
  
    const total = hits.length;
    const paginated = hits.slice(offset, offset + limit);
    return { total, hits: paginated };
  }

• src/tools/search_markdown.ts:6-10 (schema)

  Zod input schema for the search_markdown tool: required 'query' string, optional 'limit' (1-100, default 20), optional 'offset' (default 0).

  const schema = z.object({
    query: z.string(),
    limit: z.number().int().min(1).max(100).default(20),
    offset: z.number().int().min(0).default(0),
  });

• src/tools/search_markdown.ts:12-22 (handler)

  MCP ToolDefinition for 'search_markdown', including name, description, schema reference, and execute handler that delegates to the core searchMarkdown function.

  export const searchMarkdownTool: ToolDefinition<
    typeof schema,
    ReturnType<typeof searchMarkdown>
  > = {
    name: "search_markdown",
    description: "Full-text search across FedRAMP markdown documentation and guidance. Use this to find information about policies, procedures, requirements, and guidance. Examples: 'continuous monitoring', 'incident response', 'significant change', 'authorization boundary'.",
    schema,
    execute: async (input) => {
      return searchMarkdown(input.query, input.limit ?? 20, input.offset ?? 0);
    },
  };

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

  Registers the searchMarkdownTool (imported at line 21) among other tools by passing it to registerToolDefs(server, [...]). This connects the tool to the MCP server.

  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/search.ts:21-34 (helper)

  Helper function used by searchMarkdown to find the specific line number and snippet containing the query match in a markdown document.

  function findLineAndSnippet(
    doc: MarkdownDoc,
    query: string,
  ): { line: number; snippet: string } {
    const regex = new RegExp(escapeStringRegexp(query), "i");
    for (let index = 0; index < doc.lines.length; index += 1) {
      const line = doc.lines[index];
      if (regex.test(line)) {
        const snippet = line.trim();
        return { line: index + 1, snippet };
      }
    }
    return { line: 1, snippet: doc.lines[0]?.slice(0, 200) ?? "" };
  }