atoms.js

/**
 * @file atoms.js
 *
 * Wires the MCP server with dynamically-generated definitions
 * provided by `builderBot()`.
 *
 * builderBot(basePath) → Promise<{
 *    [folderName]: [
 *      { name, title, description, inputSchema, outputSchema, defaultExport, file, mimeType }
 *    ]
 * }>
 *
 * Registration patterns:
 * - Tools: server.registerTool(name, { title, description, inputSchema }, handler)
 *   - inputSchema is converted to JSON Schema format with required: ['field1', 'field2'] array
 * - Prompts: server.registerPrompt(name, { title, description, argsSchema }, handler)
 *   - Prompts should return { messages: [...] } format
 *   - argsSchema is extracted from inputSchema shape (Zod schema)
 *   - Required/optional determined by isSchemaOptional(), converted to PromptArgument[] with required: boolean
 * - Resources: server.registerResource(resourceName, resourceUri, { title, description, inputSchema }, handler)
 *   - ResourceTemplates do NOT support inputSchema validation or required field definitions
 *   - Variables are extracted from URI pattern only (e.g., {userId} from 'users://{userId}/profile')
 *   - inputSchema in metadata is for documentation purposes only
 */

import path from 'path';
//import scribbles from 'scribbles';
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
//import { ListPromptsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { getObjectShape, getSchemaDescription } from '@modelcontextprotocol/sdk/server/zod-compat.js';
import { isSchemaOptional as sdkIsSchemaOptional } from '@modelcontextprotocol/sdk/server/zod-compat.js';
import builderBot, { segmentsAfterStart, buildResourceName, buildResourceUri } from './builderBot/index.js';
import packageJson from './package.json' with { type: 'json' };

// Workaround for SDK bug: isSchemaOptional doesn't check isOptional() method for Zod v4
// v4 has isOptional() method and _zod.def.type === 'optional', but SDK only checks typeName === 'ZodOptional'
// Since we can't patch ES module exports, we'll patch the McpServer's setPromptRequestHandlers method
// to use a fixed version of promptArgumentsFromSchema

// Fixed isSchemaOptional that checks isOptional() method for both v3 and v4
function fixedIsSchemaOptional(schema) {
  // Check isOptional() method first for both v3 and v4 (v4 has this method too)
  if (typeof schema.isOptional === 'function') {
    return schema.isOptional();
  }
  // Fall back to SDK's original implementation
  return sdkIsSchemaOptional(schema);
}

// Patch the server's setPromptRequestHandlers to use our fixed promptArgumentsFromSchema
// This fixes the bug where optional fields aren't detected for Zod v4
// NOTE: This patching code is moved into robotIsworking function where server is available
// The original code here referenced 'server' before it was defined, causing module load errors
// 
// This patching should be done per-server instance inside robotIsworking if needed

// ------------------------------------------------------------
// REGISTER GENERATED TOOLS
// ------------------------------------------------------------

const _startFrom = './register';

/**
 * Extract arguments from a Zod schema for prompts, determining required/optional based on optional fields.
 * This is used for logging/debugging purposes. The actual conversion is done by the SDK's promptArgumentsFromSchema.
 * 
 * @param {import('zod').ZodType} schema - Zod object schema
 * @returns {Array<{name: string, description?: string, required: boolean}>}
 */
function extractArgumentsFromSchema(schema) {
  if (!schema) return [];
  
  // Normalize the schema to get the object shape
  const shape = getObjectShape(schema);
  if (!shape) return [];
  
  return Object.entries(shape).map(([name, field]) => {
    const description = getSchemaDescription(field);
    const isOptional = fixedIsSchemaOptional(field);
    return {
      name,
      description: description || undefined,
      required: !isOptional
    };
  });
}

/**
 * robotIsworking resolves to the fully configured MCP server.
 * This keeps the export simple for the consumer.
 */
