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:

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

Method 2: Environment Variable

{
  "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:

{
  "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:

{
  "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):

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

Returns the current number of indexed entries and refresh status.

Configuration Examples

For React/Next.js Projects

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

For ASP.NET Core + React Projects

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

Absolute Path

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

How It Works

Discovery: On startup, recursively searches for translation files in folders named en
Indexing: Builds an in-memory search index of all translation keys and values
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:

npm install -g translations-mcp

Development

# 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

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

Alternative: Auto-Discovery

{
  "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

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

License

MIT