@vinkius-core/mcp-fusion 0.6.0 → 0.7.0

package/README.md

@@ -243,8 +243,28 @@ const meta = builder.getActionMetadata();
 
 ## 🔬 Architecture & Internals
 
-### Domain Model Layer
-Beyond the framework, the package provides a full domain model for MCP primitives:
+### Project Structure
+
+The codebase is organized into bounded contexts with shallow nesting (max 2 levels):
+
+```
+src/
+├── domain/          → Pure immutable domain models
+├── converters/      → Domain-to-DTO converters
+├── framework/
+│   ├── types.ts     → ALL contracts & shared types (single file)
+│   ├── result.ts    → Result<T> monad (cross-cutting)
+│   ├── response.ts  → Response helpers (cross-cutting)
+│   ├── builder/     → GroupedToolBuilder, ActionGroupBuilder, Compiler
+│   ├── execution/   → ExecutionPipeline, MiddlewareCompiler
+│   ├── schema/      → Schema, Description, Annotation strategies
+│   ├── registry/    → ToolRegistry, ToolFilterEngine
+│   └── server/      → ServerResolver, ServerAttachment
+└── index.ts         → Public API barrel
+```
+
+### Domain Model Layer (`src/domain/`)
+The package provides a full domain model for MCP primitives:
 
 | Class | Purpose |
 |---|---|
@@ -257,17 +277,17 @@ Beyond the framework, the package provides a full domain model for MCP primitive
 
 *Features Bidirectional converters (`ToolConverterBase`, `GroupConverterBase`, etc.) with null filtering for clean conversion to external representations.*
 
-### Strategy Pattern Internals
-Six pure-function modules orchestrated by `GroupedToolBuilder`. Every module is independently testable and replaceable. **Zero shared state.**
-
-| Module | Responsibility |
-|---|---|
-| `SchemaGenerator` | 4-tier per-field annotations from Zod schemas |
-| `DescriptionGenerator` | 3-layer descriptions with ⚠️ DESTRUCTIVE warnings |
-| `ToonDescriptionGenerator` | TOON-encoded descriptions via `@toon-format/toon` |
-| `AnnotationAggregator` | Conservative behavioral hint aggregation |
-| `MiddlewareCompiler` | Right-to-left closure composition at build time |
-| `SchemaUtils` | Zod field extraction + build-time schema collision detection |
+### Strategy Modules
+Six pure-function modules organized by bounded context. Every module is independently testable and replaceable. **Zero shared state.**
+
+| Context | Module | Responsibility |
+|---|---|---|
+| `schema/` | `SchemaGenerator` | 4-tier per-field annotations from Zod schemas |
+| `schema/` | `DescriptionGenerator` | 3-layer descriptions with ⚠️ DESTRUCTIVE warnings |
+| `schema/` | `ToonDescriptionGenerator` | TOON-encoded descriptions via `@toon-format/toon` |
+| `schema/` | `AnnotationAggregator` | Conservative behavioral hint aggregation |
+| `execution/` | `MiddlewareCompiler` | Right-to-left closure composition at build time |
+| `schema/` | `SchemaUtils` | Zod field extraction + build-time schema collision detection |
 
 ---
 

package/dist/converters/ConverterBase.d.ts

@@ -3,25 +3,66 @@
  *
  * Provides batch conversion with null filtering in both directions.
  * Domain-specific converters extend this class and only implement
- * the single-item abstract methods: `convertFrom` and `convertTo`.
+ * the single-item abstract methods: {@link convertFrom} and {@link convertTo}.
  *