const robotIsworking = (startFrom=_startFrom,server=null)=>builderBot(startFrom).then(items => {

  if(!server){
    server = new McpServer({
      name: packageJson.name,
      version: packageJson.version
    });
  }

  for (const itemName in items) {
    const tidyName = tidy4(itemName);

    items[itemName].forEach(
      (item) => {

      const { name, title, description, inputSchema, outputSchema, mimeType, defaultExport, file, relativePath, autocomplete } = item;

      // HANDLE PROMPTS specially
      if (tidyName === 'Prompt') {
        // Extract argsSchema from inputSchema (prompts use argsSchema, not inputSchema)
        // argsSchema should be the shape object from a Zod object schema
        // The shape is an object like { name: z.string(), style: z.string().optional() }
        // The SDK's objectFromShape will process this shape and preserve optional fields
        let argsSchema = undefined;
        if (inputSchema) {
          // Zod objects have a 'shape' property that contains the shape object
          // Note: _def.shape is a function, not an object, so we use the shape property directly
          if (typeof inputSchema === 'object' && 'shape' in inputSchema) {
            argsSchema = inputSchema.shape;
          }
        }

        // Prompt handler receives (args, extra) and should return { messages: [...] }
        // The defaultExport should return { messages: [...] } format per MCP spec
        const handler = async (args = {}, extra = {}) => {
          // Call defaultExport with the arguments
          const result = await Promise.resolve(defaultExport(args));
          
          // If result already has messages array, return it directly (expected format)
          if (result && typeof result === 'object' && Array.isArray(result.messages)) {
            return result;
          }
          
          // Fallback: if result doesn't have messages, wrap it
          // This handles cases where the function returns a string or other format
          const text = typeof result === 'string' 
            ? result 
            : (result && typeof result === 'object' && result.text)
            ? result.text
            : JSON.stringify(result);
          
          return {
            messages: [
              {
                role: 'user',
                content: {
                  type: 'text',
                  text: text
                }
              }
            ]
          };
        };

        // Verify argsSchema before registration - check required/optional
        if (argsSchema && inputSchema) {
          // Log what we're passing to the SDK
         // scribbles.log(`[atoms] Prompt ${name} argsSchema keys:`, Object.keys(argsSchema));
          for (const [key, field] of Object.entries(argsSchema)) {
            const isOptional = field && typeof field === 'object' && 
                             (field.constructor.name === 'ZodOptional' || 
                              (typeof field.isOptional === 'function' && field.isOptional()));
            //scribbles.log(`  ${key}: type=${field?.constructor?.name}, isOptional=${isOptional}, required=${!isOptional}`);
          }
          
          // Also test using our helper function
          const testArgs = extractArgumentsFromSchema(inputSchema);
         // scribbles.log(`[atoms] Prompt ${name} extracted arguments (from inputSchema):`, testArgs);
        }

        // Register the prompt
        server.registerPrompt(
          name,
          {
            title,
            description,
            argsSchema
          },
          handler
        );

        return; // continue to next item
      } // END if Prompt

      // HANDLE RESOURCES specially
      if (tidyName === 'Resource') {

        // Compute segments after the startFrom folder so we can build the resource name & uri.
        // Use relativePath if available (from recursive fileWalker), otherwise compute from file path
        const segs = relativePath 
          ? relativePath.split(path.sep).filter(Boolean)
          : segmentsAfterStart(file, startFrom);

        // Registration NAME (dash-joined, placeholders removed)
        const registrationName = buildResourceName(segs);

        // Resource URI like "users://{userId}/profile" or "config://app"
        const resourceUriString = buildResourceUri(segs);
        
        // Check if URI contains placeholders (e.g., {userId})
        // Note: ResourceTemplates do NOT support inputSchema or required field definitions
        // Variables are extracted from the URI pattern only
        const hasParameters = /\{[^}]+\}/.test(resourceUriString);
        
        // meta passed to registerResource
        // Note: inputSchema is included for documentation purposes only, not for validation
        const meta = { 
          title, 
          description, 
          inputSchema  // For documentation only - ResourceTemplates don't validate this
        };

        // Register the resource on the server.
        // Use ResourceTemplate if it has parameters, otherwise use plain URI string
        if (hasParameters) {
          // Dynamic resource with parameters - use ResourceTemplate
          // Handler signature: (uri: URL, variables: Variables, extra)
          // Build template config with autocomplete if present
          const templateConfig = {
            list: undefined // No list of available resources
          };
          
          // Add complete functions if autocomplete export exists
          // Check that autocomplete is a plain object (not array) with function values
          if (autocomplete && 
              typeof autocomplete === 'object' && 
              !Array.isArray(autocomplete) &&
              Object.values(autocomplete).some(v => typeof v === 'function')) {
            templateConfig.complete = autocomplete;
          //  scribbles.log(`[atoms] Adding autocomplete for ${registrationName}:`, autocomplete);
          } /*else {
            scribbles.log(`[atoms] No autocomplete found for ${registrationName}`, autocomplete);
          }*/
          
          const resourceTemplate = new ResourceTemplate(resourceUriString, templateConfig);
          
          const handler = async (uri, variables={}, extra={}) => {
            // variables contains extracted URI parameters (e.g., { userId: "123" })
            const raw = await Promise.resolve(defaultExport({uri, ...variables, ...extra}));
            
            // If already an array, assume it's already in the correct format
            if (Array.isArray(raw)) {
              return { contents: raw };
            } 
            
            const output = raw;
            const isObject = output !== null && typeof output === 'object';
            const primaryMime = mimeType || (isObject ? 'application/json' : 'text/plain');
            const primaryText = isObject ? JSON.stringify(output) : String(output);

            return { 
              contents: [{ 
                uri: uri.href,
                mimeType: primaryMime, 
                text: primaryText 
              }]
            };
          };

          server.registerResource(registrationName, 
            resourceTemplate, 
            meta, 
            handler);
        } else {
          // Static resource without parameters - use plain URI string
          // Handler signature: (uri: URL, extra)
          const handler = async (uri, extra={}) => {
            // No parameters, pass empty object to defaultExport
            const raw = await Promise.resolve(defaultExport({uri, ...extra}));
            
            // If already an array, assume it's already in the correct format
            if (Array.isArray(raw)) {
              return { contents: raw };
            } 
            
            const output = raw;
            const isObject = output !== null && typeof output === 'object';
            const primaryMime = mimeType || (isObject ? 'application/json' : 'text/plain');
            const primaryText = isObject ? JSON.stringify(output) : String(output);

            return { 
              contents: [{ 
                uri: uri.href,
                mimeType: primaryMime, 
                text: primaryText 
              }]
            };
          };

          server.registerResource(registrationName, 
            resourceUriString, 
            meta, 
            handler);
        }

        return; // continue to next item
      } // END if Resource
      
      // Default non-resource registration:
      server[`register${tidyName}`](
        name,
        { title, description, inputSchema },
        (...args) => {
          return Promise.resolve(defaultExport(...args)).then(result => {
            let output = result, more = [];
            if(Array.isArray(result)){
               const [a, ...b] = result;
               output = a;
               more = b;
            }

            return {
              content: [
                { type: 'text', text: JSON.stringify(output) },
                ...more
              ],
              structuredContent: output
            }; // END return
          })
        } // END handler function
      ); // END server.register...
    } // END forEach item
    ); // END forEach
  } // END for..in items

  return server;
}); // END robotIsworking

export default robotIsworking;

/**
 * Convert a folder name like "tools" → "Tool".
 * Removes trailing "s" and capitalises the first letter.
 *
 * @param {string} s
 * @returns {string}
 */
function tidy4(s) {
  return (s || '')
    .replace(/s$/i, '')
    .replace(/^./, c => c.toUpperCase())
}