# Translations MCP Server

A Model Context Protocol (MCP) server that automatically discovers and searches translation files in your projects.

## Features

- **Configurable path**: Specify exact translation file path via configuration (recommended)
- **Auto-discovery**: Automatically finds translation files in `en` folders as fallback
- **Fast search**: Indexed search through translation keys and values
- **Partial/exact matching**: Support for both partial and exact match searches
- **File watching**: Automatically reloads when translation files change
- **Multiple file formats**: Supports common translation file names
- **TypeScript**: Fully typed with proper interfaces and modular architecture

## Quick Start

### Method 1: Configured Path (Recommended)

Configure your MCP server to use a specific translation file:

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["path/to/your/translation.json"]
    }
  }
}
```

### Method 2: Environment Variable

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "env": {
        "TRANSLATION_FILE_PATH": "src/assets/locales/en/translation.json"
      }
    }
  }
}
```

### Method 3: Auto-Discovery (Fallback)

If no path is configured, the server will automatically search for translation files:

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp"
    }
  }
}
```

## Architecture

The project is organized into focused modules for better maintainability:

```
src/
├── index.ts              # Main server entry point with MCP server setup
├── translation-discovery.ts # File discovery and search functionality
└── types.ts              # TypeScript interfaces and types
```

### Module Descriptions

- **`index.ts`**: Main MCP server setup, tool handlers, and entry point
- **`translation-discovery.ts`**: Handles file discovery, indexing, and search functionality
- **`types.ts`**: TypeScript interfaces for type safety across modules

## Usage

The server provides two main tools:

### 1. find_translation

Search for translation keys and values:

```json
{
  "name": "find_translation",
  "arguments": {
    "query": "search term",
    "exact": false
  }
}
```

- `query`: String to search for in translation keys or values
- `exact`: Boolean (optional) - whether to perform exact matching (default: false)

### 2. refresh_translations

Manually refresh the translation index (useful after file changes):

```json
{
  "name": "refresh_translations",
  "arguments": {}
}
```

Returns the current number of indexed entries and refresh status.

## Configuration Examples

### For React/Next.js Projects

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["public/locales/en/translation.json"]
    }
  }
}
```

### For ASP.NET Core + React Projects

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["ClientApp/public/locales/en/translation.json"]
    }
  }
}
```

### Absolute Path

```json
{
  "mcpServers": {
    "translations-mcp": {
      "command": "translations-mcp",
      "args": ["C:/projects/my-app/locales/en/translation.json"]
    }
  }
}
```

## How It Works

1. **Discovery**: On startup, recursively searches for translation files in folders named `en`
2. **Indexing**: Builds an in-memory search index of all translation keys and values
3. **Search**: Provides fast lookups with support for partial and exact matching

### Supported Project Structures

The server can find translation files in various project structures:

- `./en/translation.json` (simple)
- `./locales/en/translation.json` (common)
- `./src/assets/locales/en/translation.json` (React/Angular)
- `./ClientApp/public/locales/en/translation.json` (ASP.NET Core with React)
- `./Project.Name/ClientApp/public/locales/en/translation.json` (deep .NET structures)

## Installation

Install globally via npm:

```bash
npm install -g translations-mcp
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Development mode
npm run dev
```

## Testing

The project includes several test scripts:

- `npm run test:server` - Test basic server functionality
- `npm run test:find` - Test search functionality
- `npm run test:quick` - Quick integration test
- `npm run test:all` - Run all tests

## Supported File Names

The server looks for these translation files in `en` folders:

- translation.json
- translations.json
- common.json
- messages.json

## Adding to Claude Desktop

### Recommended: Specify Your Translation File Path

```json
{
  "mcpServers": {
    "translations": {
      "command": "translations-mcp",
      "args": ["path/to/your/translation.json"]
    }
  }
}
```

### Alternative: Auto-Discovery

```json
{
  "mcpServers": {
    "translations": {
      "command": "translations-mcp"
    }
  }
}
```

## Benefits of Configured Path

✅ **Eliminates confusion** - No more loading wrong translation files  
✅ **Faster startup** - No need to search directories  
✅ **Predictable behavior** - Always uses the exact file you specify  
✅ **Works anywhere** - Not limited to specific folder structures  
✅ **Production ready** - Points to your actual translation files, not test data

- `npm run clean` - Remove compiled files
- `npm test` - Run the main server functionality test
- `npm run test:server` - Run comprehensive server tests with response parsing
- `npm run test:quick` - Run quick global installation test
- `npm run test:all` - Run all tests (server + quick)

### Development Workflow

1. Clone or download this package
2. Run `npm install` to install dependencies
3. Make your changes to files in the `src/` directory
4. Test with `npm run dev` for development or `npm test` to verify functionality
5. Build for production with `npm run build && npm start`

## License

MIT