- * @template TSource - The domain model type (e.g. Group, Tool)
- * @template TTarget - The external/DTO type
+ * @typeParam TSource - The domain model type (e.g. Group, Tool)
+ * @typeParam TTarget - The external/DTO type
+ *
+ * @example
+ * ```typescript
+ * import { ToolConverterBase, Tool } from '@vinkius-core/mcp-fusion';
+ *
+ * interface ToolDto { id: string; label: string }
+ *
+ * class MyToolConverter extends ToolConverterBase<ToolDto> {
+ *     convertFrom(tool: Tool): ToolDto {
+ *         return { id: tool.name, label: tool.title ?? tool.name };
+ *     }
+ *     convertTo(dto: ToolDto): Tool {
+ *         const tool = new Tool(dto.id);
+ *         tool.title = dto.label;
+ *         return tool;
+ *     }
+ * }
+ *
+ * const converter = new MyToolConverter();
+ * const dtos = converter.convertFromBatch(tools);  // Tool[] → ToolDto[]
+ * const tools = converter.convertToBatch(dtos);     // ToolDto[] → Tool[]
+ * ```
+ *
+ * @see {@link ToolConverterBase} for tool-specific converters
+ * @see {@link GroupConverterBase} for group-specific converters
  */
 export declare abstract class ConverterBase<TSource, TTarget> {
     /**
      * Convert a batch of source items to target items.
      * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param sources - Array of domain model instances
+     * @returns Array of converted DTOs (nulls removed)
      */
     convertFromBatch(sources: TSource[]): TTarget[];
-    /** Convert a single source item to a target item. */
+    /**
+     * Convert a single source item to a target item.
+     *
+     * @param source - Domain model instance
+     * @returns The converted DTO
+     */
     abstract convertFrom(source: TSource): TTarget;
     /**
      * Convert a batch of target items back to source items.
      * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param targets - Array of DTOs
+     * @returns Array of domain model instances (nulls removed)
      */
     convertToBatch(targets: TTarget[]): TSource[];
-    /** Convert a single target item back to a source item. */
+    /**
+     * Convert a single target item back to a source item.
+     *
+     * @param target - DTO instance
+     * @returns The domain model instance
+     */
     abstract convertTo(target: TTarget): TSource;
 }
 //# sourceMappingURL=ConverterBase.d.ts.map

package/dist/converters/ConverterBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConverterBase.d.ts","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,8BAAsB,aAAa,CAAC,OAAO,EAAE,OAAO;IAChD;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM/C,qDAAqD;IACrD,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAE9C;;;OAGG;IACH,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM7C,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAC/C"}
+{"version":3,"file":"ConverterBase.d.ts","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,aAAa,CAAC,OAAO,EAAE,OAAO;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAE9C;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM7C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAC/C"}

package/dist/converters/ConverterBase.js

@@ -3,15 +3,43 @@
  *
  * Provides batch conversion with null filtering in both directions.
  * Domain-specific converters extend this class and only implement
- * the single-item abstract methods: `convertFrom` and `convertTo`.
+ * the single-item abstract methods: {@link convertFrom} and {@link convertTo}.
  *
