@ansvar/us-regulations-mcp 1.0.0

package/src/tools/action-items.ts

@@ -0,0 +1,164 @@
+import type { Database } from 'better-sqlite3';
+import { getSection, SectionData } from './section.js';
+
+export interface ActionItemsInput {
+  regulation: string;
+  sections: string[];
+}
+
+export interface ActionItem {
+  section: string;
+  title: string;
+  required_state: string;
+  priority: 'high' | 'medium' | 'low';
+  evidence_needed: string[];
+}
+
+export interface ActionItemsResult {
+  regulation: string;
+  action_items: ActionItem[];
+  total_items: number;
+}
+
+/**
+ * Extract action items priority from section text.
+ * - High: Contains "shall", "must", "required"
+ * - Medium: Contains "should", "recommended"
+ * - Low: Everything else
+ */
+function extractPriority(text: string): 'high' | 'medium' | 'low' {
+  const lowerText = text.toLowerCase();
+
+  if (
+    lowerText.includes('shall') ||
+    lowerText.includes('must') ||
+    lowerText.includes('required')
+  ) {
+    return 'high';
+  }
+
+  if (lowerText.includes('should') || lowerText.includes('recommended')) {
+    return 'medium';
+  }
+
+  return 'low';
+}
+
+/**
+ * Extract evidence keywords from section text.
+ * Looks for common audit artifacts and documentation types.
+ */
+function extractEvidenceNeeded(text: string): string[] {
+  const lowerText = text.toLowerCase();
+  const evidence: Set<string> = new Set();
+
+  // Common evidence types
+  const evidenceKeywords: Record<string, string> = {
+    'risk assessment': 'risk assessment report',
+    'risk analysis': 'risk assessment report',
+    'audit log': 'audit logs',
+    'access log': 'access logs',
+    'security incident': 'incident response documentation',
+    'breach': 'breach notification records',
+    'policy': 'written policies',
+    'procedure': 'written procedures',
+    'training': 'training records',
+    'documentation': 'supporting documentation',
+    'encryption': 'encryption documentation',
+    'access control': 'access control matrix',
+    'authentication': 'authentication logs',
+    'authorization': 'authorization records',
+    'backup': 'backup records',
+    'disaster recovery': 'disaster recovery plan',
+    'business continuity': 'business continuity plan',
+  };
+
+  for (const [keyword, evidenceType] of Object.entries(evidenceKeywords)) {
+    if (lowerText.includes(keyword)) {
+      evidence.add(evidenceType);
+    }
+  }
+
+  return Array.from(evidence);
+}
+
+/**
+ * Generate compliance action items from regulation sections.
+ * Extracts priority and evidence requirements from section text.
+ */
+export async function getComplianceActionItems(
+  db: Database,
+  input: ActionItemsInput
+): Promise<ActionItemsResult> {
+  const { regulation, sections } = input;
+
+  if (!regulation) {
+    throw new Error('Regulation is required');
+  }
+
+  if (!sections || sections.length === 0) {
+    throw new Error('At least one section must be specified');
+  }
+
+  if (sections.length > 20) {
+    throw new Error('Cannot process more than 20 sections at once');
+  }
+
+  // Fetch section data
+  const actionItems: ActionItem[] = [];
+
+  for (const sectionNumber of sections) {
+    const sectionData = await getSection(db, {
+      regulation,
+      section: sectionNumber,
+    });
+
+    if (!sectionData) {
+      console.warn(`Section ${sectionNumber} not found in ${regulation}, skipping`);
+      continue;
+    }
+
+    // Extract action item components
+    const priority = extractPriority(sectionData.text);
+    const evidenceNeeded = extractEvidenceNeeded(sectionData.text);
+
+    // Generate required state description
+    const requiredState = generateRequiredState(sectionData);
+
+    actionItems.push({
+      section: `§${sectionData.section_number}`,
+      title: sectionData.title || `Section ${sectionData.section_number}`,
+      required_state: requiredState,
+      priority,
+      evidence_needed: evidenceNeeded.length > 0 ? evidenceNeeded : ['supporting documentation'],
+    });
+  }
+
+  return {
+    regulation,
+    action_items: actionItems,
+    total_items: actionItems.length,
+  };
+}
+
+/**
+ * Generate a concise required state description from section data.
+ * Extracts first sentence or up to 200 characters from section text.
+ */
+function generateRequiredState(section: SectionData): string {
+  const text = section.text.trim();
+
+  // Try to extract first sentence
+  const firstSentence = text.match(/^[^.!?]+[.!?]/);
+  if (firstSentence) {
+    let sentence = firstSentence[0].trim();
+    if (sentence.length > 200) {
+      sentence = sentence.substring(0, 197) + '...';
+    }
+    return `Comply with requirements of §${section.section_number}: ${sentence}`;
+  }
+
+  // Fallback: first 200 characters
+  const truncated = text.length > 200 ? text.substring(0, 197) + '...' : text;
+  return `Comply with requirements of §${section.section_number}: ${truncated}`;
+}

