oscal_fragment

Instructions

Implementation Reference

• src/tools/compliance/oscal-fragment.ts:5-37 (schema)

  Tool definition and input schema for oscal_fragment: defines name, description, and JSON Schema input properties (resourceDescription, controlIds, format, systemId, componentName) with resourceDescription and controlIds required.

  export const oscalFragmentTool = {
    name: 'oscal_fragment',
    description:
      'Generate valid OSCAL SSP fragment (JSON or XML) for Azure resource configurations. Machine-readable output compatible with eMASS OSCAL import.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        resourceDescription: {
          type: 'string',
          description: 'Describe the Azure resource or configuration',
        },
        controlIds: {
          type: 'array',
          items: { type: 'string' },
          description: 'Control IDs to generate OSCAL for, e.g. ["SC-28","SC-12"]',
        },
        format: {
          type: 'string',
          enum: ['json', 'xml'],
          description: 'Output format (default: json)',
        },
        systemId: {
          type: 'string',
          description: 'eMASS system ID (optional)',
        },
        componentName: {
          type: 'string',
          description: 'Component name (optional)',
        },
      },
      required: ['resourceDescription', 'controlIds'],
    },
  };

• src/tools/compliance/oscal-fragment.ts:39-45 (schema)

  Zod validation schema for oscal_fragment: validates resourceDescription (max 500), controlIds (array of strings max 500, min 1, max 20), format (json|xml, default json), and optional systemId/componentName (max 500 each).

  const Schema = z.object({
    resourceDescription: z.string().max(500),
    controlIds: z.array(z.string().max(500)).min(1).max(20),
    format: z.enum(['json', 'xml']).default('json'),
    systemId: z.string().max(500).optional(),
    componentName: z.string().max(500).optional(),
  });

• src/tools/compliance/oscal-fragment.ts:60-83 (handler)

  The main handler function handleOscalFragment: calls runTool with the tool name, args, schema, and an async function that invokes Anthropic Claude to generate an OSCAL 1.1.2 SSP fragment in JSON or XML format based on resource description, control IDs, and optional system ID/component name. Uses the OSCAL_SYSTEM system prompt and token budget of 4096.

  export async function handleOscalFragment(args: unknown): Promise<string> {
    return runTool('oscal_fragment', args, Schema, async ({ resourceDescription, controlIds, format, systemId, componentName }) => {
      const response = await anthropic.messages.create({
        model: MODEL,
        max_tokens: getTokenBudget('oscal_fragment'),
        system: OSCAL_SYSTEM,
        messages: [
          {
            role: 'user',
            content: `Generate an OSCAL 1.1.2 SSP fragment in ${(format ?? 'json').toUpperCase()} format.
  
  **Resource/Configuration:** ${resourceDescription}
  **Controls to Cover:** ${controlIds.join(', ')}
  ${systemId ? `**eMASS System ID:** ${systemId}` : ''}
  ${componentName ? `**Component Name:** ${componentName}` : ''}
  
  Generate the complete OSCAL fragment with implemented-requirements, by-components, and set-parameters sections.`,
          },
        ],
      });
  
      return response.content[0].type === 'text' ? response.content[0].text : '';
    });
  }

• src/tools/compliance/oscal-fragment.ts:47-58 (helper)

  OSCAL_SYSTEM system prompt constant: instructs the model to generate valid OSCAL 1.1.2 compliant fragments for eMASS import with specific requirements (implemented-requirements with by-components, set-parameters, proper UUIDs, implementation-status, responsible-roles, etc.).

  const OSCAL_SYSTEM = `${BASE_SYSTEM_PROMPT}
  
  You generate valid OSCAL 1.1.2 compliant fragments for eMASS import. Requirements:
  - Generate valid OSCAL JSON or XML (user specified)
  - Include implemented-requirements with by-components
  - Include set-parameters where the control has configurable parameters
  - Use proper OSCAL UUIDs (use placeholder UUIDs in format: 00000000-0000-4000-8000-NNNNNNNNNNNN)
  - Use "implementation-status": "implemented" or "partial" based on context
  - Include "description" fields with specific technical implementation text
  - Reference the Azure service as the component
  - Include "responsible-roles" mapping to customer/provider
  - OSCAL output must be syntactically valid — it will be imported into eMASS`;

• src/tools/index.ts:7-7 (registration)

  Import of oscalFragmentTool and handleOscalFragment from the compliance/oscal-fragment module.

  import { oscalFragmentTool, handleOscalFragment } from './compliance/oscal-fragment.js';

• src/tools/index.ts:37-37 (registration)

  Registration of oscalFragmentTool in the allTools array for MCP tool listing.

  oscalFragmentTool,

• src/tools/index.ts:68-68 (registration)

  Dispatch registration: maps the 'oscal_fragment' name to handleOscalFragment in the tool call switch statement.

  case 'oscal_fragment':        return handleOscalFragment(args);

• src/utils/tool-runner.ts:20-20 (helper)

  Token budget configuration: oscal_fragment is allocated 4096 max tokens for AI responses.

  oscal_fragment: 4096,

• src/utils/tool-runner.ts:49-49 (helper)

  Timeout configuration: oscal_fragment has a 45-second (45000ms) timeout.

  oscal_fragment: 45000,

• src/utils/response-validator.ts:21-21 (helper)

  Minimum response length requirement: oscal_fragment responses must be at least 200 characters.

  oscal_fragment: 200,

• src/utils/response-validator.ts:76-85 (helper)

  Response quality validation specific to oscal_fragment: checks that the output contains valid JSON (starts with { or [) or XML (starts with <) or JSON/XML code blocks, otherwise flags an issue.

  if (tool === 'oscal_fragment') {
    const trimmed = response.trim();
    const hasJson = trimmed.startsWith('{') || trimmed.startsWith('[');
    const hasXml = trimmed.startsWith('<');
    const hasJsonBlock = response.includes('```json');
    const hasXmlBlock = response.includes('```xml');
    if (!hasJson && !hasXml && !hasJsonBlock && !hasXmlBlock) {
      issues.push('OSCAL output must be JSON or XML');
    }
  }