@type-crafter/mcp 1.2.1 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,15 +8,15 @@
8
8
 
9
9
  These are the **only** values the `type` field accepts:
10
10
 
11
- | `type` value | Notes |
12
- | --- | --- |
13
- | `string` | Accepts optional `format: date` and/or `enum` |
14
- | `number` | Accepts optional `enum` |
15
- | `integer` | Same as number. Accepts optional `enum` |
16
- | `boolean` | |
17
- | `unknown` | Dynamic/untyped value |
18
- | `object` | Requires `properties` and/or `additionalProperties` |
19
- | `array` | Requires `items`. Cannot be a top-level type |
11
+ | `type` value | Notes |
12
+ | ------------ | -------------------------------------------------------------------- |
13
+ | `string` | Accepts optional `format: date` or `format: date-time` and/or `enum` |
14
+ | `number` | Accepts optional `enum` |
15
+ | `integer` | Same as number. Accepts optional `enum` |
16
+ | `boolean` | |
17
+ | `unknown` | Dynamic/untyped value |
18
+ | `object` | Requires `properties` and/or `additionalProperties` |
19
+ | `array` | Requires `items`. Cannot be a top-level type |
20
20
 
21
21
  **No other type values exist.** `date`, `datetime`, `float`, `int`, `any`, `null`, `void`, `map`, `list` are all invalid.
22
22
 
@@ -24,19 +24,20 @@ These are the **only** values the `type` field accepts:
24
24
 
25
25
  ## Valid Format Values (Complete List)
26
26
 
27
- There is exactly **one** valid format:
27
+ There are exactly **two** valid formats:
28
28
 
29
- | `format` value | Applies to |
30
- | --- | --- |
31
- | `date` | `type: string` only |
29
+ | `format` value | Applies to | Description |
30
+ | -------------- | ------------------- | --------------------------- |
31
+ | `date` | `type: string` only | Date without time |
32
+ | `date-time` | `type: string` only | Date with time and timezone |
32
33
 
33
- **No other format values exist.** `date-time`, `datetime`, `time`, `email`, `uri`, `uuid`, `iso8601`, `url` are all invalid.
34
+ **No other format values exist.** `datetime`, `time`, `email`, `uri`, `uuid`, `iso8601`, `url` are all invalid.
34
35
 
35
36
  ---
36
37
 
37
38
  ## Primitive Types
38
39
 
39
- Valid keywords on a primitive: `type`, `enum`, `format`, `description`, `example`. Nothing else.
40
+ Valid keywords on a primitive: `type`, `enum`, `format`, `customAttributes`, `description`, `example`. Nothing else.
40
41
 
41
42
  ```yaml
42
43
  properties:
@@ -49,6 +50,9 @@ properties:
49
50
  birthDate:
50
51
  type: string
51
52
  format: date
53
+ createdAt:
54
+ type: string
55
+ format: date-time
52
56
  metadata:
53
57
  type: unknown
54
58
  ```
@@ -57,7 +61,7 @@ properties:
57
61
 
58
62
  ## Object Types
59
63
 
60
- Valid keywords on an object: `type`, `properties`, `required`, `additionalProperties`, `description`, `example`. Nothing else.
64
+ Valid keywords on an object: `type`, `properties`, `required`, `additionalProperties`, `customAttributes`, `description`, `example`. Nothing else.
61
65
 