package/src/tools/applicability.ts

@@ -0,0 +1,91 @@
+import type { Database } from 'better-sqlite3';
+
+export interface ApplicabilityInput {
+  sector: string;
+  subsector?: string;
+}
+
+export interface ApplicabilityRule {
+  regulation: string;
+  sector: string;
+  subsector: string | null;
+  applies: boolean;
+  confidence: 'definite' | 'likely' | 'possible';
+  basis_section: string | null;
+  notes: string | null;
+}
+
+export interface ApplicabilityResult {
+  sector: string;
+  subsector: string | null;
+  applicable_regulations: ApplicabilityRule[];
+  total_applicable: number;
+}
+
+/**
+ * Check which regulations apply to a specific sector/subsector.
+ * Returns regulations that apply with confidence levels.
+ */
+export async function checkApplicability(
+  db: Database,
+  input: ApplicabilityInput
+): Promise<ApplicabilityResult> {
+  const { sector, subsector } = input;
+
+  if (!sector || sector.trim().length === 0) {
+    throw new Error('Sector is required (e.g., "healthcare", "financial", "retail")');
+  }
+
+  // Query applicability rules
+  let sql = `
+    SELECT
+      regulation,
+      sector,
+      subsector,
+      applies,
+      confidence,
+      basis_section,
+      notes
+    FROM applicability_rules
+    WHERE sector = ?
+  `;
+
+  const params: string[] = [sector];
+
+  if (subsector) {
+    sql += ' AND (subsector = ? OR subsector IS NULL)';
+    params.push(subsector);
+  }
+
+  sql += ' ORDER BY applies DESC, confidence ASC';
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    regulation: string;
+    sector: string;
+    subsector: string | null;
+    applies: number; // Database stores as INTEGER (0 or 1)
+    confidence: 'definite' | 'likely' | 'possible';
+    basis_section: string | null;
+    notes: string | null;
+  }>;
+
+  // Filter to only regulations that apply
+  const applicableRules = rows
+    .filter((row) => row.applies === 1)
+    .map((row) => ({
+      regulation: row.regulation,
+      sector: row.sector,
+      subsector: row.subsector,
+      applies: row.applies === 1,
+      confidence: row.confidence,
+      basis_section: row.basis_section,
+      notes: row.notes,
+    }));
+
+  return {
+    sector,
+    subsector: subsector || null,
+    applicable_regulations: applicableRules,
+    total_applicable: applicableRules.length,
+  };
+}

package/src/tools/compare.ts

@@ -0,0 +1,61 @@
+import type { Database } from 'better-sqlite3';
+import { searchRegulations, SearchResult } from './search.js';
+
+export interface CompareInput {
+  topic: string;
+  regulations: string[];
+}
+
+export interface CompareResult {
+  topic: string;
+  comparisons: Array<{
+    regulation: string;
+    matches: SearchResult[];
+    total_matches: number;
+  }>;
+}
+
+/**
+ * Compare requirements across multiple regulations for a specific topic.
+ * Uses search_regulations internally to find relevant sections in each regulation.
+ */
+export async function compareRequirements(
+  db: Database,
+  input: CompareInput
+): Promise<CompareResult> {
+  const { topic, regulations } = input;
+
+  if (!topic || topic.trim().length === 0) {
+    throw new Error('Topic is required');
+  }
+
+  if (!regulations || regulations.length === 0) {
+    throw new Error('At least one regulation must be specified');
+  }
+
+  if (regulations.length > 10) {
+    throw new Error('Cannot compare more than 10 regulations at once');
+  }
+
+  // Search each regulation independently
+  const comparisons = await Promise.all(
+    regulations.map(async (regulation) => {
+      const results = await searchRegulations(db, {
+        query: topic,
+        regulations: [regulation],
+        limit: 5, // Top 5 matches per regulation
+      });
+
+      return {
+        regulation,
+        matches: results,
+        total_matches: results.length,
+      };
+    })
+  );
+
+  return {
+    topic,
+    comparisons,
+  };
+}

