# Weblate MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides seamless integration with Weblate translation management platform. This server enables AI assistants to interact directly with your Weblate instance for comprehensive translation management.

## 🌟 Features

- **🔧 Complete Weblate API Access**: Full integration with Weblate's REST API
- **🤖 AI-Powered Workflow**: Natural language interaction with your translation projects
- **📊 Project Management**: Create, list, and manage translation projects
- **🔍 Component Operations**: Handle translation components and configurations
- **✏️ Translation Management**: Update, search, and manage translations
- **🌐 Language Support**: Work with all supported languages in your Weblate instance
- **🚀 Multiple Transports**: HTTP/SSE, Streamable HTTP, and STDIO support
- **🛡️ Type Safety**: Full TypeScript implementation with comprehensive error handling
- **⚡ LLM-Optimized**: Tools designed to guide AI models toward efficient usage patterns

## 🎯 What is This?

This MCP server acts as a bridge between AI assistants (like Claude Desktop) and your Weblate translation management platform. Instead of manually navigating the Weblate web interface, you can use natural language to:

- **"List all projects in my Weblate instance"**
- **"Show me the French translations for the frontend component"**
- **"Update the welcome message translation"**
- **"Create a new translation project"**

## 🚀 Quick Start

### Option 1: Use with npx (Recommended)

The easiest way to use this MCP server is with npx - no installation required!

**For Claude Desktop or other MCP clients:**
```json
{
  "mcpServers": {
    "weblate": {
      "command": "npx",
      "args": ["-y", "@mmntm/weblate-mcp"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-weblate-api-token"
      }
    }
  }
}
```

**Manual testing:**
```bash
# Test the server directly
npx @mmntm/weblate-mcp
```

### Option 2: Development Setup

### Prerequisites
- Node.js 18+
- pnpm package manager
- Weblate instance with API access

### Installation
```bash
# Clone and install
git clone <this-repo>
cd weblate-mcp
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your Weblate API URL and token

# Build and start
pnpm build
pnpm start
```

Server runs on `http://localhost:3001` by default.

### Environment Configuration
```env
WEBLATE_API_URL=https://your-weblate-instance.com
WEBLATE_API_TOKEN=your-api-token-here
PORT=3001
NODE_ENV=production
LOG_LEVEL=info
```

## 🔗 MCP Client Configuration

