# 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
