create_tiddler

Instructions

Implementation Reference

• src/tools/create-tiddler.ts:37-79 (handler)

  Main handler function for create_tiddler tool. Parses input via Zod schema, checks for duplicate tiddlers, creates a new tiddler object (with custom fields merged), generates a preview, calls putTiddler to save it, and returns the preview result.

  export async function handleCreateTiddler(args: unknown): Promise<ToolResult> {
    const input = CreateTiddlerInput.parse(args);
  
    // Check if tiddler already exists
    const existing = await getTiddler(input.title);
    if (existing) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              { error: `Tiddler already exists: ${input.title}. Use update_tiddler to modify it.` },
              null,
              2
            ),
          },
        ],
        isError: true,
      };
    }
  
    // Create new tiddler object with custom fields
    const { title, text, tags, type, ...customFields } = input;
    const newTiddler = {
      ...createTiddlerObject(title, text, tags || '', type || 'text/markdown', getAuthUser()),
      ...customFields, // Add any custom fields
    };
  
    // Generate preview
    const preview = formatTiddlerPreview(newTiddler);
  
    // Create the tiddler
    await putTiddler(newTiddler);
  
    return {
      content: [
        {
          type: 'text',
          text: `## Created: "${input.title}"\n\n${preview}`,
        },
      ],
    };
  }

• src/tools/types.ts:83-92 (schema)

  Zod schema for CreateTiddlerInput validating title (string, required), text (string, required), tags (optional string), type (optional string, default text/markdown), and allowing passthrough for arbitrary custom fields.

  export const CreateTiddlerInput = z
    .object({
      title: z.string().describe('Title of the new tiddler'),
      text: z.string().describe('Text content'),
      tags: z.string().optional().describe('Tags (space-separated)'),
      type: z.string().optional().describe('Content type (default: text/markdown)'),
    })
    .passthrough(); // Allow additional custom fields
  
  export type CreateTiddlerInputType = z.infer<typeof CreateTiddlerInput>;

• src/index.ts:185-218 (registration)

  Tool registration: declares the 'create_tiddler' tool with description and inputSchema for the MCP server, including title (required), text (required), tags (optional), type (optional), and additionalProperties for custom fields.

  {
    name: 'create_tiddler',
    description:
      'Create a new tiddler. Shows a preview and requests approval before creating. Supports arbitrary custom fields beyond the standard ones (e.g., caption, summary, author, or any TiddlyWiki field).',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: 'Title of the new tiddler',
        },
        text: {
          type: 'string',
          description: 'Text content',
        },
        tags: {
          type: 'string',
          description:
            'Tags as space-separated string (optional, e.g., "Journal" or "Journal OYS")',
          default: '',
        },
        type: {
          type: 'string',
          description: 'Content type (default: text/markdown)',
          default: 'text/markdown',
        },
      },
      additionalProperties: {
        type: 'string',
        description: 'Any additional TiddlyWiki field (e.g., caption, summary, author)',
      },
      required: ['title', 'text'],
    },
  },

• src/index.ts:250-251 (registration)

  Dispatch switch-case in CallToolRequestSchema handler that routes 'create_tiddler' requests to the handleCreateTiddler function.

  case 'create_tiddler':
    return await handleCreateTiddler(args);

• src/tiddlywiki-http.ts:341-356 (helper)

  Helper function createTiddlerObject: constructs a Tiddler object with title, text, type, tags, created timestamp, and creator. Used by the handler to build the new tiddler payload.

  export function createTiddlerObject(
    title: string,
    text: string,
    tags: string = '',
    type: string = 'text/markdown',
    creator: string
  ): Tiddler {
    return {
      title,
      text,
      type,
      tags,
      created: generateTimestamp(),
      creator,
    };
  }