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 }; }