MCP TriliumNext

Instructions

Implementation Reference

• src/tools/create-note.js:5-131 (handler)

  The primary handler function that executes the create_note tool logic: validates inputs, interacts with TriliumNext API to create a note, formats success/error responses in MCP format.

  export async function createNote(triliumClient, args) {
    try {
      // Validate inputs
      const title = validators.title(args.title);
      const content = validators.content(args.content);
      const type = validators.noteType(args.type);
      // TriliumNext API requires parentNoteId - default to 'root' if not provided
      const parentNoteId = args.parentNoteId ? validators.noteId(args.parentNoteId) : 'root';
  
      logger.debug(`Creating note: title="${title}", type="${type}", parent="${parentNoteId}"`);
  
      // Prepare note data for TriliumNext API
      const noteData = {
        title,
        content,
        type,
        parentNoteId, // Always required by TriliumNext API
      };
  
      // Create the note via TriliumNext API
      const result = await triliumClient.post('create-note', noteData);
      
      if (!result || !result.note || !result.note.noteId) {
        throw new TriliumAPIError('Invalid response from TriliumNext API - missing note ID');
      }
  
      const noteId = result.note.noteId;
      logger.info(`Note created successfully with ID: ${noteId}`);
  
      // Prepare structured response data
      const creationData = {
        operation: 'create_note',
        timestamp: new Date().toISOString(),
        request: {
          title,
          type,
          contentLength: content.length,
          parentNoteId
        },
        result: {
          noteId,
          ...result.note, // Include any additional data from API response
          triliumUrl: `trilium://note/${noteId}` // Add direct link if useful
        }
      };
  
      return {
        content: [
          {
            type: 'text',
            text: `Note created: "${title}" (ID: ${noteId})`
          },
          {
            type: 'application/json',
            text: JSON.stringify(creationData, null, 2)
          }
        ],
      };
    } catch (error) {
      logger.error(`Failed to create note: ${error.message}`);
      
      // Create structured error response
      const errorData = {
        operation: 'create_note',
        timestamp: new Date().toISOString(),
        request: {
          title: args.title,
          type: args.type,
          contentLength: args.content?.length,
          parentNoteId: args.parentNoteId
        },
        error: {
          type: error.constructor.name,
          message: error.message,
          ...(error instanceof TriliumAPIError && { status: error.status }),
          ...(error instanceof TriliumAPIError && error.details && { details: error.details })
        }
      };
      
      if (error instanceof ValidationError) {
        return {
          content: [
            {
              type: 'text',
              text: `Validation error: ${error.message}`
            },
            {
              type: 'application/json',
              text: JSON.stringify(errorData, null, 2)
            }
          ],
          isError: true,
        };
      }
      
      if (error instanceof TriliumAPIError) {
        return {
          content: [
            {
              type: 'text',
              text: `TriliumNext API error: ${error.message}`
            },
            {
              type: 'application/json',
              text: JSON.stringify(errorData, null, 2)
            }
          ],
          isError: true,
        };
      }
      
      // Unknown error
      return {
        content: [
          {
            type: 'text',
            text: `Note creation failed: ${error.message}`
          },
          {
            type: 'application/json',
            text: JSON.stringify(errorData, null, 2)
          }
        ],
        isError: true,
      };
    }
  }

• src/index.js:54-81 (schema)

  The MCP tool schema definition for 'create_note', including input schema with properties, types, descriptions, enums, and required fields.

  {
    name: 'create_note',
    description: 'Create a new note in TriliumNext',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: 'The title of the note (max 200 characters)',
        },
        content: {
          type: 'string',
          description: 'The content of the note (max 1MB)',
        },
        type: {
          type: 'string',
          enum: ['text', 'code', 'file', 'image', 'search', 'book', 'relationMap', 'canvas'],
          default: 'text',
          description: 'The type of note to create',
        },
        parentNoteId: {
          type: 'string',
          description: 'ID of the parent note (defaults to "root" if not provided)',
        },
      },
      required: ['title', 'content'],
    },
  },

• src/index.js:144-145 (registration)

  Registration of the create_note tool in the CallToolRequestSchema dispatch switch statement, routing calls to the handler.

  case 'create_note':
    return await this.createNote(request.params.arguments);

• src/index.js:201-203 (registration)

  Wrapper method on the server class that delegates create_note execution to the core handler function.

  async createNote(args) {
    return await createNote(this.triliumClient, args);
  }

• src/utils/validation.js:8-81 (helper)

  Validation helper functions used by the create_note handler for input sanitization and validation (title, content, type, noteId).

  export const validators = {
    noteId: (noteId) => {
      if (!noteId || typeof noteId !== 'string') {
        throw new ValidationError('Note ID must be a non-empty string');
      }
      if (noteId.trim().length === 0) {
        throw new ValidationError('Note ID cannot be empty');
      }
      return noteId.trim();
    },
  
    title: (title) => {
      if (!title || typeof title !== 'string') {
        throw new ValidationError('Title must be a non-empty string');
      }
      const trimmed = title.trim();
      if (trimmed.length === 0) {
        throw new ValidationError('Title cannot be empty');
      }
      if (trimmed.length > 200) {
        throw new ValidationError('Title cannot exceed 200 characters');
      }
      return trimmed;
    },
  
    content: (content) => {
      if (content === null || content === undefined) {
        throw new ValidationError('Content cannot be null or undefined');
      }
      if (typeof content !== 'string') {
        throw new ValidationError('Content must be a string');
      }
      if (content.length > 1000000) { // 1MB limit
        throw new ValidationError('Content cannot exceed 1MB');
      }
      return content;
    },
  
    noteType: (type) => {
      const validTypes = ['text', 'code', 'file', 'image', 'search', 'book', 'relationMap', 'canvas'];
      if (type && !validTypes.includes(type)) {
        throw new ValidationError(`Note type must be one of: ${validTypes.join(', ')}`);
      }
      return type || 'text';
    },
  
    searchQuery: (query) => {
      if (!query || typeof query !== 'string') {
        throw new ValidationError('Search query must be a non-empty string');
      }
      const trimmed = query.trim();
      if (trimmed.length === 0) {
        throw new ValidationError('Search query cannot be empty');
      }
      if (trimmed.length > 500) {
        throw new ValidationError('Search query cannot exceed 500 characters');
      }
      return trimmed;
    },
  
    limit: (limit) => {
      if (limit === undefined || limit === null) {
        return 10; // default
      }
      const num = parseInt(limit, 10);
      if (isNaN(num) || num < 1) {
        throw new ValidationError('Limit must be a positive integer');
      }
      if (num > 100) {
        throw new ValidationError('Limit cannot exceed 100');
      }
      return num;
    }
  };