@type-crafter/mcp 1.3.0 → 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.
- package/dist/docs/RULES_TYPES.md +81 -34
- package/dist/docs/WRITING_GUIDE.md +82 -74
- package/dist/index.js +13 -1
- package/package.json +1 -1
package/dist/docs/RULES_TYPES.md
CHANGED
|
@@ -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`
|
|
14
|
-
| `number`
|
|
15
|
-
| `integer`
|
|
16
|
-
| `boolean`
|
|
17
|
-
| `unknown`
|
|
18
|
-
| `object`
|
|
19
|
-
| `array`
|
|
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
|
|
27
|
+
There are exactly **two** valid formats:
|
|
28
28
|
|
|
29
|
-
| `format` value | Applies to |
|
|
30
|
-
|
|
|
31
|
-
| `date`
|
|
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.** `
|
|
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
|
|
270
|
-
|
|
|
271
|
-
| Primitive
|
|
272
|
-
| Object
|
|
273
|
-
| Array
|
|
274
|
-
| Reference
|
|
275
|
-
| Union
|
|
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
|
|
281
|
-
|
|
|
282
|
-
| Object
|
|
283
|
-
| Enum
|
|
284
|
-
| Primitive
|
|
285
|
-
| Array
|
|
286
|
-
| Union
|
|
287
|
-
| Intersection | `allOf` with array
|
|
288
|
-
| Reference
|
|
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
|
|
12
|
-
|
|
|
13
|
-
| `info`
|
|
14
|
-
| `types`
|
|
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
|
|
22
|
-
|
|
|
23
|
-
| `version` | string | Yes
|
|
24
|
-
| `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`
|
|
33
|
-
| `number`
|
|
34
|
-
| `integer`
|
|
35
|
-
| `boolean`
|
|
36
|
-
| `unknown`
|
|
37
|
-
| `object`
|
|
38
|
-
| `array`
|
|
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
|
|
42
|
+
### Valid Format Values (ONLY these exist)
|
|
43
43
|
|
|
44
|
-
| `format` value | Applies to
|
|
45
|
-
|
|
|
46
|
-
| `date`
|
|
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 `
|
|
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
|
|
55
|
-
|
|
|
56
|
-
| `type`
|
|
57
|
-
| `enum`
|
|
58
|
-
| `format`
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
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
|
|
65
|
-
|
|
|
66
|
-
| `type`
|
|
67
|
-
| `properties`
|
|
68
|
-
| `required`
|
|
69
|
-
| `additionalProperties` | No
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
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
|
|
76
|
-
|
|
|
77
|
-
| `type`
|
|
78
|
-
| `items`
|
|
79
|
-
| `
|
|
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`
|
|
87
|
+
| Keyword | Required | Description |
|
|
88
|
+
| ------- | -------- | ----------------------- |
|
|
89
|
+
| `$ref` | Yes | Path to referenced type |
|
|
86
90
|
|
|
87
91
|
#### On a composition
|
|
88
92
|
|
|
89
|
-
| Keyword | Required
|
|
90
|
-
|
|
|
91
|
-
| `oneOf` | Yes (for unions)
|
|
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
|
|
148
|
-
|
|
|
149
|
-
| Required property | Listed in `required` array
|
|
150
|
-
| Nullable property | NOT listed in `required` array
|
|
151
|
-
| String
|
|
152
|
-
| Number
|
|
153
|
-
| Boolean
|
|
154
|
-
| Date
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
|
|
|
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
|
|
171
|
-
|
|
|
172
|
-
| `structure`
|
|
173
|
-
| `types`
|
|
174
|
-
| `nullable`
|
|
175
|
-
| `references`
|
|
176
|
-
| `composition` | oneOf (unions), allOf (intersections)
|
|
177
|
-
| `patterns`
|
|
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
|
|
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
|
@@ -537,16 +537,28 @@ server.registerTool('list-languages', {
|
|
|
537
537
|
text: 'Supported Languages for type-crafter generate:\n\n' +
|
|
538
538
|
'1. typescript\n' +
|
|
539
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' +
|
|
540
542
|
' - Usage: type-crafter generate typescript <spec.yaml> <output-dir>\n\n' +
|
|
541
543
|
'2. typescript-with-decoders\n' +
|
|
542
544
|
' - Generates TypeScript types WITH runtime decoders\n' +
|
|
543
545
|
' - Useful for runtime validation of API responses\n' +
|
|
546
|
+
' - Same type mappings as typescript\n' +
|
|
544
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' +
|
|
545
557
|
'Writer Modes:\n' +
|
|
546
558
|
'- typesWriterMode: SingleFile | Files\n' +
|
|
547
559
|
'- groupedTypesWriterMode: FolderWithFiles | SingleFile\n\n' +
|
|
548
560
|
'Example:\n' +
|
|
549
|
-
'type-crafter generate
|
|
561
|
+
'type-crafter generate rust ./types.yaml ./src/types SingleFile FolderWithFiles',
|
|
550
562
|
},
|
|
551
563
|
],
|
|
552
564
|
};
|