62
66
  ```yaml
63
67
  User:
@@ -124,7 +128,7 @@ User:
124
128
 
125
129
  ## Array Types
126
130
 
127
- Valid keywords on an array: `type`, `items`, `description`. Nothing else.
131
+ Valid keywords on an array: `type`, `items`, `customAttributes`, `description`. Nothing else.
128
132
 
129
133
  ### Arrays Cannot Be Top-Level Types
130
134
 
@@ -264,25 +268,68 @@ UserWithMeta:
264
268
 
265
269
  ---
266
270
 
271
+ ## Custom Attributes (Pass-Through)
272
+
273
+ `customAttributes` is an optional key/value map available on any type (primitive, object, array). It is **not validated** by Type Crafter — values are passed directly to language templates. Different templates read different keys.
274
+
275
+ ### On a Property (e.g. custom serialization name)
276
+
277
+ ```yaml
278
+ Product:
279
+ type: object
280
+ required:
281
+ - id
282
+ - bodyHtml
283
+ properties:
284
+ id:
285
+ type: string
286
+ bodyHtml:
287
+ type: string
288
+ customAttributes:
289
+ x-name: 'Body (HTML)'
290
+ ```
291
+
292
+ The Rust template reads `x-name` to emit `#[serde(rename = "Body (HTML)")]` on that field.
293
+
294
+ ### On an Object (e.g. rename_all strategy)
295
+
296
+ ```yaml
297
+ Product:
298
+ type: object
299
+ customAttributes:
300
+ renameAll: camelCase
301
+ required:
302
+ - id
303
+ properties:
304
+ id:
305
+ type: string
306
+ productType:
307
+ type: string
308
+ ```
309
+
310
+ The Rust template reads `renameAll` to emit `#[serde(rename_all = "camelCase")]` on the struct, suppressing automatic per-field renames.
311
+
312
+ ---
313
+
267
314
  ## Valid Keywords Summary
268
315
 
269
- | Type Kind | Valid Keywords (and ONLY these) |
270
- | --- | --- |
271
- | Primitive | `type`, `enum`, `format`, `description`, `example` |
272
- | Object | `type`, `properties`, `required`, `additionalProperties`, `description`, `example` |
273
- | Array | `type`, `items`, `description` |
274
- | Reference | `$ref` |
275
- | Union | `oneOf` |
276
- | Intersection | `allOf` |
316
+ | Type Kind | Valid Keywords (and ONLY these) |
317
+ | ------------ | ------------------------------------------------------------------------------------------------------ |
318
+ | Primitive | `type`, `enum`, `format`, `customAttributes`, `description`, `example` |
319
+ | Object | `type`, `properties`, `required`, `additionalProperties`, `customAttributes`, `description`, `example` |
320
+ | Array | `type`, `items`, `customAttributes`, `description` |
321
+ | Reference | `$ref` |
322
+ | Union | `oneOf` |
323
+ | Intersection | `allOf` |
277
324
 
278
325
  ## Type Definition Summary
279
326
 
280
- | Type | Structure | Top-Level? |
281
- | --- | --- | --- |
282
- | Object | `type: object` + `properties` | Yes |
283
- | Enum | `type: string` or `type: number` + `enum` | Yes |
284
- | Primitive | `type: string` / `number` / `boolean` / `unknown` | Yes |
285
- | Array | `type: array` + `items` | **NO** |
286
- | Union | `oneOf` with array | Yes |
287
- | Intersection | `allOf` with array | Yes |
288
- | Reference | `$ref` with path | Yes |
327
+ | Type | Structure | Top-Level? |
328
+ | ------------ | ------------------------------------------------- | ---------- |
329
+ | Object | `type: object` + `properties` | Yes |
330
+ | Enum | `type: string` or `type: number` + `enum` | Yes |
331
+ | Primitive | `type: string` / `number` / `boolean` / `unknown` | Yes |
332
+ | Array | `type: array` + `items` | **NO** |
333
+ | Union | `oneOf` with array | Yes |
334
+ | Intersection | `allOf` with array | Yes |
335
+ | Reference | `$ref` with path | Yes |
@@ -8,91 +8,97 @@ Type Crafter generates typed code from YAML specifications. This guide is the de
8
8
 
9
9
  ### Root-Level Keys (ONLY these three exist)
10
10
 