### Claude Desktop (npx method - Recommended)
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "weblate": {
      "command": "npx",
      "args": ["-y", "@mmntm/weblate-mcp"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-weblate-api-token"
      }
    }
  }
}
```

### Claude Desktop (Development/Local)
For development or local builds:
```json
{
  "mcpServers": {
    "weblate": {
      "command": "node",
      "args": ["/path/to/weblate-mcp/dist/main.js"],
      "env": {
        "WEBLATE_API_URL": "https://your-weblate-instance.com/api",
        "WEBLATE_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### HTTP Clients (Cursor, VS Code, Web Apps)
```json
{
  "transport": "http",
  "url": "http://localhost:3001/mcp"
}
```

## 🛠️ Available Tools

### 📊 Project Management
| Tool | Description |
|------|-------------|
| **`listProjects`** | List all available Weblate projects with URLs and metadata |

### 🔧 Component Management
| Tool | Description |
|------|-------------|
| **`listComponents`** | List components in a specific project with source language details |

### ✏️ Translation Management
| Tool | Description |
|------|-------------|
| **`searchUnitsWithFilters`** ⭐ | **Efficient search using Weblate's native filtering syntax** |
| **`searchStringInProject`** | Search for translations containing specific text in a project |
| **`getTranslationForKey`** | Get translation value for a specific key |
| **`writeTranslation`** | Update or write translation values with approval support |
| **`bulkWriteTranslations`** ⚡ | **Batch update multiple translations efficiently with error handling** |
| **`findTranslationsForKey`** | Find all translations for a specific key across languages |

#### 🚀 Why searchUnitsWithFilters is Recommended

The `searchUnitsWithFilters` tool uses Weblate's native filtering syntax, making it the most efficient way to find translations:

- **❌ Inefficient**: Getting all keys then checking each one individually (can make thousands of API calls)
- **✅ Efficient**: Single filtered search using Weblate's query syntax

**Example efficient queries:**
- `state:=0` - Find untranslated strings
- `state:=10` - Find strings that need editing  
- `source:"login"` - Find strings containing "login"
- `component:common AND state:=0` - Complex filters

### 🌐 Language Management
| Tool | Description |
|------|-------------|
| **`listLanguages`** | List languages available in a specific project |

### 📊 Translation Statistics Dashboard
| Tool | Description |
|------|-------------|
| **`getProjectStatistics`** | Comprehensive project statistics with completion rates and string counts |
| **`getComponentStatistics`** | Detailed statistics for a specific component |
| **`getProjectDashboard`** | Complete dashboard overview with all component statistics |
| **`getTranslationStatistics`** | Statistics for specific translation (project/component/language) |
| **`getComponentLanguageProgress`** | Translation progress for all languages in a component with progress bars |
| **`getLanguageStatistics`** | Statistics for a language across all projects |
| **`getUserStatistics`** | User contribution statistics and activity metrics |

### 📈 Change Tracking & History
| Tool | Description |
|------|-------------|
| **`listRecentChanges`** | Recent changes across all projects with user and timestamp filtering |
| **`getProjectChanges`** | Recent changes for a specific project |
| **`getComponentChanges`** | Recent changes for a specific component |
| **`getChangesByUser`** | Recent changes by a specific user |

## 💡 Usage Examples

### Project Operations
```typescript
// List all projects
await list_projects();

// Get specific project details
await get_project({ slug: "my-project" });

// Create a new project
await create_project({
  name: "New Project",
  slug: "new-project",
  web: "https://example.com"
});
```

### Translation Operations
```typescript
// List translations for a component
await list_translations({
  project_slug: "my-project",
  component_slug: "frontend"
});

// Get specific translation
await get_translation({
  project_slug: "my-project",
  component_slug: "frontend",
  language_code: "fr"
});

// Update translations
await update_translation({
  project_slug: "my-project",
  component_slug: "frontend",
  language_code: "fr",
  translations: {
    "welcome": "Bienvenue",
    "goodbye": "Au revoir"
  }
});
```

## 📚 Documentation

| Document | Description |
|----------|-------------|
| **[📖 Documentation Hub](./docs/README.md)** | Complete documentation overview and quick start |
| **[🚀 Installation & Setup](./docs/MCP_SETUP.md)** | Installation, configuration, and Claude Desktop setup |
| **[📋 API Reference](./docs/API.md)** | Complete API documentation with examples |
| **[🛠️ Development Guide](./docs/DEVELOPMENT.md)** | Contributing, development setup, and testing |
| **[🏗️ Architecture](./docs/ARCHITECTURE.md)** | Codebase structure, patterns, and design decisions |
| **[📦 Release Process](./docs/RELEASE.md)** | Release management and publishing workflow |
| **[🔄 Changesets Guide](./docs/CHANGESETS.md)** | Version management with changesets |

## 🏗️ Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  Weblate MCP     │───▶│  Weblate API    │
│  (IDE/Editor)   │    │     Server       │    │   (REST API)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │   MCP Tools      │
                       │ • Projects       │
                       │ • Components     │
                       │ • Translations   │
                       │ • Languages      │
                       └──────────────────┘
```

**Technology Stack:**
- **NestJS**: Modern Node.js framework with dependency injection
- **TypeScript**: Full type safety and IntelliSense support
- **Weblate REST API**: Comprehensive API wrapper with interfaces
- **MCP Protocol**: Standard Model Context Protocol implementation
- **Axios**: HTTP client for API communication

## 🧪 Development

### Development Setup
```bash
# Start development server with hot reload
pnpm run dev

# Run tests
pnpm test

# Run end-to-end tests
pnpm run test:e2e

# Generate test coverage
pnpm run test:cov

# Build for production
pnpm build
```

### Adding New Tools
1. Create tool file in `src/tools/`
2. Implement MCP tool interface
3. Add to service providers
4. Write tests
5. Update documentation

See [Development Guide](./docs/DEVELOPMENT.md) for detailed instructions.

## 🎯 Use Cases

### Translation Management
- **Project oversight**: Monitor translation progress across projects
- **Content updates**: Update translations programmatically
- **Quality assurance**: Review and approve translations
- **Team coordination**: Manage translation workflows

### Development Integration
- **CI/CD pipelines**: Automate translation updates in deployment
- **Content management**: Sync translations with content systems
- **Localization testing**: Validate translations in different contexts
- **Documentation**: Generate translation reports and statistics

### AI-Assisted Workflows
- **Natural language queries**: Ask about translation status in plain English
- **Contextual operations**: AI understands your translation needs
- **Batch operations**: Perform bulk updates with AI assistance
- **Smart suggestions**: Get AI-powered translation recommendations

## 🔒 Security & Production

- **API Token Security**: Store tokens securely, use environment variables
- **Rate Limiting**: Built-in request throttling and retry logic
- **Error Handling**: Comprehensive error responses with debugging info
- **Input Validation**: All inputs validated with Zod schemas
- **HTTPS Support**: Secure communication with Weblate instances

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](./docs/DEVELOPMENT.md#contributing):

1. **Fork** the repository
2. **Create** a feature branch from main
3. **Implement** changes with tests
4. **Update** documentation
5. **Submit** a pull request

### Code Style
- Use TypeScript for type safety
- Follow NestJS conventions
- Add comprehensive tests
- Update documentation

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details.

## 🙏 Acknowledgments

- **Weblate**: For providing an excellent translation management platform
- **Model Context Protocol**: For the standardized protocol specification
- **NestJS**: For the robust application framework
- **Contributors**: Everyone who helps improve this project

---

**Built with ❤️ for the translation community**

*Need help? Check our [documentation](./docs/) or create an [issue](https://github.com/mmntm/weblate-mcp/issues)!*