package/src/tools/definitions.ts

@@ -0,0 +1,79 @@
+import type { Database } from 'better-sqlite3';
+
+export interface DefinitionsInput {
+  term: string;
+  regulation?: string;
+}
+
+export interface Definition {
+  regulation: string;
+  term: string;
+  definition: string;
+  section: string;
+}
+
+export interface DefinitionsResult {
+  term: string;
+  definitions: Definition[];
+  total_definitions: number;
+}
+
+function escapeSqlLike(str: string): string {
+  return str.replace(/[%_]/g, '\\$&');
+}
+
+/**
+ * Look up official term definitions across regulations.
+ * Uses LIKE search to match partial terms (e.g., "health" matches "protected health information").
+ */
+export async function getDefinitions(
+  db: Database,
+  input: DefinitionsInput
+): Promise<DefinitionsResult> {
+  const { term, regulation } = input;
+
+  if (!term || term.trim().length === 0) {
+    throw new Error('Term is required');
+  }
+
+  // Build query with optional regulation filter
+  let sql = `
+    SELECT
+      regulation,
+      term,
+      definition,
+      section
+    FROM definitions
+    WHERE term LIKE ?
+  `;
+
+  // Use LIKE for partial matching (case-insensitive)
+  const params: string[] = [`%${escapeSqlLike(term)}%`];
+
+  if (regulation) {
+    sql += ' AND regulation = ?';
+    params.push(regulation);
+  }
+
+  sql += ' ORDER BY regulation, term';
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    regulation: string;
+    term: string;
+    definition: string;
+    section: string;
+  }>;
+
+  const definitions = rows.map((row) => ({
+    regulation: row.regulation,
+    term: row.term,
+    definition: row.definition,
+    section: row.section,
+  }));
+
+  return {
+    term,
+    definitions,
+    total_definitions: definitions.length,
+  };
+}

package/src/tools/evidence.ts

@@ -0,0 +1,53 @@
+import type { Database } from 'better-sqlite3';
+
+export interface EvidenceInput {
+  regulation: string;
+  section: string;
+}
+
+export interface EvidenceRequirement {
+  evidence_type: string;
+  description: string;
+  required: boolean;
+}
+
+export interface EvidenceResult {
+  regulation: string;
+  section: string;
+  evidence_requirements: EvidenceRequirement[];
+  notes: string;
+}
+
+/**
+ * Get evidence requirements for compliance with a specific section.
+ * MVP: Returns placeholder until evidence data is seeded.
+ * Future: Will query evidence_requirements table.
+ */
+export async function getEvidenceRequirements(
+  db: Database,
+  input: EvidenceInput
+): Promise<EvidenceResult> {
+  const { regulation, section } = input;
+
+  if (!regulation || !section) {
+    throw new Error('Both regulation and section are required');
+  }
+
+  // Verify section exists
+  const sectionExists = db
+    .prepare('SELECT 1 FROM sections WHERE regulation = ? AND section_number = ?')
+    .get(regulation, section);
+
+  if (!sectionExists) {
+    throw new Error(`Section ${section} not found in regulation ${regulation}`);
+  }
+
+  // MVP: Return empty array with note about future implementation
+  // In production, this would query an evidence_requirements table
+  return {
+    regulation,
+    section,
+    evidence_requirements: [],
+    notes: 'Evidence requirements data not yet available. This feature will be implemented in a future release with specific audit artifacts, policies, and procedures required for compliance.',
+  };
+}

package/src/tools/list.ts

