Weblate MCP Server

# Development Guide This guide will help you set up the development environment and contribute to the Weblate MCP Server project. ## 🛠️ Prerequisites Before you begin, ensure you have the following installed: - **Node.js** (v18 or higher) - **pnpm** (recommended package manager) - **Git** ## 🚀 Getting Started ### 1. Clone the Repository ```bash git clone https://github.com/mmntm/weblate-mcp.git cd weblate-mcp ``` ### 2. Install Dependencies ```bash pnpm install ``` ### 3. Environment Setup Copy the example environment file and configure it: ```bash cp env.example .env ``` Edit `.env` with your Weblate instance details: ```env WEBLATE_API_URL=https://your-weblate-instance.com/api/ WEBLATE_API_TOKEN=your-api-token PORT=3000 NODE_ENV=development ``` ### 4. Build the Project ```bash pnpm run build ``` ### 5. Start Development Server ```bash pnpm run dev ``` The server will start in watch mode and automatically restart when you make changes. ## 🏗️ Project Structure ``` weblate-mcp/ ├── src/ │ ├── services/weblate/ # Weblate API services │ │ ├── base-weblate.service.ts # Base HTTP client │ │ ├── projects.service.ts # Project operations │ │ ├── components.service.ts # Component operations │ │ ├── translations.service.ts # Translation operations │ │ └── languages.service.ts # Language operations │ ├── tools/ # MCP tool implementations │ ├── types/ # TypeScript type definitions │ │ └── weblate.types.ts # Weblate API types │ ├── app.module.ts # NestJS application module │ └── main.ts # Application entry point ├── docs/ # Documentation ├── examples/ # Usage examples ├── dist/ # Compiled output └── test/ # Test files ``` ## 🧪 Testing ### Running Tests ```bash # Run all tests pnpm test # Run tests in watch mode pnpm run test:watch # Run tests with coverage pnpm run test:cov # Run e2e tests pnpm run test:e2e ``` ### Writing Tests - Unit tests should be placed alongside the source files with `.spec.ts` extension - E2E tests go in the `test/` directory - Use Jest for testing framework - Mock external dependencies appropriately Example test structure: ```typescript import { Test, TestingModule } from '@nestjs/testing'; import { ProjectsService } from './projects.service'; describe('ProjectsService', () => { let service: ProjectsService; beforeEach(async () => { const module: TestingModule = await Test.createTestingModule({ providers: [ProjectsService], }).compile(); service = module.get<ProjectsService>(ProjectsService); }); it('should be defined', () => { expect(service).toBeDefined(); }); }); ``` ## 🔧 Development Scripts | Script | Description | |--------|-------------| | `pnpm run build` | Build the project | | `pnpm run dev` | Start development server with watch mode | | `pnpm run start` | Start production server | | `pnpm run test` | Run tests | | `pnpm run test:watch` | Run tests in watch mode | | `pnpm run test:cov` | Run tests with coverage | | `pnpm run format` | Format code with Prettier | ## 📝 Code Style ### TypeScript Guidelines - Use TypeScript strict mode - Define proper interfaces for all data structures - Use meaningful variable and function names - Add JSDoc comments for public APIs ### Formatting - Use Prettier for code formatting - Run `pnpm run format` before committing - Configure your editor to format on save ### Linting - Follow ESLint rules defined in `.eslintrc.js` - Fix linting errors before committing ## 🏛️ Architecture Patterns ### Service Layer Architecture The project uses a modular service architecture: 1. **Base Service** (`BaseWeblateService`): Handles HTTP client configuration and common functionality 2. **Specialized Services**: Inherit from base service and implement specific API operations 3. **Composition**: Main `WeblateApiService` composes all specialized services ### Dependency Injection - Use NestJS dependency injection container - Register services in `app.module.ts` - Use constructor injection for dependencies ### Error Handling - Use structured error handling with proper HTTP status codes - Log errors appropriately for debugging - Return meaningful error messages to users ## 🔄 Making Changes ### 1. Create a Feature Branch ```bash git checkout -b feature/your-feature-name ``` ### 2. Make Your Changes - Follow the coding standards - Add tests for new functionality - Update documentation if needed ### 3. Test Your Changes ```bash pnpm run test pnpm run build ``` ### 4. Create a Changeset For any user-facing changes, create a changeset: ```bash pnpm changeset ``` Follow the prompts to describe your changes. ### 5. Commit and Push ```bash git add . git commit -m "feat: add new feature" git push origin feature/your-feature-name ``` ### 6. Create a Pull Request - Create a PR against the `main` branch - Provide a clear description of your changes - Link any related issues ## 🚀 Release Process The project uses automated releases with Changesets: 1. Changes are merged to `main` 2. GitHub Actions runs CI/CD pipeline 3. If changesets exist, a release PR is created 4. Merging the release PR publishes to npm See [Release Process](./RELEASE.md) for detailed information. ## 🐛 Debugging ### Local Development 1. Set `NODE_ENV=development` in your `.env` file 2. Use `console.log` or debugger statements 3. Check the server logs for errors ### MCP Integration Testing Since the server runs in development mode, you can test changes immediately: 1. Make code changes 2. The server will restart automatically 3. Test with your MCP client (Claude Desktop) 4. Check logs for any issues ### Common Issues - **Port conflicts**: Change the `PORT` in `.env` - **API authentication**: Verify your Weblate API token - **Build errors**: Check TypeScript compilation errors ## 📚 Additional Resources - [NestJS Documentation](https://docs.nestjs.com/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [Weblate API Documentation](https://docs.weblate.org/en/latest/api.html) - [TypeScript Handbook](https://www.typescriptlang.org/docs/) ## 🤝 Getting Help If you need help: 1. Check existing [GitHub Issues](https://github.com/mmntm/weblate-mcp/issues) 2. Create a new issue with detailed information 3. Join discussions in the repository ## 📋 Checklist for Contributors Before submitting a PR, ensure: - [ ] Code follows the style guidelines - [ ] Tests pass (`pnpm test`) - [ ] Build succeeds (`pnpm run build`) - [ ] Documentation is updated if needed - [ ] Changeset is created for user-facing changes - [ ] PR description is clear and complete