feat(manifest): replace and expand manifest with detailed tooling and prompts

Update the manifest with an extensively detailed description, expanded tool
and prompt definitions, and refined configuration fields to enhance the AI-
powered localization assistant capabilities.

- Replace the previous manifest with a fully enriched one listing 59 tools
  across 11 domains, detailed usage descriptions, and 38 well-defined prompts.
- Enhance user configuration options and environment variable mappings for
  improved flexibility and clarity.
- Provide comprehensive long descriptions and examples to improve user
  understanding of the capabilities.
- Refine tool descriptions to include required, optional arguments, and return
  data, aiding better usability.
- Adjust compatibility and runtime versions to align with updates.
- Modify related code to improve tool extraction, allowing multiline and
  escaped strings parsing for accurate manifest generation.
- Enrich tool registration descriptions with detailed usage, inputs, and outputs.

These changes significantly improve the manifest's clarity, completeness, and
usability, laying groundwork for advanced conversational workflows in the Lokalise
MCP project.

Author: AbdallahAHO

.dxtignore

@@ -0,0 +1,46 @@
+# Development files
+.cursor/
+.claude/
+.vscode/
+.idea/
+*.log
+*.tmp
+.DS_Store
+.env
+.env.*
+
+# Test files
+coverage/
+*.test.ts
+*.test.js
+__tests__/
+__mocks__/
+__snapshots__/
+__fixtures__/
+vitest.config.ts
+
+# Documentation and development guides
+*.md
+!README.md
+!LICENSE
+
+# CI/CD
+.github/
+.releaserc.json
+
+# Build artifacts
+*.tgz
+release/
+certs/
+
+# Development config
+.nvmrc
+.node-version
+biome.json
+tsconfig.json
+.gitignore
+.dxtignore
+
+# Misc
+.git/
+node_modules/

.npmignore

@@ -14,7 +14,10 @@ coverage/
 *.test.ts
 *.test.js
 __tests__/
-jest.config.js
+__mocks__/
+__snapshots__/
+__fixtures__/
+vitest.config.ts
 
 # Documentation and development guides
 *.md

manifest.json

