mcp-structured-memory

Instructions

Implementation Reference

• src/tools/addToList.ts:5-43 (handler)

  The addToListTool function implements the core logic: validates params, reads memory, finds section, formats item, appends to section via StorageManager, returns success message.

  export async function addToListTool(
    storageManager: StorageManager,
    args: any
  ): Promise<any> {
    const params = args as AddToListParams;
    
    if (!params.memory_id || !params.section || !params.item) {
      throw new Error('memory_id, section, and item are required');
    }
  
    // Read the memory document
    const memory = await storageManager.readMemory(params.memory_id);
    if (!memory) {
      throw new Error(`Memory document '${params.memory_id}' not found`);
    }
  
    // Find the section
    const section = storageManager.findSection(memory.content, params.section);
    if (!section) {
      throw new Error(`Section '${params.section}' not found in memory document '${params.memory_id}'`);
    }
  
    // Format the item using generic formatting
    const itemText = formatGenericItem(params.item);
  
    // Add the item to the section
    await storageManager.updateSection(params.memory_id, params.section, itemText, 'append');
  
    return {
      content: [{
        type: 'text',
        text: `Successfully added item to ${params.section} in memory document '${params.memory_id}':
  
  ${itemText}
  
  The item has been appended to the section. You can view the updated section using the get_section tool.`
      }]
    };
  }

• src/index.ts:59-81 (registration)

  Tool registration in ListToolsRequestSchema handler: defines name 'add_to_list', description, and inputSchema matching AddToListParams.

  {
    name: "add_to_list",
    description: "Add an item to a list section in a memory document",
    inputSchema: {
      type: "object",
      properties: {
        memory_id: {
          type: "string",
          description: "The ID of the memory document to update",
        },
        section: {
          type: "string",
          description: "The section name to add the item to",
        },
        item: {
          type: "object",
          description:
            "The item data to add (structure depends on template)",
        },
      },
      required: ["memory_id", "section", "item"],
    },
  },

• src/index.ts:262-263 (registration)

  Dispatch in CallToolRequestSchema switch statement: calls addToListTool for 'add_to_list'.

  case "add_to_list":
    return await addToListTool(storageManager, args);

• src/types/memory.ts:36-40 (schema)

  TypeScript interface AddToListParams defines the input parameters for the tool.

  export interface AddToListParams {
    memory_id: string;
    section: string;
    item: Record<string, any>;
  }

• src/tools/addToListHelpers.ts:32-77 (helper)

  formatGenericItem converts item objects/strings into formatted Markdown list items (with titles, stars, bullet fields), used by the handler.

  export function formatGenericItem(item: Record<string, any>): string {
    if (typeof item === 'string') {
      return `- ${item}`;
    }
    
    if (typeof item === 'object' && item !== null) {
      // Look for common title fields
      const titleFields = ['name', 'title', 'destination', 'company', 'activity'];
      let title = '';
      
      for (const field of titleFields) {
        if (item[field]) {
          title = String(item[field]);
          break;
        }
      }
      
      if (title) {
        // Format with star rating if present
        const stars = formatStarRating(item.rating || item.stars);
        let result = `### ${title}${stars}\n`;
        
        // Convert remaining fields to field list format
        const remainingFields: Record<string, string> = {};
        for (const [key, value] of Object.entries(item)) {
          if (!titleFields.includes(key) && key !== 'rating' && key !== 'stars' && value) {
            remainingFields[key] = String(value);
          }
        }
        
        result += formatFieldList(remainingFields);
        return result;
      } else {
        // Simple key-value format without title
        const fields: Record<string, string> = {};
        for (const [key, value] of Object.entries(item)) {
          if (value) {
            fields[key] = String(value);
          }
        }
        return formatFieldList(fields);
      }
    }
    
    return `- ${String(item)}`;
  }