Weblate MCP Server

Instructions

Implementation Reference

• src/tools/translations.tool.ts:391-446 (handler)

  The main handler function for the 'searchUnitsWithFilters' tool. It calls the WeblateApiService to perform the search and formats the results using a helper method.

  async searchUnitsWithFilters({
    projectSlug,
    componentSlug,
    languageCode,
    searchQuery,
    limit = 50,
  }: {
    projectSlug: string;
    componentSlug: string;
    languageCode: string;
    searchQuery: string;
    limit?: number;
  }) {
    try {
      const results = await this.weblateApiService.searchUnitsWithQuery(
        projectSlug,
        componentSlug,
        languageCode,
        searchQuery,
        Math.min(limit, 200), // Cap at 200 to prevent overwhelming responses
      );
  
      if (results.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No units found matching query "${searchQuery}" in ${projectSlug}/${componentSlug}/${languageCode}`,
            },
          ],
        };
      }
  
      const resultText = this.formatFilteredResults(results, projectSlug, componentSlug, languageCode, searchQuery);
      
      return {
        content: [
          {
            type: 'text',
            text: resultText,
          },
        ],
      };
    } catch (error) {
      this.logger.error('Failed to search units with filters', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error searching units: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/translations.tool.ts:380-390 (registration)

  Tool registration decorator including the name, description, and Zod input schema definition.

  @Tool({
    name: 'searchUnitsWithFilters',
    description: 'Search translation units using Weblate\'s powerful filtering syntax. Supports filters like: state:<translated (untranslated), state:>=translated (translated), component:NAME, source:TEXT, target:TEXT, has:suggestion, etc.',
    parameters: z.object({
      projectSlug: z.string().describe('The slug of the project'),
      componentSlug: z.string().describe('The slug of the component'),
      languageCode: z.string().describe('The language code (e.g., sk, cs, fr)'),
      searchQuery: z.string().describe('Weblate search query using their filter syntax. Examples: "state:<translated" (untranslated), "state:>=translated" (translated), "source:hello", "has:suggestion", "component:common AND state:<translated"'),
      limit: z.number().optional().default(50).describe('Maximum number of results to return (default: 50, max: 200)'),
    }),
  })

• src/tools/translations.tool.ts:383-389 (schema)

  Zod schema for input parameters of the tool.

  parameters: z.object({
    projectSlug: z.string().describe('The slug of the project'),
    componentSlug: z.string().describe('The slug of the component'),
    languageCode: z.string().describe('The language code (e.g., sk, cs, fr)'),
    searchQuery: z.string().describe('Weblate search query using their filter syntax. Examples: "state:<translated" (untranslated), "state:>=translated" (translated), "source:hello", "has:suggestion", "component:common AND state:<translated"'),
    limit: z.number().optional().default(50).describe('Maximum number of results to return (default: 50, max: 200)'),
  }),

• src/tools/translations.tool.ts:472-510 (helper)

  Helper method called by the handler to format the search results into a readable string.

    private formatFilteredResults(results: Unit[], projectSlug: string, componentSlug: string, languageCode: string, searchQuery: string): string {
      if (results.length === 0) {
        return `No units found in ${projectSlug}/${componentSlug}/${languageCode} matching query: ${searchQuery}`;
      }
  
      const formattedResults = results
        .slice(0, 50) // Limit to 50 for readability
        .map(unit => {
          const sourceText = unit.source && Array.isArray(unit.source) 
            ? unit.source.join('') 
            : (unit.source || '(empty)');
          const targetText = unit.target && Array.isArray(unit.target) 
            ? unit.target.join('') 
            : (unit.target || '(empty)');
  
          // Determine status based on state
          let status = '❓ Unknown';
          if (unit.state === 0) status = '❌ Untranslated';
          else if (unit.state === 10) status = '🔄 Needs Editing';
          else if (unit.state === 20) status = '✅ Translated';
          else if (unit.state === 30) status = '✅ Approved';
          else if (unit.state === 100) status = '🔒 Read-only';
  
          return `**Key:** ${unit.context || '(no context)'}
  **Source:** ${sourceText}
  **Target:** ${targetText}
  **Status:** ${status}
  **Location:** ${unit.location || '(none)'}
  **Note:** ${unit.note || '(none)'}
  **ID:** ${unit.id}`;
        })
        .join('\n\n');
  
      const totalText = results.length > 50
        ? `\n\n*Showing first 50 of ${results.length} units*`
        : '';
  
      return `Found ${results.length} units in ${projectSlug}/${componentSlug}/${languageCode} matching query "${searchQuery}":\n\n${formattedResults}${totalText}`;
    }