@@ -0,0 +1,120 @@
+import type { Database } from 'better-sqlite3';
+
+export interface ListInput {
+  regulation?: string;
+}
+
+export interface RegulationInfo {
+  id: string;
+  full_name: string;
+  citation: string;
+  effective_date: string | null;
+  jurisdiction: string | null;
+}
+
+export interface Chapter {
+  name: string;
+  sections: string[];
+}
+
+export interface RegulationStructure {
+  regulation: RegulationInfo;
+  chapters: Chapter[];
+}
+
+export interface ListResult {
+  regulations?: RegulationInfo[];
+  structure?: RegulationStructure;
+}
+
+export async function listRegulations(
+  db: Database,
+  input: ListInput
+): Promise<ListResult> {
+  const { regulation } = input;
+
+  if (regulation) {
+    // Get specific regulation with chapters
+    const regRow = db.prepare(`
+      SELECT id, full_name, citation, effective_date, jurisdiction
+      FROM regulations
+      WHERE id = ?
+    `).get(regulation) as {
+      id: string;
+      full_name: string;
+      citation: string;
+      effective_date: string | null;
+      jurisdiction: string | null;
+    } | undefined;
+
+    if (!regRow) {
+      return { regulations: [] };
+    }
+
+    // Get sections grouped by chapter
+    const sections = db.prepare(`
+      SELECT section_number, title, chapter
+      FROM sections
+      WHERE regulation = ?
+      ORDER BY section_number
+    `).all(regulation) as Array<{
+      section_number: string;
+      title: string | null;
+      chapter: string | null;
+    }>;
+
+    // Group by chapter
+    const chapterMap = new Map<string, Chapter>();
+    for (const section of sections) {
+      const chapterKey = section.chapter || 'General';
+      if (!chapterMap.has(chapterKey)) {
+        chapterMap.set(chapterKey, {
+          name: chapterKey,
+          sections: [],
+        });
+      }
+      chapterMap.get(chapterKey)!.sections.push(section.section_number);
+    }
+
+    return {
+      structure: {
+        regulation: {
+          id: regRow.id,
+          full_name: regRow.full_name,
+          citation: regRow.citation,
+          effective_date: regRow.effective_date,
+          jurisdiction: regRow.jurisdiction,
+        },
+        chapters: Array.from(chapterMap.values()),
+      },
+    };
+  }
+
+  // List all regulations
+  const rows = db.prepare(`
+    SELECT
+      id,
+      full_name,
+      citation,
+      effective_date,
+      jurisdiction
+    FROM regulations
+    ORDER BY id
+  `).all() as Array<{
+    id: string;
+    full_name: string;
+    citation: string;
+    effective_date: string | null;
+    jurisdiction: string | null;
+  }>;
+
+  return {
+    regulations: rows.map(row => ({
+      id: row.id,
+      full_name: row.full_name,
+      citation: row.citation,
+      effective_date: row.effective_date,
+      jurisdiction: row.jurisdiction,
+    })),
+  };
+}

package/src/tools/map.ts

@@ -0,0 +1,100 @@
+import type { Database } from 'better-sqlite3';
+
+export interface MapControlsInput {
+  framework: string;
+  control?: string;
+  regulation?: string;
+}
+
+export interface ControlMapping {
+  framework: string;
+  control_id: string;
+  control_name: string;
+  regulation: string;
+  sections: string[];
+  coverage: 'full' | 'partial' | 'related';
+  notes: string | null;
+}
+
+export interface MapControlsResult {
+  framework: string;
+  mappings: ControlMapping[];
+  total_mappings: number;
+}
+
+/**
+ * Map NIST controls (800-53, CSF) to regulation sections.
+ * Can filter by specific control ID or regulation.
+ */
+export async function mapControls(
+  db: Database,
+  input: MapControlsInput
+): Promise<MapControlsResult> {
+  const { framework, control, regulation } = input;
+
+  if (!framework) {
+    throw new Error('Framework is required (e.g., "NIST_CSF", "NIST_800_53")');
+  }
+
+  // Build query with optional filters
+  let sql = `
+    SELECT
+      framework,
+      control_id,
+      control_name,
+      regulation,
+      sections,
+      coverage,
+      notes
+    FROM control_mappings
+    WHERE framework = ?
+  `;
+
+  const params: string[] = [framework];
+
+  if (control) {
+    sql += ' AND control_id = ?';
+    params.push(control);
+  }
+
+  if (regulation) {
+    sql += ' AND regulation = ?';
+    params.push(regulation);
+  }
+
+  sql += ' ORDER BY control_id, regulation';
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    framework: string;
+    control_id: string;
+    control_name: string;
+    regulation: string;
+    sections: string;
+    coverage: 'full' | 'partial' | 'related';
+    notes: string | null;
+  }>;
+
+  // Parse sections JSON
+  const mappings = rows.map((row) => ({
+    framework: row.framework,
+    control_id: row.control_id,
+    control_name: row.control_name,
+    regulation: row.regulation,
+    sections: (() => {
+      try {
+        return JSON.parse(row.sections);
+      } catch {
+        console.warn(`Invalid sections JSON for ${row.control_id}`);
+        return [];
+      }
+    })(),
+    coverage: row.coverage,
+    notes: row.notes,
+  }));
+
+  return {
+    framework,
+    mappings,
+    total_mappings: mappings.length,
+  };
+}