# 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