feat(mcp): tools de idiomas y traducciones
- Nueva categoria tools/languages: list_web_languages, get_record_translations y set_record_translations (registros, config, textos_generales y vars de modulo via builder_custom). - Param lang opcional en list_table_records y get_record (options.translates de CocoDB). - Docs actualizados (03/04/06/09/11b + ACAI_ENDPOINTS) con el modelo de cms_traducciones y los workflows de traduccion.
This commit is contained in:
Jordan Diaz
74
mcp-server/tools/languages/getRecordTranslations.js
Normal file
74
mcp-server/tools/languages/getRecordTranslations.js
Normal file
@@ -0,0 +1,74 @@
|
||||
import { z } from "zod";
|
||||
import { withAuth, getSessionCredentials } from "../../auth/index.js";
|
||||
import { handleToolError, validateRequired, handleApiResponse } from "../helpers/errorHandler.js";
|
||||
import { AcaiHttpClient } from "../helpers/acaiHttpClient.js";
|
||||
import { withAuthParams } from "../helpers/authSchema.js";
|
||||
|
||||
export function registerGetRecordTranslationsTool(server) {
|
||||
server.tool(
|
||||
"get_record_translations",
|
||||
`Read the stored translations for one or more records of a table, from the central cms_traducciones table.
|
||||
|
||||
Translations are keyed by (prefix = language code, tableName without 'cms_', fieldName, recordNum). Values are stored Base64 in the DB but this tool returns them already decoded (plain text). An absent field/prefix means there is no translation and the base-language value is used at runtime.
|
||||
|
||||
Params:
|
||||
- tableName: table name WITHOUT the 'cms_' prefix (e.g. 'apartados', 'productos', 'builder_custom', 'textos_generales').
|
||||
- recordNums: array of record 'num' primary keys to read.
|
||||
- fields (optional): only return these field names. Omit to return every translated field found.
|
||||
- prefix (optional): only return translations for this language prefix (e.g. 'en'). Omit to return all languages.
|
||||
|
||||
Returns translations shaped as { "<recordNum>": { "<prefix>": { "<fieldName>": "<value>" } } }.
|
||||
|
||||
To translate module vars, first call get_module_config_vars to obtain varsMeta ({ fieldName, recordNum } per var) and read from tableName='builder_custom'. For template literals, read tableName='textos_generales' field 'texto'.`,
|
||||
withAuthParams({
|
||||
tableName: z.string().describe("Table name without 'cms_' prefix (e.g. 'apartados', 'builder_custom', 'textos_generales')"),
|
||||
recordNums: z.array(z.number()).describe("Array of record 'num' primary keys to read translations for"),
|
||||
fields: z.array(z.string()).optional().describe("Only return these field names. Omit to return all translated fields."),
|
||||
prefix: z.string().optional().describe("Only return translations for this language prefix (e.g. 'en'). Omit for all languages."),
|
||||
}),
|
||||
{ readOnlyHint: true, destructiveHint: false },
|
||||
withAuth(async ({ tableName, recordNums, fields, prefix }, extra) => {
|
||||
try {
|
||||
const validationError = validateRequired(
|
||||
{ tableName, recordNums },
|
||||
["tableName", "recordNums"],
|
||||
"get_record_translations"
|
||||
);
|
||||
if (validationError) return validationError;
|
||||
|
||||
const credentials = await getSessionCredentials(extra.sessionId);
|
||||
|
||||
const payload = { tableName, recordNums };
|
||||
if (fields && fields.length > 0) payload.fields = fields;
|
||||
if (prefix) payload.prefix = prefix;
|
||||
|
||||
const response = await AcaiHttpClient.postViewerAction(
|
||||
credentials,
|
||||
"getTranslations",
|
||||
payload,
|
||||
credentials.token,
|
||||
credentials.tokenHash,
|
||||
{},
|
||||
15000
|
||||
);
|
||||
|
||||
const apiError = handleApiResponse(response.data, "get_record_translations");
|
||||
if (apiError) return apiError;
|
||||
|
||||
return {
|
||||
content: [{
|
||||
type: "text",
|
||||
text: JSON.stringify({
|
||||
success: true,
|
||||
action: "get_record_translations",
|
||||
tableName: response.data?.tableName || tableName,
|
||||
translations: response.data?.translations || {},
|
||||
}, null, 2)
|
||||
}],
|
||||
};
|
||||
} catch (error) {
|
||||
return handleToolError(error, "get_record_translations", { tableName, recordNums });
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
9
mcp-server/tools/languages/index.js
Normal file
9
mcp-server/tools/languages/index.js
Normal file
@@ -0,0 +1,9 @@
|
||||
import { registerListWebLanguagesTool } from './listWebLanguages.js';
|
||||
import { registerGetRecordTranslationsTool } from './getRecordTranslations.js';
|
||||
import { registerSetRecordTranslationsTool } from './setRecordTranslations.js';
|
||||
|
||||
export function registerLanguageTools(server) {
|
||||
registerListWebLanguagesTool(server);
|
||||
registerGetRecordTranslationsTool(server);
|
||||
registerSetRecordTranslationsTool(server);
|
||||
}
|
||||
54
mcp-server/tools/languages/listWebLanguages.js
Normal file
54
mcp-server/tools/languages/listWebLanguages.js
Normal file
@@ -0,0 +1,54 @@
|
||||
import { withAuth, getSessionCredentials } from "../../auth/index.js";
|
||||
import { handleToolError, handleApiResponse } from "../helpers/errorHandler.js";
|
||||
import { AcaiHttpClient } from "../helpers/acaiHttpClient.js";
|
||||
import { withAuthParams } from "../helpers/authSchema.js";
|
||||
|
||||
export function registerListWebLanguagesTool(server) {
|
||||
server.tool(
|
||||
"list_web_languages",
|
||||
`List the active languages configured for the current website (from settings.dat.php [idiomas]).
|
||||
|
||||
Returns an array of languages, each with:
|
||||
- name: internal code (e.g. 'espanol')
|
||||
- label: human label
|
||||
- prefix: the translation prefix stored in cms_traducciones. The prefix "www" is the BASE language (its URLs have NO path prefix). Any other prefix (e.g. "en") is a secondary language served under /<urlPrefix>/...
|
||||
- urlPrefix: the URL path segment for that language ('' for the base language, e.g. 'en' otherwise)
|
||||
- isDefault: true for the base language
|
||||
|
||||
Also returns defaultLanguage. Use the prefix values here when calling get_record_translations / set_record_translations.`,
|
||||
withAuthParams({}),
|
||||
{ readOnlyHint: true, destructiveHint: false },
|
||||
withAuth(async (_args, extra) => {
|
||||
try {
|
||||
const credentials = await getSessionCredentials(extra.sessionId);
|
||||
|
||||
const response = await AcaiHttpClient.postViewerAction(
|
||||
credentials,
|
||||
"getLanguages",
|
||||
{},
|
||||
credentials.token,
|
||||
credentials.tokenHash,
|
||||
{},
|
||||
15000
|
||||
);
|
||||
|
||||
const apiError = handleApiResponse(response.data, "list_web_languages");
|
||||
if (apiError) return apiError;
|
||||
|
||||
return {
|
||||
content: [{
|
||||
type: "text",
|
||||
text: JSON.stringify({
|
||||
success: true,
|
||||
action: "list_web_languages",
|
||||
languages: response.data?.languages || [],
|
||||
defaultLanguage: response.data?.defaultLanguage,
|
||||
}, null, 2)
|
||||
}],
|
||||
};
|
||||
} catch (error) {
|
||||
return handleToolError(error, "list_web_languages");
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
79
mcp-server/tools/languages/setRecordTranslations.js
Normal file
79
mcp-server/tools/languages/setRecordTranslations.js
Normal file
@@ -0,0 +1,79 @@
|
||||
import { z } from "zod";
|
||||
import { withAuth, getSessionCredentials } from "../../auth/index.js";
|
||||
import { handleToolError, validateRequired, handleApiResponse } from "../helpers/errorHandler.js";
|
||||
import { AcaiHttpClient } from "../helpers/acaiHttpClient.js";
|
||||
import { withAuthParams } from "../helpers/authSchema.js";
|
||||
|
||||
export function registerSetRecordTranslationsTool(server) {
|
||||
server.tool(
|
||||
"set_record_translations",
|
||||
`Write translations for a single record + language into the central cms_traducciones table. Values are stored Base64 automatically (transparent — pass plain text). Only translatable field types can be translated: textfield, textbox, wysiwyg, codigo and multitext.
|
||||
|
||||
Four usage scenarios:
|
||||
1. Normal records — translate the visible text fields of any content table. tableName without 'cms_', recordNum = the record 'num', fields = { fieldName: translatedText }.
|
||||
2. configuracion / configuracion_tienda — the global settings tables are ordinary records; translate their text fields the same way (locate the row with list_table_records).
|
||||
3. textos_generales — the template literals used by the Twig '| translate' filter are normal records: translate their 'texto' field. Find the right num by 'identificador' with list_table_records first (tableName='textos_generales', fields={ texto: '...' }).
|
||||
4. Module vars — the textual values of a module live in the 'builder_custom' table. Call get_module_config_vars to get varsMeta ({ fieldName, recordNum } per var, and per item for multi vars), then set tableName='builder_custom', recordNum + fields={ <fieldName>: translatedText } from varsMeta.
|
||||
|
||||
Rules:
|
||||
- An EMPTY STRING ('') as a value DELETES that translation (falls back to base language at runtime).
|
||||
- The 'enlace' field is NEVER translated by hand — the CocoEnlace engine maintains it; the PHP rejects it.
|
||||
- multitext fields are translated as the full serialized JSON string in a single row (translate the whole JSON value, not individual items).
|
||||
- prefix is the language code from list_web_languages (e.g. 'en'); do NOT write to prefix 'www' (base language is edited via normal record fields, not translations).
|
||||
|
||||
Params:
|
||||
- tableName (string) without 'cms_' prefix.
|
||||
- recordNum (number) the record 'num' primary key.
|
||||
- prefix (string) target language prefix (e.g. 'en').
|
||||
- fields (object) { fieldName: translatedValue } map. '' deletes.`,
|
||||
withAuthParams({
|
||||
tableName: z.string().describe("Table name without 'cms_' prefix (e.g. 'apartados', 'builder_custom', 'textos_generales')"),
|
||||
recordNum: z.number().describe("Record 'num' primary key to translate"),
|
||||
prefix: z.string().describe("Target language prefix from list_web_languages (e.g. 'en'). Never 'www' (base language)."),
|
||||
fields: z.record(z.string()).describe("Map { fieldName: translatedValue }. Empty string '' deletes the translation. 'enlace' is forbidden."),
|
||||
}),
|
||||
{ readOnlyHint: false, destructiveHint: false },
|
||||
withAuth(async ({ tableName, recordNum, prefix, fields }, extra) => {
|
||||
try {
|
||||
const validationError = validateRequired(
|
||||
{ tableName, recordNum, prefix, fields },
|
||||
["tableName", "recordNum", "prefix", "fields"],
|
||||
"set_record_translations"
|
||||
);
|
||||
if (validationError) return validationError;
|
||||
|
||||
const credentials = await getSessionCredentials(extra.sessionId);
|
||||
|
||||
const response = await AcaiHttpClient.postViewerAction(
|
||||
credentials,
|
||||
"setTranslations",
|
||||
{ tableName, recordNum, prefix, fields },
|
||||
credentials.token,
|
||||
credentials.tokenHash,
|
||||
{},
|
||||
15000
|
||||
);
|
||||
|
||||
const apiError = handleApiResponse(response.data, "set_record_translations");
|
||||
if (apiError) return apiError;
|
||||
|
||||
return {
|
||||
content: [{
|
||||
type: "text",
|
||||
text: JSON.stringify({
|
||||
success: true,
|
||||
action: "set_record_translations",
|
||||
tableName,
|
||||
recordNum,
|
||||
prefix,
|
||||
updated: response.data?.updated,
|
||||
deleted: response.data?.deleted,
|
||||
}, null, 2)
|
||||
}],
|
||||
};
|
||||
} catch (error) {
|
||||
return handleToolError(error, "set_record_translations", { tableName, recordNum, prefix });
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user