11
- | Key | Required | Description |
12
- | --- | --- | --- |
13
- | `info` | Yes (for top files) | Version and title metadata |
14
- | `types` | At least one of `types` or `groupedTypes` | Flat/top-level type definitions |
15
- | `groupedTypes` | At least one of `types` or `groupedTypes` | Namespaced type definitions |
11
+ | Key | Required | Description |
12
+ | -------------- | ----------------------------------------- | ------------------------------- |
13
+ | `info` | Yes (for top files) | Version and title metadata |
14
+ | `types` | At least one of `types` or `groupedTypes` | Flat/top-level type definitions |
15
+ | `groupedTypes` | At least one of `types` or `groupedTypes` | Namespaced type definitions |
16
16
 
17
17
  **No other root-level keys exist.** Do not add `schemas`, `definitions`, `components`, or anything else at the root.
18
18
 
19
19
  ### The `info` Object (ONLY these two keys)
20
20
 
21
- | Key | Type | Required | Description |
22
- | --- | --- | --- | --- |
23
- | `version` | string | Yes | Semver format, e.g. `'1.0.0'` |
24
- | `title` | string | Yes | Descriptive title |
21
+ | Key | Type | Required | Description |
22
+ | --------- | ------ | -------- | ----------------------------- |
23
+ | `version` | string | Yes | Semver format, e.g. `'1.0.0'` |
24
+ | `title` | string | Yes | Descriptive title |
25
25
 
26
26
  **No other info keys exist.** Do not add `description`, `contact`, `license`, or anything else.
27
27
 
28
28
  ### Valid Type Values (ONLY these)
29
29
 
30
- | `type` value | Notes |
31
- | --- | --- |
32
- | `string` | Basic string |
33
- | `number` | Numeric value |
34
- | `integer` | Numeric value (same as number) |
35
- | `boolean` | True/false |
36
- | `unknown` | Dynamic/untyped value |
37
- | `object` | Must have `properties` and/or `additionalProperties` |
38
- | `array` | Must have `items`. **Cannot be a top-level type.** |
30
+ | `type` value | Notes |
31
+ | ------------ | ---------------------------------------------------- |
32
+ | `string` | Basic string |
33
+ | `number` | Numeric value |
34
+ | `integer` | Numeric value (same as number) |
35
+ | `boolean` | True/false |
36
+ | `unknown` | Dynamic/untyped value |
37
+ | `object` | Must have `properties` and/or `additionalProperties` |
38
+ | `array` | Must have `items`. **Cannot be a top-level type.** |
39
39
 
40
40
  **No other type values exist.** Do not use `date`, `datetime`, `float`, `int`, `any`, `null`, `void`, `map`, `list`, `dict`, or anything else.
41
41
 
42
- ### Valid Format Values (ONLY one exists)
42
+ ### Valid Format Values (ONLY these exist)
43
43
 
44
- | `format` value | Applies to | Description |
45
- | --- | --- | --- |
46
- | `date` | `type: string` only | Represents a date value |
44
+ | `format` value | Applies to | Description |
45
+ | -------------- | ------------------- | ----------------------------------------------------- |
46
+ | `date` | `type: string` only | Represents a date value |
47
+ | `date-time` | `type: string` only | Represents a date-time value (with time and timezone) |
47
48
 
48
- **No other format values exist.** Do not use `date-time`, `datetime`, `time`, `email`, `uri`, `url`, `uuid`, `iso8601`, or anything else.
49
+ **No other format values exist.** Do not use `datetime`, `time`, `email`, `uri`, `url`, `uuid`, `iso8601`, or anything else.
49
50
 
50
51
  ### Valid Keywords Per Type Kind
51
52
 
52
53
  #### On a primitive (`type: string | number | integer | boolean | unknown`)
53
54
 
54
- | Keyword | Required | Description |
55
- | --- | --- | --- |
56
- | `type` | Yes | One of: `string`, `number`, `integer`, `boolean`, `unknown` |
57
- | `enum` | No | Array of allowed values. Creates a union of literals. |
58
- | `format` | No | Only `date`, only on `type: string` |
59
- | `description` | No | Documentation comment |
60
- | `example` | No | Documentation example |
55
+ | Keyword | Required | Description |
56
+ | ------------------ | -------- | ---------------------------------------------------------------------- |
57
+ | `type` | Yes | One of: `string`, `number`, `integer`, `boolean`, `unknown` |
58
+ | `enum` | No | Array of allowed values. Creates a union of literals. |
59
+ | `format` | No | `date` or `date-time`, only on `type: string` |
60
+ | `customAttributes` | No | Pass-through key/value map for template-level features (e.g. `x-name`) |
61
+ | `description` | No | Documentation comment |
62
+ | `example` | No | Documentation example |
61
63
 
