Typst Universe MCP Server

Instructions

Implementation Reference

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

  Core handler function that performs web scraping on Typst Universe to search for packages based on query, kind, category, and limit.

  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:83-88 (schema)

  Zod validation schema for input parameters of 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:22-49 (registration)

  MCP Tool object registration defining name, description, and JSON input schema for search_packages.

  {
      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:173-202 (registration)

  Dispatch handler in MCP CallToolRequestSchema that validates args, calls searchPackages, formats results, and returns 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 input options for the searchPackages function.

  export interface SearchOptions {
      query?: string;
      kind?: 'packages' | 'templates';
      category?: string;
      limit?: number;
  }