@espanol/mcp

@espanol/mcp

MCP adapter for DialectOS — provides 16 Model Context Protocol tools for Spanish dialect translation, i18n management, and documentation translation.

Installation

pnpm add @espanol/mcp

Quick Start

Add to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dialectos": {
      "command": "npx",
      "args": ["-y", "@espanol/mcp"],
      "env": {
        "ALLOWED_LOCALE_DIRS": "/path/to/your/locales"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "dialectos": {
      "command": "npx",
      "args": ["-y", "@espanol/mcp"],
      "env": {}
    }
  }
}

16 Available Tools

Markdown Translation (4 tools)

Tool	Description	Key Parameters
translate_markdown	Translate markdown preserving code blocks, links, tables	filePath, dialect?, provider?
extract_translatable	Extract translatable text from markdown	filePath
translate_api_docs	Translate API docs with table/list handling	filePath, dialect?, provider?
create_bilingual_doc	Create side-by-side bilingual document	filePath, dialect?, provider?

i18n Operations (6 tools)

Tool	Description	Key Parameters
detect_missing_keys	Compare locale files, find missing keys	basePath, targetPath
translate_missing_keys	Translate missing keys to target locale	basePath, targetPath, dialect?
batch_translate_locales	Batch translate to multiple dialects	directory, targets[]
manage_dialect_variants	Create dialect-specific variants	sourcePath, variant
check_formality	Check formality consistency	localePath, register?
apply_gender_neutral	Apply gender-neutral language	localePath, strategy?

Translation (6 tools)

Tool	Description	Key Parameters
translate_text	Translate text to Spanish dialect	text, dialect?, formal?
detect_dialect	Detect Spanish dialect from text	text
translate_code_comment	Translate code comments	code, dialect?
translate_readme	Translate README files	filePath, dialect?
search_glossary	Search built-in glossary (500+ terms)	query
list_dialects	List all 20 Spanish dialects	(none)

Configuration

Environment Variables

Variable	Description	Default
DEEPL_AUTH_KEY	DeepL API key	(none)
LIBRETRANSLATE_URL	LibreTranslate endpoint URL	(none)
ALLOWED_LOCALE_DIRS	Comma-separated allowed directories	process.cwd()
MYMEMORY_RATE_LIMIT	MyMemory provider requests/min	60
ESPANOL_RATE_LIMIT	Rate limit as max,windowMs	60,60000
ESPANOL_LOG_LEVEL	Logging level	error

Config File

espanol-mcp --config ./dialectos.config.json

{
  "rateLimit": { "maxRequests": 100, "windowMs": 60000 },
  "security": {
    "maxFileSize": 524288,
    "maxContentLength": 50000,
    "allowedDirs": ["/path/to/locales"]
  },
  "logging": { "level": "info" }
}

Security

• Path traversal protection on all file operations
• Symlink resolution via fs.realpathSync
• Content length validation (512KB files, 50KB content)
• Rate limiting (60 requests/minute default)
• Input sanitization (no null bytes, no control chars)
• Error message sanitization (no API keys, no stack traces)

Development

pnpm --filter @espanol/mcp test
pnpm --filter @espanol/mcp build