62
64
  #### On an object (`type: object`)
63
65
 
64
- | Keyword | Required | Description |
65
- | --- | --- | --- |
66
- | `type` | Yes | Must be `object` |
67
- | `properties` | Yes (unless `additionalProperties` only) | Map of property names to type definitions |
68
- | `required` | No | Array of property names that are non-nullable |
69
- | `additionalProperties` | No | `true` or object with `keyType` and `valueType` for hashmaps |
70
- | `description` | No | Documentation comment |
71
- | `example` | No | Documentation example |
66
+ | Keyword | Required | Description |
67
+ | ---------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
68
+ | `type` | Yes | Must be `object` |
69
+ | `properties` | Yes (unless `additionalProperties` only) | Map of property names to type definitions |
70
+ | `required` | No | Array of property names that are non-nullable |
71
+ | `additionalProperties` | No | `true` or object with `keyType` and `valueType` for hashmaps |
72
+ | `customAttributes` | No | Pass-through key/value map for template-level features (e.g. `renameAll`) |
73
+ | `description` | No | Documentation comment |
74
+ | `example` | No | Documentation example |
72
75
 
73
76
  #### On an array (`type: array`)
74
77
 
75
- | Keyword | Required | Description |
76
- | --- | --- | --- |
77
- | `type` | Yes | Must be `array` |
78
- | `items` | Yes | Type definition for array elements |
79
- | `description` | No | Documentation comment |
78
+ | Keyword | Required | Description |
79
+ | ------------------ | -------- | ------------------------------------------------------ |
80
+ | `type` | Yes | Must be `array` |
81
+ | `items` | Yes | Type definition for array elements |
82
+ | `customAttributes` | No | Pass-through key/value map for template-level features |
83
+ | `description` | No | Documentation comment |
80
84
 
81
85
  #### On a reference
82
86
 
83
- | Keyword | Required | Description |
84
- | --- | --- | --- |
85
- | `$ref` | Yes | Path to referenced type |
87
+ | Keyword | Required | Description |
88
+ | ------- | -------- | ----------------------- |
89
+ | `$ref` | Yes | Path to referenced type |
86
90
 
87
91
  #### On a composition
88
92
 
89
- | Keyword | Required | Description |
90
- | --- | --- | --- |
91
- | `oneOf` | Yes (for unions) | Array of type definitions. Union of types. |
93
+ | Keyword | Required | Description |
94
+ | ------- | ----------------------- | ------------------------------------------------- |
95
+ | `oneOf` | Yes (for unions) | Array of type definitions. Union of types. |
92
96
  | `allOf` | Yes (for intersections) | Array of type definitions. Intersection of types. |
93
97
 
94
98
  **No other keywords exist anywhere.** Do not use `nullable`, `optional`, `extensible`, `default`, `minimum`, `maximum`, `minLength`, `maxLength`, `pattern`, `title` (on properties), `readOnly`, `writeOnly`, `deprecated`, `discriminator`, `allowed_values`, `values`, `options`, `choices`, or anything from OpenAPI/JSON Schema that is not listed above.
95
99
 
100
+ > **Note on `customAttributes`:** This field is a generic pass-through map. Its keys/values are not validated by Type Crafter — they are forwarded directly to language templates. Different language templates may read different keys (e.g. the Rust template reads `x-name` for serde rename and `renameAll` for `serde(rename_all)`). Consult the template documentation for your target language.
101
+
96
102
  ---
97
103
 
98
104
  ## Nullability: The Only Mechanism
@@ -144,22 +150,24 @@ types:
144
150
 
