@fractalizer/mcp-core 0.1.0

package/README.md

@@ -0,0 +1,398 @@
+# @fractalizer/mcp-core
+
+**Core framework for building MCP tools: base classes, utilities, registry**
+
+[![npm version](https://img.shields.io/npm/v/@fractalizer/mcp-core.svg)](https://www.npmjs.com/package/@fractalizer/mcp-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🎯 Purpose
+
+**Principle:** Core provides reusable base classes and utilities for building MCP tools
+
+**Generic Design:** `BaseTool<TFacade>` is facade-agnostic — works with any API facade
+
+**Architecture rule:** Core depends ONLY on `@fractalizer/mcp-infrastructure`
+
+---
+
+## ⚠️ Scope Restrictions
+
+Этот пакет содержит **ТОЛЬКО** инфраструктуру для MCP tools:
+
+| ✅ Входит в scope | ❌ НЕ входит в scope |
+|-------------------|---------------------|
+| `BaseTool` и связанные типы | HTTP клиенты → `@fractalizer/mcp-infrastructure` |
+| `ToolRegistry` и фильтрация | CLI логика → `@fractalizer/mcp-cli` |
+| Schema → Definition генерация | Поиск tools → `@fractalizer/mcp-search` |
+| Утилиты для результатов tools | Бизнес-логика серверов → `packages/servers/*` |
+| Общие Zod-схемы для tools | Logging, caching → `@fractalizer/mcp-infrastructure` |
+
+**Правило:** Если функционал не связан напрямую с созданием/регистрацией/выполнением MCP tools — ему здесь не место
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @fractalizer/mcp-core
+```
+
+**Dependencies:**
+- `@fractalizer/mcp-infrastructure` (HTTP, logging, config)
+- `@modelcontextprotocol/sdk` (MCP protocol)
+- `zod` (validation)
+
+---
+
+## 📁 Structure
+
+```
+src/
+├── definition/                       # Schema-to-Definition generation
+│   ├── schema-to-definition.ts      # Auto-generate definitions from Zod
+│   ├── definition-validator.ts      # ToolDefinition validation
+│   └── zod-json-schema-adapter.ts   # Zod → JSON Schema converter
+├── tool-registry/                    # Tool registration and filtering
+│   ├── tool-registry.ts             # Tool registration and routing
+│   ├── tool-filter.service.ts       # Category/subcategory filtering
+│   ├── tool-sorter.ts               # Priority-based sorting
+│   └── types.ts                     # Registry types
+├── tools/
+│   ├── base/                         # Base classes for tools
+│   │   ├── base-tool.ts             # Generic BaseTool<TSchema>
+│   │   └── tool-metadata.ts         # StaticToolMetadata interface
+│   └── common/                       # Common utilities
+│       ├── schemas/                 # Reusable Zod schemas
+│       └── utils/                   # Tool utilities
+├── utils/                            # General utilities
+│   ├── response-field-filter.ts     # Filter response fields
+│   ├── batch-result-processor.ts    # Process batch results
+│   └── result-logger.ts             # Log tool results
+└── index.ts                          # Public exports
+```
+
+---
+
+## 🔧 Core Components
+
+### BaseTool<TFacade>
+
+**Generic base class** for creating MCP tools that work with any API facade.
+
+**Key features:**
+- ✅ Generic `<TFacade>` — facade-agnostic design
+- ✅ Automatic parameter validation (Zod schemas via `getParamsSchema()`)
+- ✅ Auto-generates MCP definitions from schema (DRY principle)
+- ✅ Built-in logging, error handling
+- ✅ Integration with ToolRegistry
+
+**Implementation:** [src/tools/base/base-tool.ts](src/tools/base/base-tool.ts)
+
+**Abstract interface:**
+```typescript
+abstract class BaseTool<TFacade = unknown> {
+  static readonly METADATA: StaticToolMetadata; // Required!
+
+  constructor(facade: TFacade, logger: Logger);
+
+  getDefinition(): ToolDefinition;  // Auto-generated from schema
+  getParamsSchema?(): ZodSchema;    // Optional: enables auto-generation
+  abstract execute(params: unknown): Promise<ToolResult>;
+}
+```
+
+**Reference implementation:** See any tool in `packages/servers/yandex-tracker/src/tools/api/` (e.g., `issues/get/get-issues.tool.ts`)
+
+### generateDefinitionFromSchema()
+
+**✅ Auto-generates MCP definitions from Zod schemas** (eliminates schema-definition mismatch)
+
+**Key features:**
+- ✅ Single source of truth (Zod schema with `.describe()`)
+- ✅ Uses Zod v4 native `schema.toJSONSchema()` API
+- ✅ Automatic required/optional field detection
+- ✅ Physically impossible to create schema ↔ definition mismatch
+
+**Implementation:** [src/definition/schema-to-definition.ts](src/definition/schema-to-definition.ts)
+
+**Function signature:**
+```typescript
+function generateDefinitionFromSchema(
+  schema: ZodSchema,
+  options?: { includeDescriptions?: boolean }
+): JSONSchema7
+```
+
+**Benefits:** DRY principle, type-safe, no separate `*.definition.ts` files
+
+**Migration guide:** [../../ARCHITECTURE.md](../../ARCHITECTURE.md) → "Schema-to-Definition Generator"
+
+---
+
+### BaseDefinition (Deprecated)
+
+**⚠️ Deprecated** in v2.0 — use `generateDefinitionFromSchema()` instead.
+
+**Problem with old approach:** Manual sync between Zod validation schema and MCP definition → frequent mismatch bugs.
+
+---
+
+### ToolRegistry
+
+**Tool registration and routing** — maps tool names to handlers, provides filtering and sorting.
+
+**Key features:**
+- ✅ Lazy initialization (tools created on-demand via DI container)
+- ✅ **Priority-based sorting:** critical → high → normal → low
+- ✅ **Category filtering** (via `ToolFilterService`)
+- ✅ Type-safe tool registration
+- ✅ Error handling for unknown tools
+
+**Implementation:** [src/tool-registry/tool-registry.ts](src/tool-registry/tool-registry.ts)
+
+**Class signature:**
+```typescript
+class ToolRegistry {
+  constructor(
+    container: Container,
+    logger: Logger,
+    toolClasses: ReadonlyArray<ToolClass>,
+    filterService?: ToolFilterService
+  );
+
+  getDefinitions(): ToolDefinition[];  // Filtered & sorted
+  executeToolByName(name: string, params: ToolCallParams): Promise<ToolResult>;
+}
+```
+
+---
+
+## 🛠️ Utilities
+
+### ResponseFieldFilter
+
+**Filter response fields** to reduce token usage (80-90% savings).
+
+**Usage:**
+```typescript
+import { ResponseFieldFilter } from '@fractalizer/mcp-core';
+
+const data = {
+  id: '123',
+  name: 'Item',
+  description: 'Long description...',
+  metadata: { /* ... */ },
+};
+
+// Filter to specific fields
+const filtered = ResponseFieldFilter.filter(data, ['id', 'name']);
+// Result: { id: '123', name: 'Item' }
+
+// No fields specified = return all
+const all = ResponseFieldFilter.filter(data);
+// Result: full data object
+```
+
+### BatchResultProcessor
+
+**Process batch operation results** (fulfilled + rejected).
+
+**Usage:**
+```typescript
+import { BatchResultProcessor } from '@fractalizer/mcp-core';
+
+const results: BatchResult<string, Item> = [
+  { status: 'fulfilled', value: { id: '1', name: 'Item 1' } },
+  { status: 'rejected', reason: new Error('Not found') },
+];
+
+// Separate successful and failed
+const { successful, failed } = BatchResultProcessor.separateResults(results);
+
+// Format for response
+const formatted = BatchResultProcessor.formatBatchResponse(
+  successful,
+  failed,
+  'items'
+);
+// Result: { items: [...], errors: [...] }
+```
+
+### ResultLogger
+
+**Log tool execution results** with structured output.
+
+**Usage:**
+```typescript
+import { ResultLogger } from '@fractalizer/mcp-core';
+
+// Log successful result
+ResultLogger.logSuccess(logger, 'get_item', result, { itemId: '123' });
+
+// Log error
+ResultLogger.logError(logger, 'get_item', error, { itemId: '123' });
+```
+
+---
+
+## 🚨 Critical Rules
+
+### 1. BaseTool is generic — facade-agnostic
+
+```typescript
+// ✅ CORRECT (generic facade)
+class MyTool extends BaseTool<MyApiFacade> {
+  async execute(params: Params) {
+    // Use this.facade (type: MyApiFacade)
+    return this.facade.someMethod();
+  }
+}
+
+// ❌ WRONG (hardcoded facade type in BaseTool)
+class BaseTool {
+  constructor(private facade: SpecificFacade) {} // BAD!
+}
+```
+
+### 2. Always validate params with Zod
+
+```typescript
+// ✅ CORRECT
+const validated = this.validateParams(ParamsSchema, params);
+
+// ❌ WRONG (no validation)
+const id = params.id; // Unsafe!
+```
+
+### 3. Use METADATA for tool discovery
+
+```typescript
+// ✅ CORRECT — Extended metadata with categorization
+static readonly METADATA: ToolMetadata = {
+  name: 'my_tool',
+  description: '[Category/Action] Brief description',
+  category: 'api',              // REQUIRED
+  subcategory: 'read',          // Optional (read/write/workflow)
+  priority: 'critical',         // Optional (critical/high/normal/low)
+  tags: ['tag1', 'tag2'],       // Optional (for search)
+  requiresExplicitUserConsent: false, // or true for write operations
+  inputSchema: {...}
+};
+
+// ❌ WRONG (missing required category)
+static readonly METADATA = {
+  name: 'my_tool',
+  description: 'Tool description',
+  // Missing category — will fail type check
+};
+```
+
+**Tool Categorization & Priority:**
+
+**Priority levels** (for sorting in tools/list):
+- `critical` — Frequently used, key operations (shown first)
+- `high` — Important but not critical
+- `normal` — Regular operations (default)
+- `low` — Rarely used, debug tools (shown last)
+
+**Tools are sorted:** critical → high → normal → low → alphabetically
+
+**Description convention:** `[Category/Subcategory] Brief description`
+- Keep descriptions concise (≤80 chars)
+- Use category prefix for structure
+- Details go in inputSchema parameter descriptions
+
+**Example:**
+```typescript
+static readonly METADATA: ToolMetadata = {
+  name: 'create_issue',
+  description: '[Issues/Write] Create new issue',
+  category: 'issues',
+  subcategory: 'write',
+  priority: 'critical',
+  tags: ['create', 'new', 'write', 'issue'],
+  inputSchema: {...}
+};
+```
+
+### 4. Filter fields before returning
+
+```typescript
+// ✅ CORRECT (filter to save tokens)
+const filtered = ResponseFieldFilter.filter(data, params.fields);
+return { content: [{ type: 'text', text: JSON.stringify(filtered) }] };
+
+// ❌ WRONG (return everything)
+return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+```
+
+---
+
+## 📖 API Reference
+
+### Exports
+
+```typescript
+// Base classes
+export { BaseTool } from './tools/base/base-tool.js';
+export { BaseDefinition } from './tools/base/base-definition.js';
+export type { StaticToolMetadata } from './tools/base/tool-metadata.js';
+
+// Utilities
+export { ResponseFieldFilter } from './utils/response-field-filter.js';
+export { BatchResultProcessor } from './utils/batch-result-processor.js';
+export { ResultLogger } from './utils/result-logger.js';
+
+// Registry
+export { ToolRegistry } from './tool-registry.js';
+
+// Common utilities
+export { buildToolName, SafetyWarningBuilder } from './tools/common/utils/index.js';
+
+// Types
+export type { BatchResult, FulfilledResult, RejectedResult } from '@fractalizer/mcp-infrastructure';
+```
+
+---
+
+## 🧪 Testing
+
+**Run tests:**
+```bash
+cd packages/framework/core
+npm run test
+```
+
+**With coverage:**
+```bash
+npm run test:coverage
+```
+
+**Watch mode:**
+```bash
+npm run test:watch
+```
+
+---
+
+## 🤝 Contributing
+
+See [../../.github/CONTRIBUTING.md](../../.github/CONTRIBUTING.md)
+
+**Architecture rules:** [../../CLAUDE.md](../../CLAUDE.md)
+
+---
+
+## 📄 License
+
+MIT License
+
+---
+
+## 🔗 Links
+
+- **Monorepo root:** [../../README.md](../../README.md)
+- **Architecture:** [../../ARCHITECTURE.md](../../ARCHITECTURE.md)
+- **Infrastructure package:** [../infrastructure/README.md](../infrastructure/README.md)

package/dist/definition/definition-validator.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Валидатор соответствия Zod Schema ↔ MCP Definition
+ *
+ * Используется для проверки, что MCP definition корректно описывает Zod schema.
+ * Критично для предотвращения багов schema-definition mismatch.
+ */
+import type { z } from 'zod';
+import type { ToolInputSchema } from './zod-json-schema-adapter.js';
+/**
+ * Типы ошибок валидации
+ */
+export declare enum ValidationErrorType {
+    /** Поле присутствует в schema, но отсутствует в definition.properties */
+    MISSING_PROPERTY = "missing_property",
+    /** Поле отсутствует в schema, но присутствует в definition.properties */
+    EXTRA_PROPERTY = "extra_property",
+    /** Поле обязательно в schema, но не указано в definition.required */
+    REQUIRED_MISMATCH = "required_mismatch",
+    /** Поле опционально в schema, но указано в definition.required */
+    OPTIONAL_MISMATCH = "optional_mismatch",
+    /** Различие в типах данных между schema и definition */
+    TYPE_MISMATCH = "type_mismatch",
+    /** Структурное различие (nested objects, arrays) */
+    STRUCTURE_MISMATCH = "structure_mismatch"
+}
+/**
+ * Описание ошибки валидации
+ */
+export interface ValidationError {
+    /** Тип ошибки */
+    type: ValidationErrorType;
+    /** Имя поля, в котором обнаружена ошибка */
+    field: string;
+    /** Человекочитаемое сообщение об ошибке */
+    message: string;
+    /** Ожидаемое значение (если применимо) */
+    expected?: unknown;
+    /** Фактическое значение (если применимо) */
+    actual?: unknown;
+}
+/**
+ * Результат валидации
+ */
+export interface ValidationResult {
+    /** Успешна ли валидация (нет ошибок) */
+    success: boolean;
+    /** Список ошибок (пустой если success: true) */
+    errors: ValidationError[];
+}
+/**
+ * Проверить соответствие Zod schema и MCP definition
+ *
+ * Выполняет полную проверку соответствия между Zod схемой и MCP definition:
+ * 1. Проверяет, что все поля из schema присутствуют в definition.properties
+ * 2. Проверяет, что required поля совпадают
+ * 3. Проверяет базовые типы данных
+ *
+ * @param schema - Zod схема параметров
+ * @param definition - MCP definition inputSchema
+ * @returns Результат валидации с списком ошибок (если есть)
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   issueKey: z.string(),
+ *   fields: z.array(z.string()).optional(),
+ * });
+ *
+ * const definition: ToolInputSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     issueKey: { type: 'string' },
+ *     // fields отсутствует - это ошибка!
+ *   },
+ *   required: ['issueKey'],
+ * };
+ *
+ * const result = validateSchemaDefinitionMatch(schema, definition);
+ * // result.success === false
+ * // result.errors[0].type === ValidationErrorType.MISSING_PROPERTY
+ * // result.errors[0].field === 'fields'
+ * ```
+ */
+export declare function validateSchemaDefinitionMatch<T extends z.ZodRawShape>(schema: z.ZodObject<T>, definition: ToolInputSchema): ValidationResult;
+/**
+ * Helper: Форматировать результат валидации в человекочитаемую строку
+ *
+ * @param result - Результат валидации
+ * @returns Строка с описанием ошибок (или 'OK' если ошибок нет)
+ *
+ * @example
+ * ```typescript
+ * const result = validateSchemaDefinitionMatch(schema, definition);
+ * console.log(formatValidationResult(result));
+ * // Вывод:
+ * // ❌ Schema-Definition Mismatch (2 errors):
+ * // 1. [missing_property] fields: Поле 'fields' присутствует в schema, но отсутствует в definition.properties
+ * // 2. [required_mismatch] issueKey: Поле 'issueKey' обязательно в schema, но не указано в definition.required
+ * ```
+ */
+export declare function formatValidationResult(result: ValidationResult): string;
+//# sourceMappingURL=definition-validator.d.ts.map

package/dist/definition/definition-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-validator.d.ts","sourceRoot":"","sources":["../../src/definition/definition-validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE;;GAEG;AACH,oBAAY,mBAAmB;IAC7B,yEAAyE;IACzE,gBAAgB,qBAAqB;IAErC,yEAAyE;IACzE,cAAc,mBAAmB;IAEjC,qEAAqE;IACrE,iBAAiB,sBAAsB;IAEvC,kEAAkE;IAClE,iBAAiB,sBAAsB;IAEvC,wDAAwD;IACxD,aAAa,kBAAkB;IAE/B,oDAAoD;IACpD,kBAAkB,uBAAuB;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,IAAI,EAAE,mBAAmB,CAAC;IAE1B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IAEjB,gDAAgD;IAChD,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EACnE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,UAAU,EAAE,eAAe,GAC1B,gBAAgB,CAoElB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAevE"}

package/dist/definition/definition-validator.js

@@ -0,0 +1,151 @@
+/**
+ * Валидатор соответствия Zod Schema ↔ MCP Definition
+ *
+ * Используется для проверки, что MCP definition корректно описывает Zod schema.
+ * Критично для предотвращения багов schema-definition mismatch.
+ */
+import { extractRequiredFields } from './zod-json-schema-adapter.js';
+/**
+ * Типы ошибок валидации
+ */
+export var ValidationErrorType;
+(function (ValidationErrorType) {
+    /** Поле присутствует в schema, но отсутствует в definition.properties */
+    ValidationErrorType["MISSING_PROPERTY"] = "missing_property";
+    /** Поле отсутствует в schema, но присутствует в definition.properties */
+    ValidationErrorType["EXTRA_PROPERTY"] = "extra_property";
+    /** Поле обязательно в schema, но не указано в definition.required */
+    ValidationErrorType["REQUIRED_MISMATCH"] = "required_mismatch";
+    /** Поле опционально в schema, но указано в definition.required */
+    ValidationErrorType["OPTIONAL_MISMATCH"] = "optional_mismatch";
+    /** Различие в типах данных между schema и definition */
+    ValidationErrorType["TYPE_MISMATCH"] = "type_mismatch";
+    /** Структурное различие (nested objects, arrays) */
+    ValidationErrorType["STRUCTURE_MISMATCH"] = "structure_mismatch";
+})(ValidationErrorType || (ValidationErrorType = {}));
+/**
+ * Проверить соответствие Zod schema и MCP definition
+ *
+ * Выполняет полную проверку соответствия между Zod схемой и MCP definition:
+ * 1. Проверяет, что все поля из schema присутствуют в definition.properties
+ * 2. Проверяет, что required поля совпадают
+ * 3. Проверяет базовые типы данных
+ *
+ * @param schema - Zod схема параметров
+ * @param definition - MCP definition inputSchema
+ * @returns Результат валидации с списком ошибок (если есть)
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   issueKey: z.string(),
+ *   fields: z.array(z.string()).optional(),
+ * });
+ *
+ * const definition: ToolInputSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     issueKey: { type: 'string' },
+ *     // fields отсутствует - это ошибка!
+ *   },
+ *   required: ['issueKey'],
+ * };
+ *
+ * const result = validateSchemaDefinitionMatch(schema, definition);
+ * // result.success === false
+ * // result.errors[0].type === ValidationErrorType.MISSING_PROPERTY
+ * // result.errors[0].field === 'fields'
+ * ```
+ */
+export function validateSchemaDefinitionMatch(schema, definition) {
+    const errors = [];
+    // 1. Извлекаем информацию из schema
+    const schemaFields = Object.keys(schema.shape);
+    const schemaRequiredFields = extractRequiredFields(schema);
+    // 2. Извлекаем информацию из definition
+    const definitionFields = Object.keys(definition.properties);
+    const definitionRequiredFields = definition.required ?? [];
+    // 3. Проверка: все поля из schema присутствуют в definition.properties
+    for (const field of schemaFields) {
+        if (!definitionFields.includes(field)) {
+            errors.push({
+                type: ValidationErrorType.MISSING_PROPERTY,
+                field,
+                message: `Поле '${field}' присутствует в schema, но отсутствует в definition.properties`,
+                expected: `Поле должно быть в definition.properties`,
+                actual: `Поле отсутствует`,
+            });
+        }
+    }
+    // 4. Проверка: нет лишних полей в definition.properties
+    for (const field of definitionFields) {
+        if (!schemaFields.includes(field)) {
+            errors.push({
+                type: ValidationErrorType.EXTRA_PROPERTY,
+                field,
+                message: `Поле '${field}' присутствует в definition.properties, но отсутствует в schema`,
+                expected: `Поле должно отсутствовать`,
+                actual: `Поле присутствует`,
+            });
+        }
+    }
+    // 5. Проверка: required поля совпадают
+    for (const field of schemaRequiredFields) {
+        if (!definitionRequiredFields.includes(field)) {
+            errors.push({
+                type: ValidationErrorType.REQUIRED_MISMATCH,
+                field,
+                message: `Поле '${field}' обязательно в schema, но не указано в definition.required`,
+                expected: `required: [..., '${field}']`,
+                actual: `required: [${definitionRequiredFields.join(', ')}]`,
+            });
+        }
+    }
+    // 6. Проверка: нет лишних required полей в definition
+    for (const field of definitionRequiredFields) {
+        if (!schemaRequiredFields.includes(field)) {
+            errors.push({
+                type: ValidationErrorType.OPTIONAL_MISMATCH,
+                field,
+                message: `Поле '${field}' опционально в schema, но указано в definition.required`,
+                expected: `required: [${schemaRequiredFields.join(', ')}]`,
+                actual: `required: [..., '${field}']`,
+            });
+        }
+    }
+    // 7. Формируем результат
+    return {
+        success: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Helper: Форматировать результат валидации в человекочитаемую строку
+ *
+ * @param result - Результат валидации
+ * @returns Строка с описанием ошибок (или 'OK' если ошибок нет)
+ *
+ * @example
+ * ```typescript
+ * const result = validateSchemaDefinitionMatch(schema, definition);
+ * console.log(formatValidationResult(result));
+ * // Вывод:
+ * // ❌ Schema-Definition Mismatch (2 errors):
+ * // 1. [missing_property] fields: Поле 'fields' присутствует в schema, но отсутствует в definition.properties
+ * // 2. [required_mismatch] issueKey: Поле 'issueKey' обязательно в schema, но не указано в definition.required
+ * ```
+ */
+export function formatValidationResult(result) {
+    if (result.success) {
+        return '✅ Schema-Definition Match: OK';
+    }
+    const lines = [`❌ Schema-Definition Mismatch (${result.errors.length} errors):`];
+    for (let i = 0; i < result.errors.length; i++) {
+        const error = result.errors[i];
+        if (error) {
+            lines.push(`${i + 1}. [${error.type}] ${error.field}: ${error.message}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=definition-validator.js.map

package/dist/definition/definition-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-validator.js","sourceRoot":"","sources":["../../src/definition/definition-validator.ts"],"names":[],"mappings":"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"}

package/dist/definition/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Definition Generator Module
+ *
+ * Автоматическая генерация MCP definition из Zod schema
+ *
+ * Основная функциональность:
+ * - Генерация inputSchema из Zod схемы (DRY принцип)
+ * - Валидация соответствия schema ↔ definition
+ * - Адаптер для конвертации Zod → JSON Schema
+ *
+ * @module @fractalizer/mcp-core/definition
+ */
+export { generateDefinitionFromSchema, type SchemaToDefinitionOptions, } from './schema-to-definition.js';
+export { zodToMcpInputSchema, extractRequiredFields, type ToolInputSchema, type ZodToJsonSchemaOptions, } from './zod-json-schema-adapter.js';
+export { validateSchemaDefinitionMatch, formatValidationResult, ValidationErrorType, type ValidationError, type ValidationResult, } from './definition-validator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/definition/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EACL,4BAA4B,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,mBAAmB,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,2BAA2B,CAAC"}