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

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:

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

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