feat: add CLAUDE.md for project guidance, update dependencies and add glossaries support (#17)

* feat: add CLAUDE.md for project guidance and update dependencies

- Introduced CLAUDE.md to provide comprehensive guidance on the Lara Translate MCP Server, including setup, development commands, architecture, and error handling.
- Updated @translated/lara dependency version from 1.4.0 to 1.7.3 in package.json and pnpm-lock.yaml.
- Added new tools for glossary management: list_glossaries and get_glossary, along with corresponding tests.
- Enhanced translate tool to support glossaries, no_trace, priority, and timeout_in_millis parameters.

* refactor: update documentation and enhance error handling in MCP tools

- Updated CLAUDE.md to reflect changes in transport modes and environment variable requirements.
- Added a security note in README.md regarding API credentials in HTTP mode.
- Enhanced error handling in MCP tools to provide clearer validation messages and prevent exposure of technical details.
- Added additional validation rules for glossary IDs and timeout parameters in the translate tool.
- Improved logging for privacy-sensitive translation requests.

* fix: copilot comments

* fix: copilot review

* fix: claude.md specs

Author: CristianBelli01k

.gitignore

@@ -21,6 +21,9 @@ out/
 # Env
 .env
 
+# Claude Code local settings
+.claude/settings.local.json
+
 # mpeltonen/sbt-idea plugin
 .idea_modules/
 

CLAUDE.md

@@ -0,0 +1,160 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Lara Translate MCP Server is a Model Context Protocol (MCP) server that provides translation capabilities through the Lara Translate API. The server supports both STDIO and HTTP transport modes.
+
+## Development Commands
+
+### Setup
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm run build
+```
+
+### Development
+```bash
+# Run in development mode with hot reload
+pnpm run dev
+
+# Start the built server
+pnpm run start
+```
+
+### Testing
+```bash
+# Run all tests once
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run tests with coverage report
+pnpm test:coverage
+```
+
+### Docker Development
+```bash
+# Build Docker image
+docker build -t lara-mcp .
+```
+
+## Architecture
+
+### Server Modes
+
+The server operates in two transport modes determined by the `TRANSPORT` environment variable:
+
+1. **STDIO Mode** (`src/index.ts:56-75`): Direct MCP server using stdio transport, requires `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables.
+
+2. **HTTP Mode** (`src/index.ts:42-54`): REST API server with MCP protocol endpoint at `/v1`
+
+### Core Components
+
+#### MCP Server (`src/mcp/server.ts`)
+
+The server factory function `getMcpServer(accessKeyId, accessKeySecret)` creates an MCP server instance with:
+- `accessKeyId`: The Lara Translate API access key ID
+- `accessKeySecret`: The Lara Translate API access key secret
+
+The server initializes a `Translator` instance from the `@translated/lara` SDK and configures MCP request handlers for tools and resources.
+
+#### Tools (`src/mcp/tools/`)
+
+All MCP tools are organized in individual files under `src/mcp/tools/`:
+
+**Translation Tools:**
+- `translate.ts` - Main translation with context, instructions, memory support, and glossaries
+  - Advanced options: `glossaries` (array of glossary IDs, max 10), `no_trace` (privacy flag), `priority` (normal/background), `timeout_in_millis` (max 300000ms)
+  - Validation includes format checks for glossary IDs (`gls_*` pattern) and timeout limits
+
+**Glossary Management Tools:**
+- `list_glossaries.ts` - List all glossaries
+- `get_glossary.ts` - Get glossary by ID (returns null if not found)
+  - Validates glossary ID format with regex `/^gls_[a-zA-Z0-9_-]+$/`
+
+**Memory Management Tools:**
+- `list_memories.ts` - List all translation memories
+- `create_memory.ts` - Create new memory (supports MyMemory import via `external_id`)
+- `update_memory.tool.ts` - Update memory name
+- `delete_memory.ts` - Delete memory
+- `add_translation.ts` - Add translation unit to memory
+- `delete_translation.ts` - Remove translation unit from memory
+- `import_tmx.ts` - Import TMX file (supports gzip compression)
+- `check_import_status.ts` - Check TMX import job status
+
+**Language Support:**
+- `list_languages.ts` - List supported languages
+
+Each tool exports a handler function and a Zod validation schema. Tool registration happens in `src/mcp/tools.ts` which maintains two handler maps:
+- `handlers` - Tools with arguments (e.g., translate, create_memory)
+- `listers` - Tools without arguments (e.g., list_memories, list_languages)
+
+#### Resources (`src/mcp/resources.ts`)
+
+The MCP server exposes translation memories as resources:
+- Resource URI format: `memory://{memoryId}`
+- Resource template: `memory://{memoryId}` for listing memories
+
+### Path Aliases
+
+The project uses path aliases (configured in `tsconfig.json` and `package.json` imports):
+- `#env` → `src/env.js`
+- `#exception` → `src/exception.js`
+- `#logger` → `src/logger.js`
+- `#rest/server` → `src/rest/server.js`
+- `#mcp/server` → `src/mcp/server.js`
+
+### Environment Variables
+
+Core configuration (`src/env.ts`):
+- `TRANSPORT` - Server mode: `stdio` or `http` (default: `stdio`)
+- `HOST` / `PORT` - HTTP server binding (default: `0.0.0.0:3000`)
+- `LARA_ACCESS_KEY_ID` / `LARA_ACCESS_KEY_SECRET` - API credentials (required for STDIO mode)
+- `LOGGING_LEVEL` - Log level: `debug`, `info`, `warn`, `error` (default: `info`)
+
+### Error Handling
+
+Custom exception classes (`src/exception.ts`):
+- `ServerException` - Base exception with error code
+- `InvalidInputError` - Invalid request parameters (code: -32600)
+- `InvalidCredentialsError` - Authentication failure (code: -32600)
+- `MethodNotAllowedError` - HTTP method not allowed (code: -32601)
+
+Error handling in `src/mcp/tools.ts`:
+- Zod validation errors return specific field names (not full error details for security)
+- Existing `InvalidInputError` instances are preserved and re-thrown
+- Other unexpected errors are logged internally and returned as generic "An error occurred while processing your request" message
+- Privacy-sensitive translations (with `no_trace=true`) are logged for audit purposes
+
+### Logging
+
+The server uses Pino structured logging (`src/logger.ts`). Log level is controlled by `LOGGING_LEVEL` environment variable.
+
+## Testing
+
+Tests are located in `src/__tests__/` and mirror the source structure:
+- `tools/` - Individual tool tests (71 total tests)
+- `server/` - REST server tests
+- `utils/mocks.ts` - Shared test utilities with Vitest mocks
+
+Tests use Vitest with coverage reporting (v8 provider).
+
+## Security Features
+
+- **Input validation**: All glossary IDs validated with regex, timeout capped at 300000ms, max 10 glossaries per request
+- **Error sanitization**: Zod errors filtered to show only field names, SDK errors hidden behind generic messages
+- **Audit logging**: Privacy-sensitive requests (no_trace=true) logged for compliance
+- **Credential protection**: Access key ID never logged in debug mode
+
+## Important Notes
+
+- When adding new tools, update both the handler in `src/mcp/tools/{tool}.ts` and register it in `src/mcp/tools.ts`.
+- All file imports must use the `.js` extension even though source files are `.ts` (ES module resolution requirement).
+- The `translate` tool builds options object dynamically - only includes non-empty arrays and defined values to avoid passing `undefined` to SDK.
+- Semicolons are consistently used throughout the codebase.

README.md

@@ -82,10 +82,33 @@ Lara also lowers the cost of using models like GPT-4 in non-English workflows. S
 - `context` (optional string): Additional context to improve translation quality
 - `instructions` (optional string[]): Instructions to adjust translation behavior
 - `source_hint` (optional string): Guidance for language detection
+- `glossaries` (optional string[]): Array of glossary IDs to enforce terminology (e.g., ['gls_xyz123'])
+- `no_trace` (optional boolean): Privacy flag - if true, request won't be traced/logged
+- `priority` (optional string): Translation priority - 'normal' or 'background'
+- `timeout_in_millis` (optional number): Custom timeout in milliseconds
 
 **Returns**: Translated text blocks maintaining the original structure
 </details>
 
+### Glossaries Tools
+
+<details>
+<summary><strong>list_glossaries</strong> - List all glossaries</summary>
+
+**Inputs**: None
+
+**Returns**: Array of glossaries with their details (id, name, createdAt, updatedAt, ownerId)
+</details>
+
+<details>
+<summary><strong>get_glossary</strong> - Get a specific glossary by ID</summary>
+
+**Inputs**:
+- `id` (string): The glossary ID (e.g., 'gls_xyz123')
+
+**Returns**: Glossary object or null if not found
+</details>
+
 ### Translation Memories Tools
 
 <details>
@@ -181,6 +204,18 @@ Lara supports both the STDIO and streamable HTTP protocols. For a hassle-free se
 
 You'll find setup instructions for both protocols in the sections below.
 
+## ⚠️ Security Note
+
+**Important:** When running your own HTTP server instance (not using the remote `https://mcp.laratranslate.com/v1`), all connected clients share the same Lara API credentials configured via `LARA_ACCESS_KEY_ID` and `LARA_ACCESS_KEY_SECRET` environment variables.
+
+This server is designed for:
+- ✅ Single-user deployments
+- ✅ Trusted-environment deployments (e.g., internal tools)
+
+For multi-tenant scenarios, either:
+- Use the remote server at `https://mcp.laratranslate.com/v1` where each client provides their own credentials via headers
+- Deploy separate MCP server instances per user with isolated credentials
+
 ### HTTP Server 🌐
 <details>
 <summary><strong>❌ Clients NOT supporting <code>url</code> configuration (e.g., Claude, OpenAI)</strong></summary>

package.json

@@ -52,7 +52,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.3",
-    "@translated/lara": "^1.4.0",
+    "@translated/lara": "^1.7.3",
     "cors": "^2.8.5",
     "express": "^5.1.0",
     "helmet": "^8.1.0",

pnpm-lock.yaml

@@ -0,0 +1,63 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { getGlossary, getGlossarySchema } from '../../mcp/tools/get_glossary.js';
+import { getMockTranslator, setupTranslatorMock, type MockTranslator } from '../utils/mocks.js';
+import { Translator } from '@translated/lara';
+
+// Setup mocks
+setupTranslatorMock();
+
+describe('getGlossarySchema', () => {
+  it('should validate correct input', () => {
+    expect(() => getGlossarySchema.parse({ id: 'gls_xyz123' })).not.toThrow();
+  });
+
+  it('should reject missing id', () => {
+    expect(() => getGlossarySchema.parse({})).toThrow();
+  });
+
+  it('should reject empty glossary ID', () => {
+    expect(() => getGlossarySchema.parse({ id: '' })).toThrow();
+  });
+
+  it('should reject very long glossary ID', () => {
+    const longId = 'gls_' + 'a'.repeat(300);
+    expect(() => getGlossarySchema.parse({ id: longId })).toThrow();
+  });
+
+  it('should reject invalid glossary ID format', () => {
+    expect(() => getGlossarySchema.parse({ id: 'invalid-id' })).toThrow();
+  });
+});
+
+describe('getGlossary', () => {
+  let mockTranslator: MockTranslator;
+
+  beforeEach(() => {
+    mockTranslator = getMockTranslator();
+  });
+
+  it('should call lara.glossaries.get with correct id', async () => {
+    const mockGlossary = {
+      id: 'gls_xyz123',
+      name: 'Test Glossary',
+      createdAt: 1234567890,
+      updatedAt: 1234567890,
+      ownerId: 'user1'
+    };
+
+    mockTranslator.glossaries.get.mockResolvedValue(mockGlossary);
+
+    const result = await getGlossary({ id: 'gls_xyz123' }, mockTranslator as any as Translator);
+
+    expect(mockTranslator.glossaries.get).toHaveBeenCalledWith('gls_xyz123');
+    expect(result).toEqual(mockGlossary);
+  });
+
+  it('should return null for non-existent glossary', async () => {
+    mockTranslator.glossaries.get.mockResolvedValue(null);
+
+    const result = await getGlossary({ id: 'gls_nonexistent' }, mockTranslator as any as Translator);
+
+    expect(result).toBeNull();
+  });
+});

src/__tests__/tools/get_glossary.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { listGlossaries, listGlossariesSchema } from '../../mcp/tools/list_glossaries.js';
+import { getMockTranslator, setupTranslatorMock, type MockTranslator } from '../utils/mocks.js';
+import { Translator } from '@translated/lara';
+
+// Setup mocks
+setupTranslatorMock();
+
+describe('listGlossariesSchema', () => {
+  it('should validate empty object', () => {
+    expect(() => listGlossariesSchema.parse({})).not.toThrow();
+  });
+});
+
+describe('listGlossaries', () => {
+  let mockTranslator: MockTranslator;
+
+  beforeEach(() => {
+    mockTranslator = getMockTranslator();
+  });
+
+  it('should call lara.glossaries.list and return the result', async () => {
+    const mockGlossariesList = [
+      { id: 'gls_xyz123', name: 'glossary1', createdAt: 1234567890, updatedAt: 1234567890, ownerId: 'user1' },
+      { id: 'gls_abc456', name: 'glossary2', createdAt: 1234567890, updatedAt: 1234567890, ownerId: 'user1' }
+    ];
+
+    mockTranslator.glossaries.list.mockResolvedValue(mockGlossariesList);
+
+    const result = await listGlossaries(mockTranslator as any as Translator);
+
+    expect(mockTranslator.glossaries.list).toHaveBeenCalled();
+    expect(result).toEqual(mockGlossariesList);
+  });
+});