Typst Universe MCP Server

Instructions

Implementation Reference

• src/scraper.ts:55-108 (handler)

  Core implementation of the search_packages tool: scrapes Typst Universe search results using Cheerio to extract package information.
  export async function searchPackages(options: SearchOptions = {}): Promise<TypstPackage[]> { const { query, kind = 'packages', category, limit = 50 } = options; // Build the search URL const searchParams = new URLSearchParams(); searchParams.set('kind', kind); if (query) { searchParams.set('q', query); } if (category) { searchParams.set('category', category); } const searchUrl = `${UNIVERSE_URL}/search/?${searchParams.toString()}`; const html = await fetchPage(searchUrl); const $ = cheerio.load(html); const packages: TypstPackage[] = []; // Parse the package list from the page // The packages are typically listed as links with package info $('a[href^="/universe/package/"]').each((_, element) => { const $el = $(element); const href = $el.attr('href'); if (!href) return; // Extract text content - name, version, and description are typically in the link text const text = $el.text().trim(); // Try to parse the package info from the text // Format is typically: "name0.0.0Description text here" const match = text.match(/^([a-z0-9_-]+)(\d+\.\d+\.\d+)(.*)$/i); if (match) { const [, name, version, description] = match; packages.push({ name: name.trim(), version: version.trim(), description: description.trim(), url: `${BASE_URL}${href}`, }); } }); // Remove duplicates (same package might appear multiple times) const uniquePackages = packages.filter((pkg, index, self) => index === self.findIndex(p => p.name === pkg.name) ); return uniquePackages.slice(0, limit); }
• src/index.ts:22-49 (registration)

  Tool registration in the TOOLS array, including name, description, and input schema for MCP protocol.
  { name: 'search_packages', description: 'Search for Typst packages in the Typst Universe. You can search by query text, filter by category, and specify the kind (packages or templates).', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query text to find packages (e.g., "math", "diagram", "table")', }, kind: { type: 'string', enum: ['packages', 'templates'], description: 'Type of items to search for. Defaults to "packages".', default: 'packages', }, category: { type: 'string', description: 'Filter by category (e.g., "visualization", "math", "text")', }, limit: { type: 'number', description: 'Maximum number of results to return. Defaults to 20.', default: 20, }, }, }, },
• src/index.ts:83-88 (schema)

  Zod schema for validating input arguments to the search_packages tool.
  const SearchPackagesSchema = z.object({ query: z.string().optional(), kind: z.enum(['packages', 'templates']).optional().default('packages'), category: z.string().optional(), limit: z.number().optional().default(20), });
• src/index.ts:173-202 (handler)

  MCP tool dispatch handler case that validates arguments, calls the core searchPackages function, formats results, and returns the response.
  case 'search_packages': { const validatedArgs = SearchPackagesSchema.parse(args); const packages = await searchPackages({ query: validatedArgs.query, kind: validatedArgs.kind, category: validatedArgs.category, limit: validatedArgs.limit, }); if (packages.length === 0) { return { content: [ { type: 'text', text: 'No packages found matching your search criteria.', }, ], }; } const formattedResults = packages.map(formatPackage).join('\n\n'); return { content: [ { type: 'text', text: `Found ${packages.length} package(s):\n\n${formattedResults}`, }, ], }; }
• src/scraper.ts:27-32 (schema)

  TypeScript interface defining the input options for the searchPackages function.
  export interface SearchOptions { query?: string; kind?: 'packages' | 'templates'; category?: string; limit?: number; }