145
151
  ## Quick Reference
146
152
 
147
- | Concept | YAML |
148
- | --- | --- |
149
- | Required property | Listed in `required` array |
150
- | Nullable property | NOT listed in `required` array |
151
- | String | `type: string` |
152
- | Number | `type: number` |
153
- | Boolean | `type: boolean` |
154
- | Date | `type: string` with `format: date` |
155
- | Unknown | `type: unknown` |
156
- | String enum | `type: string` with `enum` list |
157
- | Number enum | `type: number` with `enum` list |
158
- | Array | `type: array` with `items` |
159
- | Union | `oneOf` with array of types |
160
- | Intersection | `allOf` with array of types |
161
- | Reference | `$ref` with path |
162
- | Hashmap | `additionalProperties: true` or with `keyType`/`valueType` |
153
+ | Concept | YAML |
154
+ | ----------------- | ---------------------------------------------------------- |
155
+ | Required property | Listed in `required` array |
156
+ | Nullable property | NOT listed in `required` array |
157
+ | String | `type: string` |
158
+ | Number | `type: number` |
159
+ | Boolean | `type: boolean` |
160
+ | Date | `type: string` with `format: date` |
161
+ | Date-time | `type: string` with `format: date-time` |
162
+ | Unknown | `type: unknown` |
163
+ | String enum | `type: string` with `enum` list |
164
+ | Number enum | `type: number` with `enum` list |
165
+ | Array | `type: array` with `items` |
166
+ | Union | `oneOf` with array of types |
167
+ | Intersection | `allOf` with array of types |
168
+ | Reference | `$ref` with path |
169
+ | Hashmap | `additionalProperties: true` or with `keyType`/`valueType` |
170
+ | Custom attributes | `customAttributes: { key: value }` on any type |
163
171
 
164
172
  ---
165
173
 
@@ -167,14 +175,14 @@ types:
167
175
 
168
176
  Call `get-rules-section` with these topics for deep dives:
169
177
 
170
- | Section | What You'll Learn |
171
- | --- | --- |
172
- | `structure` | Root structure, info section, types vs groupedTypes |
173
- | `types` | Objects, enums, primitives, arrays, nested objects |
174
- | `nullable` | How `required` array controls nullability |
175
- | `references` | $ref syntax, top-file vs non-top-file rules |
176
- | `composition` | oneOf (unions), allOf (intersections) |
177
- | `patterns` | Common patterns with full examples |
178
+ | Section | What You'll Learn |
179
+ | ------------- | --------------------------------------------------- |
180
+ | `structure` | Root structure, info section, types vs groupedTypes |
181
+ | `types` | Objects, enums, primitives, arrays, nested objects |
182
+ | `nullable` | How `required` array controls nullability |
183
+ | `references` | $ref syntax, top-file vs non-top-file rules |
184
+ | `composition` | oneOf (unions), allOf (intersections) |
185
+ | `patterns` | Common patterns with full examples |
178
186
 
179
187
  ---
180
188
 
@@ -192,7 +200,7 @@ Call `get-rules-section` with these topics for deep dives:
192
200
 
193
201
  1. **Only use keywords listed in this guide** - Anything else is invalid and will be rejected
194
202
  2. **Nullability = `required` array** - The only mechanism that controls this
195
- 3. **Only valid format is `date`** - No other format values exist
203
+ 3. **Only valid formats are `date` and `date-time`** - No other format values exist
196
204
  4. **Only valid types are `string`, `number`, `integer`, `boolean`, `unknown`, `object`, `array`**
197
205
  5. **Arrays = properties only** - Never top-level types
198
206
  6. **Paths = from project root** - Where you run the CLI
package/dist/index.js CHANGED
@@ -8,6 +8,10 @@ import { dirname } from 'path';
8
8
  import { parse as parseYaml } from 'yaml';
9
9
  import { randomUUID } from 'crypto';
10
10
  import { z } from 'zod';
