Flint Note

Instructions

Implementation Reference

• src/server/note-handlers.ts:46-108 (handler)

  MCP tool handler for 'create_note'. Validates args, handles single or batch note creation via noteManager.createNote or batchCreateNotes, appends agent instructions.

  handleCreateNote = async (args: CreateNoteArgs) => {
    // Validate arguments
    validateToolArgs('create_note', args);
  
    const { noteManager, noteTypeManager } = await this.resolveVaultContext(
      args.vault_id
    );
  
    // Handle batch creation if notes array is provided
    if (args.notes) {
      const result = await noteManager.batchCreateNotes(args.notes);
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    }
  
    // Handle single note creation
    if (!args.type || !args.title || !args.content) {
      throw new Error('Single note creation requires type, title, and content');
    }
  
    const noteInfo = await noteManager.createNote(
      args.type,
      args.title,
      args.content,
      args.metadata || {}
    );
  
    // Get agent instructions for this note type
    let agentInstructions: string[] = [];
    let nextSuggestions = '';
    try {
      const typeInfo = await noteTypeManager.getNoteTypeDescription(args.type);
      agentInstructions = typeInfo.parsed.agentInstructions;
      if (agentInstructions.length > 0) {
        nextSuggestions = `Consider following these guidelines for ${args.type} notes: ${agentInstructions.join(', ')}`;
      }
    } catch {
      // Ignore errors getting type info, continue without instructions
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              ...noteInfo,
              agent_instructions: agentInstructions,
              next_suggestions: nextSuggestions
            },
            null,
            2
          )
        }
      ]
    };
  };

• src/server/tool-schemas.ts:85-149 (schema)

  JSON schema definition for the 'create_note' tool input, supporting single note or batch creation via 'notes' array.

  name: 'create_note',
  description: 'Create one or more notes of the specified type(s)',
  inputSchema: {
    type: 'object',
    properties: {
      type: {
        type: 'string',
        description: 'Type of note to create'
      },
      title: {
        type: 'string',
        description: 'Title of the note'
      },
      content: {
        type: 'string',
        description: 'Content of the note in markdown format',
        default: ''
      },
      metadata: {
        type: 'object',
        description: 'Additional metadata for the note'
      },
      vault_id: {
        type: 'string',
        description:
          'Optional vault ID to create the note in. If not provided, uses the current active vault.'
      },
      notes: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            type: {
              type: 'string',
              description: 'Type of note to create'
            },
            title: {
              type: 'string',
              description: 'Title of the note'
            },
            content: {
              type: 'string',
              description: 'Content of the note in markdown format',
              default: ''
            },
            metadata: {
              type: 'object',
              description: 'Additional metadata for the note'
            }
          },
          required: ['type', 'title']
        },
        description:
          'Array of notes to create in batch (alternative to single note creation)'
      }
    },
    oneOf: [
      {
        required: ['type', 'title']
      },
      {
        required: ['notes']
      }
    ]
  }

• src/server.ts:1237-1239 (registration)

  Registration of 'create_note' handler in the MCP CallToolRequestSchema switch statement, dispatching to noteHandlers.handleCreateNote

  return await this.noteHandlers.handleCreateNote(
    args as unknown as CreateNoteArgs
  );

• src/core/notes.ts:129-206 (helper)

  Core implementation of single note creation: generates FS-safe filename, validates metadata schema, formats YAML frontmatter, writes .md file, indexes for search.

  async createNote(
    typeName: string,
    title: string,
    content: string,
    metadata: Record<string, unknown> = {}
  ): Promise<NoteInfo> {
    try {
      // Validate inputs
      if (!title || title.trim().length === 0) {
        throw new Error('Note title is required and cannot be empty');
      }
  
      // Trim the title for consistent handling
      const trimmedTitle = title.trim();
  
      // Validate and ensure note type exists
      if (!this.#workspace.isValidNoteTypeName(typeName)) {
        throw new Error(`Invalid note type name: ${typeName}`);
      }
  
      const typePath = await this.#workspace.ensureNoteType(typeName);
  
      // Generate filename from title and check availability
      const baseFilename = this.generateFilename(trimmedTitle);
      await this.checkFilenameAvailability(typePath, baseFilename);
      const filename = baseFilename;
      const notePath = path.join(typePath, filename);
  
      // Prepare metadata with title for validation
      const metadataWithTitle = {
        title: trimmedTitle,
        ...metadata
      };
  
      // Validate metadata against schema
      const validationResult = await this.validateMetadata(typeName, metadataWithTitle);
      if (!validationResult.valid) {
        throw new Error(
          `Metadata validation failed: ${validationResult.errors.map(e => e.message).join(', ')}`
        );
      }
  
      // Prepare note content with metadata
      const noteContent = await this.formatNoteContent(
        trimmedTitle,
        content,
        typeName,
        metadata
      );
  
      // Write the note file
      await fs.writeFile(notePath, noteContent, 'utf-8');
  
      // Update search index
      await this.updateSearchIndex(notePath, noteContent);
  
      return {
        id: this.generateNoteId(typeName, filename),
        type: typeName,
        title: trimmedTitle,
        filename,
        path: notePath,
        created: new Date().toISOString()
      };
    } catch (error) {
      if (error instanceof Error) {
        // Preserve custom error properties if they exist
        const flintError = error as FlintNoteError;
        if (flintError.code === 'NOTE_ALREADY_EXISTS') {
          // Re-throw the original error for duplicate notes to preserve error details
          throw error;
        }
        // For other errors, wrap with context
        throw new Error(`Failed to create note '${title}': ${error.message}`);
      }
      throw new Error(`Failed to create note '${title}': Unknown error`);
    }
  }

• src/core/notes.ts:1216-1252 (helper)

  Batch note creation helper: loops over input array calling createNote, returns summary of successful/failed creations.

  async batchCreateNotes(notes: BatchCreateNoteInput[]): Promise<BatchCreateResult> {
    const results: BatchCreateResult['results'] = [];
    let successful = 0;
    let failed = 0;
  
    for (const noteInput of notes) {
      try {
        const result = await this.createNote(
          noteInput.type,
          noteInput.title,
          noteInput.content,
          noteInput.metadata || {}
        );
        results.push({
          input: noteInput,
          success: true,
          result
        });
        successful++;
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
        results.push({
          input: noteInput,
          success: false,
          error: errorMessage
        });
        failed++;
      }
    }
  
    return {
      total: notes.length,
      successful,
      failed,
      results
    };
  }