@@ -32,19 +32,31 @@ async function extractToolsFromFile(filePath) {
 		const content = await readFile(filePath, "utf-8");
 		const tools = [];
 
-		// Match server.tool() calls with better multiline support
-		// This regex captures the tool name and the full description string
-		const toolRegex =
-			/server\.tool\(\s*["'`]([^"'`]+)["'`]\s*,\s*["'`]((?:[^"'`\\]|\\.)*)["'`]/gs;
+		// Find all server.tool() calls and parse their arguments properly
+		const toolCallRegex = /server\.tool\(\s*/g;
 		let match;
 
-		// biome-ignore lint/suspicious/noAssignInExpressions: YOLO
-		while ((match = toolRegex.exec(content)) !== null) {
-			const name = match[1] ? match[1].trim() : "";
-			const description = match[2] ? match[2].trim() : "";
+		// biome-ignore lint/suspicious/noAssignInExpressions: Need to iterate through matches
+		while ((match = toolCallRegex.exec(content)) !== null) {
+			const startIndex = match.index + match[0].length;
+
+			// Parse the first argument (tool name)
+			const nameResult = parseStringLiteral(content, startIndex);
+			if (!nameResult) continue;
+
+			// Skip comma and whitespace
+			let nextIndex = nameResult.endIndex;
+			while (nextIndex < content.length && /[\s,]/.test(content[nextIndex])) {
+				nextIndex++;
+			}
+
+			// Parse the second argument (description)
+			const descResult = parseStringLiteral(content, nextIndex);
+			if (!descResult) continue;
+
 			tools.push({
-				name,
-				description,
+				name: nameResult.value,
+				description: descResult.value,
 			});
 		}
 
@@ -55,6 +67,69 @@ async function extractToolsFromFile(filePath) {
 	}
 }
 
+/**
+ * Parse a string literal from the given position, handling escape sequences properly
+ */
+function parseStringLiteral(content, startIndex) {
+	if (startIndex >= content.length) return null;
+
+	const quote = content[startIndex];
+	if (quote !== '"' && quote !== "'" && quote !== "`") return null;
+
+	let i = startIndex + 1;
+	let value = "";
+
+	while (i < content.length) {
+		const char = content[i];
+
+		if (char === quote) {
+			// Found closing quote
+			return { value, endIndex: i + 1 };
+		}
+
+		if (char === "\\") {
+			// Handle escape sequence
+			i++;
+			if (i < content.length) {
+				const escaped = content[i];
+				switch (escaped) {
+					case "n":
+						value += "\n";
+						break;
+					case "t":
+						value += "\t";
+						break;
+					case "r":
+						value += "\r";
+						break;
+					case "\\":
+						value += "\\";
+						break;
+					case '"':
+						value += '"';
+						break;
+					case "'":
+						value += "'";
+						break;
+					case "`":
+						value += "`";
+						break;
+					default:
+						value += escaped;
+						break;
+				}
+			}
+		} else {
+			value += char;
+		}
+
+		i++;
+	}
+
+	// Unclosed string
+	return null;
+}
+
 /**
  * Discover all domain tool files
  */
@@ -333,6 +408,19 @@ async function generateManifest() {
 		manifest.repository = packageJson.repository;
 	}
 
+	// Preserve manually crafted display_name and description if they exist and are custom
+	if (!manifest.display_name || manifest.display_name === "Lokalise MCP") {
+		manifest.display_name = "Lokalise MCP";
+	}
+
+	if (
+		!manifest.description ||
+		manifest.description.includes("Manage 59 tools across 11 domains")
+	) {
+		manifest.description =
+			"Transform Lokalise into your conversational AI assistant. Manage tools across domains with natural language - from project creation to translation workflows, team management to bulk operations. Stop clicking, start commanding.";
+	}
+
 	// Discover and extract tools
 	console.log(chalk.yellow("📂 Discovering domain tools..."));
 	const toolFiles = await discoverToolFiles();
@@ -362,15 +450,24 @@ async function generateManifest() {
 	manifest.tools = allTools;
 	manifest.tools_generated = true;
 
-	// Generate long description
-	console.log(chalk.yellow("📝 Generating long description..."));
-	manifest.long_description = generateLongDescription(allTools, domainCounts);
+	// Only generate long description if it doesn't exist or is the old auto-generated format
+	if (
+		!manifest.long_description ||
+		manifest.long_description.includes(
+			"Transform Your Localization Workflow with Conversational AI",
+		)
+	) {
+		console.log(chalk.yellow("📝 Generating long description..."));
+		manifest.long_description = generateLongDescription(allTools, domainCounts);
+	} else {
+		console.log(chalk.gray("📝 Preserving existing long description..."));
+	}
 
 	// Extract prompts (if implemented)
 	const prompts = await extractPrompts();
 	if (prompts.length > 0) {
 		manifest.prompts = prompts;
-		manifest.prompts_generated = false; // Set to true when auto-generation is implemented
+		manifest.prompts_generated = true; // Set to true when auto-generation is implemented
 	}
 
 	// Write the manifest

scripts/generate-manifest.js

@@ -107,14 +107,14 @@ function registerTools(server: McpServer) {
 
 	server.tool(
 		"lokalise_list_queued_processes",
-		"Lists all background/async processes in a Lokalise project with status tracking",
+		"Lists all background/async processes in a Lokalise project with status tracking. Required: projectId. Optional: limit (100), page. Use to monitor file uploads, downloads, bulk operations, or troubleshoot process issues. Returns: Processes with status, progress, and completion estimates.",
 		ListQueuedprocessesToolArgs.shape,
 		handleListQueuedprocesses,
 	);
 
 	server.tool(
 		"lokalise_get_queued_process",
-		"Gets detailed status and information about a specific async process (upload, download, etc.)",
+		"Gets detailed status and information about a specific async process (upload, download, etc.). Required: projectId, processId. Use to check process completion, diagnose failures, or get detailed progress information. Returns: Complete process details with logs and status history.",
 		GetQueuedprocessesToolArgs.shape,
 		handleGetQueuedprocesses,
 	);

src/domains/queuedprocesses/queuedprocesses.tool.ts

@@ -168,15 +168,24 @@ export class DomainRegistry {
 			});
 			return module;
 		} catch (error) {
-			methodLogger.error(`Failed to load domain ${name}`, { error });
+			const errorMessage =
+				error instanceof Error ? error.message : String(error);
+			const errorStack = error instanceof Error ? error.stack : undefined;
+
+			methodLogger.error(`Failed to load domain ${name}`, {
+				error: errorMessage,
+				stack: errorStack,
+				indexPath: join(this.domainsPath, name, "index.js"),
+				name,
+			});
 
 			// Update registry with error
 			this.registryMap.set(name, {
 				name,
 				path: join(this.domainsPath, name),
 				module: {},
 				loaded: false,
-				error: error instanceof Error ? error.message : String(error),
+				error: errorMessage,
 			});
 
 			return null;

src/domains/registry.ts

@@ -180,28 +180,28 @@ function registerTools(server: McpServer) {
 
 	server.tool(
 		"lokalise_list_team_users",
-		"Lists all users in a Lokalise team with pagination support",
+		"Lists all users in a Lokalise team with pagination support. Required: teamId. Optional: limit (100), page. Use to audit team composition, check access levels, or prepare team changes. Returns: Users with roles, permissions, and activity status.",
 		ListTeamusersToolArgs.shape,
 		handleListTeamusers,
 	);
 
 	server.tool(
 		"lokalise_get_team_user",
-		"Gets detailed information about a specific user in a team",
+		"Gets detailed information about a specific user in a team. Required: teamId, userId. Use to verify user permissions, check role assignments, or investigate access issues. Returns: Complete user profile with all team permissions and administrative rights.",
 		GetTeamusersToolArgs.shape,
 		handleGetTeamusers,
 	);
 
 	server.tool(
 		"lokalise_update_team_user",
-		"Updates a team user's role (owner, admin, member, or biller)",
+		"Updates a team user's role (owner, admin, member, or biller). Required: teamId, userId, role. Use to manage permissions, promote/demote, or adjust access levels. Returns: Updated user profile with new role and permissions.",
 		UpdateTeamusersToolArgs.shape,
 		handleUpdateTeamusers,
 	);
 
 	server.tool(
 		"lokalise_delete_team_user",
-		"Removes a user from a Lokalise team",
+		"Removes a user from a Lokalise team. Required: teamId, userId. Use to remove members, clean up permissions, or manage team structure. Returns: Success message with user details.",
 		DeleteTeamusersToolArgs.shape,
 		handleDeleteTeamusers,
 	);

src/domains/teamusers/teamusers.tool.ts

@@ -317,63 +317,63 @@ function registerTools(server: McpServer) {
 
 	server.tool(
 		"lokalise_list_usergroups",
-		"Lists all user groups in a Lokalise team with pagination support",
+		"Lists all user groups in a Lokalise team with pagination support. Required: teamId. Optional: limit (100), page. Use to audit team organization, check group structure, or prepare group management operations. Returns: User groups with names, member counts, permissions, and language assignments. Essential for understanding team hierarchy.",
 		ListUsergroupsToolArgs.shape,
 		handleListUsergroups,
 	);
 
 	server.tool(
 		"lokalise_get_usergroup",
-		"Gets detailed information about a specific user group",
+		"Gets detailed information about a specific user group including members, permissions, and project assignments. Required: teamId, groupId. Use to audit group configuration, verify member access, or understand permission structure. Returns: Complete group profile with admin rights, language permissions, and assigned projects/members.",
 		GetUsergroupsToolArgs.shape,
 		handleGetUsergroups,
 	);
 
 	server.tool(
 		"lokalise_create_usergroup",
-		"Creates a new user group in a Lokalise team",
+		"Creates a new user group in a Lokalise team for organized permission management. Required: teamId, name, isReviewer, isAdmin. Optional: adminRights, languages, projects, members. Use to establish role-based access control, organize team permissions, or set up project-specific groups. Returns: Created group with assigned ID and configuration.",
 		CreateUsergroupsToolArgs.shape,
 		handleCreateUsergroups,
 	);
 
 	server.tool(
 		"lokalise_update_usergroup",
-		"Updates a user group's properties",
+		"Updates a user group's properties including permissions and assignments. Required: teamId, groupId, name, isReviewer, isAdmin. Optional: adminRights, languages. Use to adjust group permissions, modify access levels, or reorganize team structure. Returns: Updated group configuration. Note: Cannot modify projects/members here - use dedicated tools.",
 		UpdateUsergroupsToolArgs.shape,
 		handleUpdateUsergroups,
 	);
 
 	server.tool(
 		"lokalise_delete_usergroup",
-		"Deletes a user group from a Lokalise team",
+		"Deletes a user group from a Lokalise team, removing all associated permissions. Required: teamId, groupId. Use for cleanup, removing obsolete groups, or restructuring team organization. Returns: Deletion confirmation. Warning: Removes all group assignments - members lose group-based permissions immediately.",
 		DeleteUsergroupsToolArgs.shape,
 		handleDeleteUsergroups,
 	);
 
 	server.tool(
 		"lokalise_add_members_to_group",
-		"Adds users to a user group",
+		"Adds users to a user group, granting them group-based permissions and project access. Required: teamId, groupId, userIds array. Use to onboard team members, assign role-based access, or batch permission updates. Returns: Operation confirmation. Members immediately gain group permissions and project access.",
 		AddMembersToolArgs.shape,
 		handleAddMembers,
 	);
 
 	server.tool(
 		"lokalise_remove_members_from_group",
-		"Removes users from a user group",
+		"Removes users from a user group, revoking group-based permissions and project access. Required: teamId, groupId, userIds array. Use for role changes, offboarding, or permission cleanup. Returns: Operation confirmation. Warning: Immediate effect - users lose group permissions and project access.",
 		RemoveMembersToolArgs.shape,
 		handleRemoveMembers,
 	);
 
 	server.tool(
 		"lokalise_add_projects_to_group",
-		"Adds projects to a user group",
+		"Adds projects to a user group, granting all group members access to specified projects. Required: teamId, groupId, projectIds array. Use to expand group project scope, onboard projects to existing teams, or batch project assignments. Returns: Operation confirmation. All group members gain immediate project access.",
 		AddProjectsToolArgs.shape,
 		handleAddProjects,
 	);
 
 	server.tool(
 		"lokalise_remove_projects_from_group",
-		"Removes projects from a user group",
+		"Removes projects from a user group, revoking group member access to specified projects. Required: teamId, groupId, projectIds array. Use to limit project scope, offboard projects, or restructure access. Returns: Operation confirmation. Warning: All group members lose immediate project access.",
 		RemoveProjectsToolArgs.shape,
 		handleRemoveProjects,
 	);

src/domains/usergroups/usergroups.tool.ts

@@ -1,5 +1,4 @@
 // Shared utilities exports
-export * from "./cli.test.util.js";
 export * from "./config.util.js";
 export * from "./constants.util.js";
 export * from "./error.util.js";

src/shared/utils/index.ts

@@ -113,5 +113,13 @@
 		"skipLibCheck": true /* Skip type checking all .d.ts files. */
 	},
 	"include": ["src/**/*"],
-	"exclude": ["**/__fixtures__/**/*", "**/*.test.ts"]
+	"exclude": [
+		"**/__fixtures__/**/*",
+		"**/*.test.ts",
+		"**/*.test.js",
+		"**/test-utils/**/*",
+		"**/scripts/**/*",
+		"**/__mocks__/**/*",
+		"**/__snapshots__/**/*"
+	]
 }