Weblate MCP Server

Instructions

Implementation Reference

• src/tools/changes.tool.ts:23-78 (handler)

  The primary handler function for the 'listRecentChanges' MCP tool. It invokes the WeblateApiService, handles empty results and errors, formats the changes using helper methods, and returns a structured MCP content response.

  async listRecentChanges({
    limit = 20,
    user,
    timestampAfter,
    timestampBefore,
  }: {
    limit?: number;
    user?: string;
    timestampAfter?: string;
    timestampBefore?: string;
  }) {
    try {
      const result = await this.weblateApiService.listRecentChanges(
        limit,
        user,
        timestampAfter,
        timestampBefore,
      );
  
      if (result.results.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No recent changes found.',
            },
          ],
        };
      }
  
      const changesList = result.results
        .slice(0, limit)
        .map(change => this.formatChangeResult(change))
        .join('\n\n---\n\n');
  
      return {
        content: [
          {
            type: 'text',
            text: `Found ${result.count} recent changes (showing ${Math.min(limit, result.results.length)}):\n\n${changesList}`,
          },
        ],
      };
    } catch (error) {
      this.logger.error('Failed to list recent changes', error);
      return {
        content: [
          {
            type: 'text',
            text: `Error listing recent changes: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/tools/changes.tool.ts:16-21 (schema)

  Zod schema defining the input parameters for the listRecentChanges tool: limit, user, timestampAfter, timestampBefore.

  parameters: z.object({
    limit: z.number().optional().describe('Number of changes to return (default: 20)').default(20),
    user: z.string().optional().describe('Filter by specific user'),
    timestampAfter: z.string().optional().describe('Show changes after this timestamp (ISO format)'),
    timestampBefore: z.string().optional().describe('Show changes before this timestamp (ISO format)'),
  }),

• src/tools/changes.tool.ts:13-22 (registration)

  @Tool decorator that registers the listRecentChanges function as an MCP tool, specifying name, description, and input schema.

  @Tool({
    name: 'listRecentChanges',
    description: 'List recent changes across all projects in Weblate',
    parameters: z.object({
      limit: z.number().optional().describe('Number of changes to return (default: 20)').default(20),
      user: z.string().optional().describe('Filter by specific user'),
      timestampAfter: z.string().optional().describe('Show changes after this timestamp (ISO format)'),
      timestampBefore: z.string().optional().describe('Show changes before this timestamp (ISO format)'),
    }),
  })

• src/tools/changes.tool.ts:247-254 (helper)

  Helper method to format a single Change object into a human-readable markdown string used in the tool response.

  private formatChangeResult(change: Change): string {
    const timestamp = change.timestamp ? new Date(change.timestamp).toLocaleString() : 'Unknown';
    const actionDescription = this.getActionDescription(change.action || 0);
    const user = change.user || 'Unknown user';
    const target = change.target || 'N/A';
    
    return `**${actionDescription}**\n**User:** ${user}\n**Time:** ${timestamp}\n**Target:** ${target}`;
  }

• src/tools/changes.tool.ts:256-308 (helper)

  Helper method that maps numeric action codes from Weblate changes to descriptive strings for display in tool output.

  private getActionDescription(action: number): string {
    const actionMap: Record<number, string> = {
      0: 'Resource updated',
      1: 'Translation completed',
      2: 'Translation changed',
      3: 'Comment added',
      4: 'Suggestion added',
      5: 'Translation added',
      6: 'Automatically translated',
      7: 'Suggestion accepted',
      8: 'Translation reverted',
      9: 'Translation uploaded',
      13: 'Source string added',
      14: 'Component locked',
      15: 'Component unlocked',
      17: 'Changes committed',
      18: 'Changes pushed',
      19: 'Repository reset',
      20: 'Repository merged',
      21: 'Repository rebased',
      22: 'Repository merge failed',
      23: 'Repository rebase failed',
      24: 'Parsing failed',
      25: 'Translation removed',
      26: 'Suggestion removed',
      27: 'Translation replaced',
      28: 'Repository push failed',
      29: 'Suggestion removed during clean-up',
      30: 'Source string changed',
      31: 'String added',
      32: 'Bulk status changed',
      33: 'Visibility changed',
      34: 'User added',
      35: 'User removed',
      36: 'Translation approved',
      37: 'Marked for edit',
      38: 'Component removed',
      39: 'Project removed',
      41: 'Project renamed',
      42: 'Component renamed',
      43: 'Moved component',
      45: 'Contributor joined',
      46: 'Announcement posted',
      47: 'Alert triggered',
      48: 'Language added',
      49: 'Language requested',
      50: 'Project created',
      51: 'Component created',
      52: 'User invited',
    };
    
    return actionMap[action] || `Unknown action (${action})`;
  }