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:

Method 2: Environment Variable

Method 3: Auto-Discovery (Fallback)

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

Architecture

The project is organized into focused modules for better maintainability:

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:

• 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):

Returns the current number of indexed entries and refresh status.

Configuration Examples

For React/Next.js Projects

For ASP.NET Core + React Projects

Absolute Path

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:

Development

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

Alternative: Auto-Discovery

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