- * @template TSource - The domain model type (e.g. Group, Tool)
- * @template TTarget - The external/DTO type
+ * @typeParam TSource - The domain model type (e.g. Group, Tool)
+ * @typeParam TTarget - The external/DTO type
+ *
+ * @example
+ * ```typescript
+ * import { ToolConverterBase, Tool } from '@vinkius-core/mcp-fusion';
+ *
+ * interface ToolDto { id: string; label: string }
+ *
+ * class MyToolConverter extends ToolConverterBase<ToolDto> {
+ *     convertFrom(tool: Tool): ToolDto {
+ *         return { id: tool.name, label: tool.title ?? tool.name };
+ *     }
+ *     convertTo(dto: ToolDto): Tool {
+ *         const tool = new Tool(dto.id);
+ *         tool.title = dto.label;
+ *         return tool;
+ *     }
+ * }
+ *
+ * const converter = new MyToolConverter();
+ * const dtos = converter.convertFromBatch(tools);  // Tool[] → ToolDto[]
+ * const tools = converter.convertToBatch(dtos);     // ToolDto[] → Tool[]
+ * ```
+ *
+ * @see {@link ToolConverterBase} for tool-specific converters
+ * @see {@link GroupConverterBase} for group-specific converters
  */
 export class ConverterBase {
     /**
      * Convert a batch of source items to target items.
      * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param sources - Array of domain model instances
+     * @returns Array of converted DTOs (nulls removed)
      */
     convertFromBatch(sources) {
         return sources
@@ -21,6 +49,9 @@ export class ConverterBase {
     /**
      * Convert a batch of target items back to source items.
      * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param targets - Array of DTOs
+     * @returns Array of domain model instances (nulls removed)
      */
     convertToBatch(targets) {
         return targets

package/dist/converters/ConverterBase.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConverterBase.js","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,OAAgB,aAAa;IAC/B;;;OAGG;IACH,gBAAgB,CAAC,OAAkB;QAC/B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;aAC7B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;IAKD;;;OAGG;IACH,cAAc,CAAC,OAAkB;QAC7B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;aAC3B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;CAIJ"}
+{"version":3,"file":"ConverterBase.js","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,aAAa;IAC/B;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAkB;QAC/B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;aAC7B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;IAUD;;;;;;OAMG;IACH,cAAc,CAAC,OAAkB;QAC7B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;aAC3B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;CASJ"}

package/dist/converters/GroupConverter.d.ts

@@ -1,10 +1,32 @@
-import { type Group } from '../Group.js';
+import { type Group } from '../domain/Group.js';
 import { ConverterBase } from './ConverterBase.js';
-/** Type-safe Group converter contract. */
+/**
+ * Type-safe Group converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link GroupConverterBase} for the base implementation class
+ */
 export type GroupConverter<T> = ConverterBase<Group, T>;
 /**
  * Base class for Group converters.
- * Extend and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyGroupConverter extends GroupConverterBase<GroupDto> {
+ *     convertFrom(group: Group): GroupDto {
+ *         return { name: group.name, children: group.childGroups.length };
+ *     }
+ *     convertTo(dto: GroupDto): Group {
+ *         return new Group(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export declare abstract class GroupConverterBase<T> extends ConverterBase<Group, T> {
 }

package/dist/converters/GroupConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GroupConverter.d.ts","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,0CAA0C;AAC1C,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAExD;;;GAGG;AACH,8BAAsB,kBAAkB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC;CAAG"}
+{"version":3,"file":"GroupConverter.d.ts","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,kBAAkB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/GroupConverter.js

@@ -1,7 +1,25 @@
+import {} from '../domain/Group.js';
 import { ConverterBase } from './ConverterBase.js';
 /**
  * Base class for Group converters.
- * Extend and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyGroupConverter extends GroupConverterBase<GroupDto> {
+ *     convertFrom(group: Group): GroupDto {
+ *         return { name: group.name, children: group.childGroups.length };
+ *     }
+ *     convertTo(dto: GroupDto): Group {
+ *         return new Group(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export class GroupConverterBase extends ConverterBase {
 }

package/dist/converters/GroupConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"GroupConverter.js","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;GAGG;AACH,MAAM,OAAgB,kBAAsB,SAAQ,aAAuB;CAAG"}
+{"version":3,"file":"GroupConverter.js","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,kBAAsB,SAAQ,aAAuB;CAAG"}

package/dist/converters/PromptConverter.d.ts

@@ -1,10 +1,32 @@
-import { type Prompt } from '../Prompt.js';
+import { type Prompt } from '../domain/Prompt.js';
 import { ConverterBase } from './ConverterBase.js';
-/** Type-safe Prompt converter contract. */
+/**
+ * Type-safe Prompt converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link PromptConverterBase} for the base implementation class
+ */
 export type PromptConverter<T> = ConverterBase<Prompt, T>;
 /**
  * Base class for Prompt converters.
- * Extend and implement `convertFrom(prompt)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(prompt)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyPromptConverter extends PromptConverterBase<PromptDto> {
+ *     convertFrom(prompt: Prompt): PromptDto {
+ *         return { name: prompt.name, args: prompt.promptArguments.length };
+ *     }
+ *     convertTo(dto: PromptDto): Prompt {
+ *         return new Prompt(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export declare abstract class PromptConverterBase<T> extends ConverterBase<Prompt, T> {
 }

package/dist/converters/PromptConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PromptConverter.d.ts","sourceRoot":"","sources":["../../src/converters/PromptConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,2CAA2C;AAC3C,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAE1D;;;GAGG;AACH,8BAAsB,mBAAmB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;CAAG"}
+{"version":3,"file":"PromptConverter.d.ts","sourceRoot":"","sources":["../../src/converters/PromptConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,mBAAmB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/PromptConverter.js

@@ -1,7 +1,25 @@
+import {} from '../domain/Prompt.js';
 import { ConverterBase } from './ConverterBase.js';
 /**
  * Base class for Prompt converters.
- * Extend and implement `convertFrom(prompt)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(prompt)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyPromptConverter extends PromptConverterBase<PromptDto> {
+ *     convertFrom(prompt: Prompt): PromptDto {
+ *         return { name: prompt.name, args: prompt.promptArguments.length };
+ *     }
+ *     convertTo(dto: PromptDto): Prompt {
+ *         return new Prompt(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export class PromptConverterBase extends ConverterBase {
 }

package/dist/converters/PromptConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"PromptConverter.js","sourceRoot":"","sources":["../../src/converters/PromptConverter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;GAGG;AACH,MAAM,OAAgB,mBAAuB,SAAQ,aAAwB;CAAG"}
+{"version":3,"file":"PromptConverter.js","sourceRoot":"","sources":["../../src/converters/PromptConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,mBAAuB,SAAQ,aAAwB;CAAG"}

package/dist/converters/ResourceConverter.d.ts

@@ -1,10 +1,34 @@
-import { type Resource } from '../Resource.js';
+import { type Resource } from '../domain/Resource.js';
 import { ConverterBase } from './ConverterBase.js';
-/** Type-safe Resource converter contract. */
+/**
+ * Type-safe Resource converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link ResourceConverterBase} for the base implementation class
+ */
 export type ResourceConverter<T> = ConverterBase<Resource, T>;
 /**
  * Base class for Resource converters.
- * Extend and implement `convertFrom(resource)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(resource)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyResourceConverter extends ResourceConverterBase<ResourceDto> {
+ *     convertFrom(resource: Resource): ResourceDto {
+ *         return { name: resource.name, uri: resource.uri ?? '' };
+ *     }
+ *     convertTo(dto: ResourceDto): Resource {
+ *         const r = new Resource(dto.name);
+ *         r.uri = dto.uri;
+ *         return r;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export declare abstract class ResourceConverterBase<T> extends ConverterBase<Resource, T> {
 }

package/dist/converters/ResourceConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResourceConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ResourceConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,6CAA6C;AAC7C,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AAE9D;;;GAGG;AACH,8BAAsB,qBAAqB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC;CAAG"}
+{"version":3,"file":"ResourceConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ResourceConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,qBAAqB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,QAAQ,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/ResourceConverter.js

@@ -1,7 +1,27 @@
+import {} from '../domain/Resource.js';
 import { ConverterBase } from './ConverterBase.js';
 /**
  * Base class for Resource converters.
- * Extend and implement `convertFrom(resource)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(resource)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyResourceConverter extends ResourceConverterBase<ResourceDto> {
+ *     convertFrom(resource: Resource): ResourceDto {
+ *         return { name: resource.name, uri: resource.uri ?? '' };
+ *     }
+ *     convertTo(dto: ResourceDto): Resource {
+ *         const r = new Resource(dto.name);
+ *         r.uri = dto.uri;
+ *         return r;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export class ResourceConverterBase extends ConverterBase {
 }

package/dist/converters/ResourceConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ResourceConverter.js","sourceRoot":"","sources":["../../src/converters/ResourceConverter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;GAGG;AACH,MAAM,OAAgB,qBAAyB,SAAQ,aAA0B;CAAG"}
+{"version":3,"file":"ResourceConverter.js","sourceRoot":"","sources":["../../src/converters/ResourceConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,qBAAyB,SAAQ,aAA0B;CAAG"}

package/dist/converters/ToolAnnotationsConverter.d.ts

@@ -1,10 +1,32 @@
-import { type ToolAnnotations } from '../ToolAnnotations.js';
+import { type ToolAnnotations } from '../domain/ToolAnnotations.js';
 import { ConverterBase } from './ConverterBase.js';
-/** Type-safe ToolAnnotations converter contract. */
+/**
+ * Type-safe ToolAnnotations converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link ToolAnnotationsConverterBase} for the base implementation class
+ */
 export type ToolAnnotationsConverter<T> = ConverterBase<ToolAnnotations, T>;
 /**
  * Base class for ToolAnnotations converters.
- * Extend and implement `convertFrom(toolAnnotation)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(annotations)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyAnnotationsConverter extends ToolAnnotationsConverterBase<McpAnnotations> {
+ *     convertFrom(ta: ToolAnnotations): McpAnnotations {
+ *         return { readOnly: ta.readOnlyHint ?? false, destructive: ta.destructiveHint ?? false };
+ *     }
+ *     convertTo(mcp: McpAnnotations): ToolAnnotations {
+ *         return createToolAnnotations({ readOnlyHint: mcp.readOnly, destructiveHint: mcp.destructive });
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export declare abstract class ToolAnnotationsConverterBase<T> extends ConverterBase<ToolAnnotations, T> {
 }

package/dist/converters/ToolAnnotationsConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolAnnotationsConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ToolAnnotationsConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,oDAAoD;AACpD,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;AAE5E;;;GAGG;AACH,8BAAsB,4BAA4B,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC;CAAG"}
+{"version":3,"file":"ToolAnnotationsConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ToolAnnotationsConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,4BAA4B,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,eAAe,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/ToolAnnotationsConverter.js

@@ -1,7 +1,25 @@
+import {} from '../domain/ToolAnnotations.js';
 import { ConverterBase } from './ConverterBase.js';
 /**
  * Base class for ToolAnnotations converters.
- * Extend and implement `convertFrom(toolAnnotation)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(annotations)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyAnnotationsConverter extends ToolAnnotationsConverterBase<McpAnnotations> {
+ *     convertFrom(ta: ToolAnnotations): McpAnnotations {
+ *         return { readOnly: ta.readOnlyHint ?? false, destructive: ta.destructiveHint ?? false };
+ *     }
+ *     convertTo(mcp: McpAnnotations): ToolAnnotations {
+ *         return createToolAnnotations({ readOnlyHint: mcp.readOnly, destructiveHint: mcp.destructive });
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export class ToolAnnotationsConverterBase extends ConverterBase {
 }

package/dist/converters/ToolAnnotationsConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ToolAnnotationsConverter.js","sourceRoot":"","sources":["../../src/converters/ToolAnnotationsConverter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;GAGG;AACH,MAAM,OAAgB,4BAAgC,SAAQ,aAAiC;CAAG"}
+{"version":3,"file":"ToolAnnotationsConverter.js","sourceRoot":"","sources":["../../src/converters/ToolAnnotationsConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,4BAAgC,SAAQ,aAAiC;CAAG"}

package/dist/converters/ToolConverter.d.ts

@@ -1,10 +1,34 @@
-import { type Tool } from '../Tool.js';
+import { type Tool } from '../domain/Tool.js';
 import { ConverterBase } from './ConverterBase.js';
-/** Type-safe Tool converter contract. */
+/**
+ * Type-safe Tool converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link ToolConverterBase} for the base implementation class
+ */
 export type ToolConverter<T> = ConverterBase<Tool, T>;
 /**
  * Base class for Tool converters.
- * Extend and implement `convertFrom(tool)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(tool)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class McpToolConverter extends ToolConverterBase<McpTool> {
+ *     convertFrom(tool: Tool): McpTool {
+ *         return { name: tool.name, description: tool.description ?? '' };
+ *     }
+ *     convertTo(mcp: McpTool): Tool {
+ *         const tool = new Tool(mcp.name);
+ *         tool.description = mcp.description;
+ *         return tool;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export declare abstract class ToolConverterBase<T> extends ConverterBase<Tool, T> {
 }

package/dist/converters/ToolConverter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ToolConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,yCAAyC;AACzC,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAEtD;;;GAGG;AACH,8BAAsB,iBAAiB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;CAAG"}
+{"version":3,"file":"ToolConverter.d.ts","sourceRoot":"","sources":["../../src/converters/ToolConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,iBAAiB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/ToolConverter.js

@@ -1,7 +1,27 @@
+import {} from '../domain/Tool.js';
 import { ConverterBase } from './ConverterBase.js';
 /**
  * Base class for Tool converters.
- * Extend and implement `convertFrom(tool)` and `convertTo(dto)`.
+ *
+ * Extend this and implement `convertFrom(tool)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class McpToolConverter extends ToolConverterBase<McpTool> {
+ *     convertFrom(tool: Tool): McpTool {
+ *         return { name: tool.name, description: tool.description ?? '' };
+ *     }
+ *     convertTo(mcp: McpTool): Tool {
+ *         const tool = new Tool(mcp.name);
+ *         tool.description = mcp.description;
+ *         return tool;
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
  */
 export class ToolConverterBase extends ConverterBase {
 }

package/dist/converters/ToolConverter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ToolConverter.js","sourceRoot":"","sources":["../../src/converters/ToolConverter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKnD;;;GAGG;AACH,MAAM,OAAgB,iBAAqB,SAAQ,aAAsB;CAAG"}
+{"version":3,"file":"ToolConverter.js","sourceRoot":"","sources":["../../src/converters/ToolConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,iBAAqB,SAAQ,aAAsB;CAAG"}

package/dist/domain/Annotations.d.ts

@@ -0,0 +1,42 @@
+import { type Role } from './Role.js';
+/**
+ * Resource Annotations — audience, priority, and freshness metadata.
+ *
+ * Used on {@link Resource} instances to provide hints about who
+ * should see the resource and how important it is.
+ *
+ * @example
+ * ```typescript
+ * import { createAnnotations, Role } from '@vinkius-core/mcp-fusion';
+ *
+ * const annotations = createAnnotations({
+ *     audience: [Role.ASSISTANT],
+ *     priority: 0.8,
+ *     lastModified: '2025-01-15T10:30:00Z',
+ * });
+ * ```
+ *
+ * @see {@link Resource} for usage on resources
+ * @see {@link createAnnotations} for the factory function
+ */
+export interface Annotations {
+    /** Target audience roles for this resource */
+    readonly audience?: readonly Role[];
+    /** Priority weight (0.0 = lowest, 1.0 = highest) */
+    readonly priority?: number;
+    /** ISO 8601 timestamp of last modification */
+    readonly lastModified?: string;
+}
+/**
+ * Create Annotations from partial properties.
+ *
+ * @param props - Annotation properties (all optional)
+ * @returns An Annotations instance
+ *
+ * @example
+ * ```typescript
+ * const ann = createAnnotations({ priority: 0.5 });
+ * ```
+ */
+export declare function createAnnotations(props?: Annotations): Annotations;
+//# sourceMappingURL=Annotations.d.ts.map

package/dist/domain/Annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.d.ts","sourceRoot":"","sources":["../../src/domain/Annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,WAAW;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,GAAE,WAAgB,GAAG,WAAW,CAEtE"}

package/dist/domain/Annotations.js

@@ -0,0 +1,16 @@
+import {} from './Role.js';
+/**
+ * Create Annotations from partial properties.
+ *
+ * @param props - Annotation properties (all optional)
+ * @returns An Annotations instance
+ *
+ * @example
+ * ```typescript
+ * const ann = createAnnotations({ priority: 0.5 });
+ * ```
+ */
+export function createAnnotations(props = {}) {
+    return { ...props };
+}
+//# sourceMappingURL=Annotations.js.map

package/dist/domain/Annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.js","sourceRoot":"","sources":["../../src/domain/Annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,WAAW,CAAC;AA+BtC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAqB,EAAE;IACrD,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACxB,CAAC"}