Telegraph MCP Server

Instructions

Implementation Reference

• src/tools/pages.ts:235-252 (handler)

  Tool handler case that validates input, parses content, calls the createPage API wrapper, and returns the result as a text content block.

  case 'telegraph_create_page': {
    const input = CreatePageSchema.parse(args);
    const content = telegraph.parseContent(input.content, input.format);
    const result = await telegraph.createPage(
      input.access_token,
      input.title,
      content,
      input.author_name,
      input.author_url,
      input.return_content
    );
    return {
      content: [{
        type: 'text' as const,
        text: JSON.stringify(result, null, 2),
      }],
    };
  }

• src/tools/pages.ts:52-96 (registration)

  Tool registration definition in the pageTools array, including name, description, and JSON input schema.

  {
    name: 'telegraph_create_page',
    description: 'Create a new Telegraph page. Returns a Page object including the URL of the created page.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        access_token: {
          type: 'string',
          description: 'Access token of the Telegraph account',
        },
        title: {
          type: 'string',
          description: 'Page title (1-256 characters)',
          minLength: 1,
          maxLength: 256,
        },
        content: {
          type: 'string',
          description: 'Page content - can be HTML string (e.g., "<p>Hello <b>world</b></p>"), Markdown string, or JSON array of Node objects',
        },
        format: {
          type: 'string',
          description: 'Content format: "html" or "markdown" (default: "html")',
          enum: ['html', 'markdown'],
          default: 'html',
        },
        author_name: {
          type: 'string',
          description: 'Author name displayed below the title (0-128 characters)',
          maxLength: 128,
        },
        author_url: {
          type: 'string',
          description: 'Profile link opened when users click on the author name (0-512 characters)',
          maxLength: 512,
        },
        return_content: {
          type: 'boolean',
          description: 'If true, the content field will be returned in the Page object',
          default: false,
        },
      },
      required: ['access_token', 'title', 'content'],
    },
  },

• src/tools/pages.ts:10-18 (schema)

  Zod schema for input validation, parsed in the handler.

  export const CreatePageSchema = z.object({
    access_token: z.string().describe('Access token of the Telegraph account'),
    title: z.string().min(1).max(256).describe('Page title (1-256 characters)'),
    content: z.string().describe('Page content - can be HTML string, Markdown string, or JSON array of Node objects'),
    format: z.enum(['html', 'markdown']).optional().default('html').describe('Content format: "html" or "markdown" (default: "html")'),
    author_name: z.string().max(128).optional().describe('Author name (0-128 characters)'),
    author_url: z.string().max(512).optional().describe('Profile link (0-512 characters)'),
    return_content: z.boolean().optional().describe('If true, content field will be returned in the Page object'),
  });

• src/telegraph-client.ts:137-153 (helper)

  Low-level API wrapper function that makes the POST request to Telegraph's createPage endpoint.

  export async function createPage(
    access_token: string,
    title: string,
    content: Node[],
    author_name?: string,
    author_url?: string,
    return_content?: boolean
  ): Promise<Page> {
    return apiRequest<Page>('createPage', {
      access_token,
      title,
      content,
      author_name,
      author_url,
      return_content,
    });
  }

• src/telegraph-client.ts:465-488 (helper)

  Utility function called by handler to parse input content into Telegraph Node array, supporting HTML, Markdown, or JSON.

  export function parseContent(content: string | Node[], format: 'html' | 'markdown' = 'html'): Node[] {
    if (Array.isArray(content)) {
      return content;
    }
  
    // Try to parse as JSON first (in case it's a stringified Node array)
    try {
      const parsed = JSON.parse(content);
      if (Array.isArray(parsed)) {
        return parsed;
      }
    } catch {
      // Not JSON, continue with string parsing
    }
  
    // Convert markdown to HTML if format is markdown
    let htmlContent = content;
    if (format === 'markdown') {
      htmlContent = markdownToHtml(content);
    }
  
    // Convert HTML to nodes
    return htmlToNodes(htmlContent);
  }