11
+ import { createRequire } from 'module';
12
+ const require = createRequire(import.meta.url);
13
+ const packageJson = require('../package.json');
14
+ const MCP_VERSION = packageJson.version;
11
15
  // ES module dirname workaround
12
16
  const __filename = fileURLToPath(import.meta.url);
13
17
  const __dirname = dirname(__filename);
@@ -212,7 +216,7 @@ function checkSpecContent(specContent, resolvedSpecPath) {
212
216
  // Create server instance
213
217
  const server = new McpServer({
214
218
  name: 'type-crafter-mcp',
215
- version: '0.2.0',
219
+ version: MCP_VERSION,
216
220
  }, {
217
221
  capabilities: {
218
222
  tools: {},
@@ -533,16 +537,42 @@ server.registerTool('list-languages', {
533
537
  text: 'Supported Languages for type-crafter generate:\n\n' +
534
538
  '1. typescript\n' +
535
539
  ' - Generates TypeScript type definitions (.ts files)\n' +
540
+ ' - Type mappings: string→string, number→number, integer→number, boolean→boolean, unknown→unknown\n' +
541
+ ' - Formats: date→string (no special type)\n' +
536
542
  ' - Usage: type-crafter generate typescript <spec.yaml> <output-dir>\n\n' +
537
543
  '2. typescript-with-decoders\n' +
538
544
  ' - Generates TypeScript types WITH runtime decoders\n' +
539
545
  ' - Useful for runtime validation of API responses\n' +
546
+ ' - Same type mappings as typescript\n' +
540
547
  ' - Usage: type-crafter generate typescript-with-decoders <spec.yaml> <output-dir>\n\n' +
548
+ '3. rust\n' +
549
+ ' - Generates Rust struct/enum definitions (.rs files) with serde derives\n' +
550
+ ' - Type mappings: string→String, number→i32, integer→i32, boolean→bool, unknown→serde_json::Value\n' +
551
+ ' - Formats: date→time::Date, date-time→time::OffsetDateTime\n' +
552
+ ' - Arrays: Vec<T>\n' +
553
+ ' - Handles reserved keywords with r# prefix\n' +
554
+ ' - Supports customAttributes for serde rename (x-name) and rename_all (renameAll)\n' +
555
+ ' - Module structure: snake_case mod files with mod.rs exporters\n' +
556
+ ' - Usage: type-crafter generate rust <spec.yaml> <output-dir>\n\n' +
541
557
  'Writer Modes:\n' +
542
558
  '- typesWriterMode: SingleFile | Files\n' +
543
559
  '- groupedTypesWriterMode: FolderWithFiles | SingleFile\n\n' +
544
560
  'Example:\n' +
545
- 'type-crafter generate typescript ./types.yaml ./src/types SingleFile FolderWithFiles',
561
+ 'type-crafter generate rust ./types.yaml ./src/types SingleFile FolderWithFiles',
562
+ },
563
+ ],
564
+ };
565
+ });
566
+ // Tool 6: get-version
567
+ server.registerTool('get-version', {
568
+ description: 'Returns the current version of the Type Crafter MCP server.',
569
+ inputSchema: z.object({}),
570
+ }, async () => {
571
+ return {
572
+ content: [
573
+ {
574
+ type: 'text',
575
+ text: `Type Crafter MCP v${MCP_VERSION}`,
546
576
  },
547
577
  ],
548
578
  };
@@ -551,7 +581,7 @@ server.registerTool('list-languages', {
551
581
  async function main() {
552
582
  const transport = new StdioServerTransport();
553
583
  await server.connect(transport);
554
- console.error('Type Crafter MCP Server v0.2.0 running on stdio');
584
+ console.error(`Type Crafter MCP Server v${MCP_VERSION} running on stdio`);
555
585
  }
556
586
  main().catch((error) => {
557
587
  console.error('Server error:', error);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@type-crafter/mcp",
3
- "version": "1.2.1",
3
+ "version": "1.3.1",
4
4
  "description": "MCP server for Type Crafter - generate types from YAML specifications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",