@macroforge/mcp-server 0.1.37 → 0.1.38

package/docs/builtin-macros/serialize.md

@@ -8,18 +8,10 @@ including circular references.
 
 | Type | Generated Code | Description |
 |------|----------------|-------------|
-| Class | `toStringifiedJSON()`, `toObject()`, `__serialize(ctx)` | Instance methods |
-| Enum | `toStringifiedJSONEnumName(value)`, `__serializeEnumName` | Standalone functions |
-| Interface | `toStringifiedJSONInterfaceName(value)`, etc. | Standalone functions |
-| Type Alias | `toStringifiedJSONTypeName(value)`, etc. | Standalone functions |
-
-## Configuration
-
-The `functionNamingStyle` option in `macroforge.json` controls naming:
-- `"prefix"` (default): Prefixes with type name (e.g., `myTypeToStringifiedJSON`)
-- `"suffix"`: Suffixes with type name (e.g., `toStringifiedJSONMyType`)
-- `"generic"`: Uses TypeScript generics (e.g., `toStringifiedJSON<T extends MyType>`)
-- `"namespace"`: Legacy namespace wrapping
+| Class | `classNameSerialize(value)` + `static serialize(value)` | Standalone function + static wrapper method |
+| Enum | `enumNameSerialize(value)`, `enumNameSerializeWithContext` | Standalone functions |
+| Interface | `interfaceNameSerialize(value)`, etc. | Standalone functions |
+| Type Alias | `typeNameSerialize(value)`, etc. | Standalone functions |
 
 ## Cycle Detection Protocol
 
@@ -45,11 +37,11 @@ When an object is serialized:
 |------|------------------------|
 | Primitives | Direct value |
 | `Date` | `toISOString()` |
-| Arrays | For primitive-like element types, pass through; for `Date`/`Date | null`, map to ISO strings; otherwise map and call `__serialize(ctx)` when available |
-| `Map<K,V>` | For primitive-like values, `Object.fromEntries(map.entries())`; for `Date`/`Date | null`, convert to ISO strings; otherwise call `__serialize(ctx)` per value when available |
+| Arrays | For primitive-like element types, pass through; for `Date`/`Date | null`, map to ISO strings; otherwise map and call `SerializeWithContext(ctx)` when available |
+| `Map<K,V>` | For primitive-like values, `Object.fromEntries(map.entries())`; for `Date`/`Date | null`, convert to ISO strings; otherwise call `SerializeWithContext(ctx)` per value when available |
 | `Set<T>` | Convert to array; element handling matches `Array<T>` |
-| Nullable | Include `null` explicitly; for primitive-like and `Date` unions the generator avoids runtime `__serialize` checks |
-| Objects | Call `__serialize(ctx)` if available (to support user-defined implementations) |
+| Nullable | Include `null` explicitly; for primitive-like and `Date` unions the generator avoids runtime `SerializeWithContext` checks |
+| Objects | Call `SerializeWithContext(ctx)` if available (to support user-defined implementations) |
 
 Note: the generator specializes some code paths based on the declared TypeScript type to
 avoid runtime feature detection on primitives and literal unions.
@@ -58,34 +50,144 @@ avoid runtime feature detection on primitives and literal unions.
 
 The `@serde` decorator supports:
 
-- `skip` / `skip_serializing` - Exclude field from serialization
+- `skip` / `skipSerializing` - Exclude field from serialization
 - `rename = "jsonKey"` - Use different JSON property name
 - `flatten` - Merge nested object's fields into parent
 
 ## Example
 
-```typescript
-@derive(Serialize)
+```typescript before
+/** @derive(Serialize) */
 class User {
     id: number;
 
-    @serde(rename = "userName")
+    /** @serde({ rename: "userName" }) */
     name: string;
 
-    @serde(skip_serializing)
+    /** @serde({ skipSerializing: true }) */
     password: string;
 
-    @serde(flatten)
+    /** @serde({ flatten: true }) */
     metadata: UserMetadata;
 }
+```
+
+```typescript after
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
 
-// Usage:
-const user = new User();
-const json = user.toStringifiedJSON();
-// => '{"__type":"User","__id":1,"id":1,"userName":"Alice",...}'
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
 
-const obj = user.toObject();
-// => { __type: "User", __id: 1, id: 1, userName: "Alice", ... }
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: SerializeContext
+): Record<string, unknown> {
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
+    const __id = ctx.register(value);
+    const result: Record<string, unknown> = { __type: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
+```
+
+Generated output:
+
+```typescript
+import { SerializeContext } from 'macroforge/serde';
+
+class User {
+    id: number;
+
+    name: string;
+
+    password: string;
+
+    metadata: UserMetadata;
+    /** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
+
+    static serialize(value: User): string {
+        return userSerialize(value);
+    }
+    /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
+
+    static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+        return userSerializeWithContext(value, ctx);
+    }
+}
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */ export function userSerialize(
+    value: User
+): string {
+    const ctx = SerializeContext.create();
+    return JSON.stringify(userSerializeWithContext(value, ctx));
+} /** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */
+export function userSerializeWithContext(
+    value: User,
+    ctx: SerializeContext
+): Record<string, unknown> {
+    const existingId = ctx.getId(value);
+    if (existingId !== undefined) {
+        return { __ref: existingId };
+    }
+    const __id = ctx.register(value);
+    const result: Record<string, unknown> = { __type: 'User', __id };
+    result['id'] = value.id;
+    result['userName'] = value.name;
+    {
+        const __flattened = userMetadataSerializeWithContext(value.metadata, ctx);
+        const { __type: _, __id: __, ...rest } = __flattened as any;
+        Object.assign(result, rest);
+    }
+    return result;
+}
 ```
 
 ## Required Import

package/docs/concepts/derive-system.md

@@ -78,46 +78,32 @@ class User {
   
   metadata: Record<string, unknown>;
 
-  toString(): string {
-    const parts: string[] = [];
-    parts.push("userId: " + this.id);
-    parts.push("name: " + this.name);
-    parts.push("metadata: " + this.metadata);
-    return "User { " + parts.join(", ") + " }";
+  static toString(value: User): string {
+    return userToString(value);
 }
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata  */
 
-  toStringifiedJSON(): string {
-    const ctx = SerializeContext.create();
-    return JSON.stringify(this.__serialize(ctx));
+  static serialize(value: User): string {
+    return userSerialize(value);
 }
+/** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context  */
 
-  toObject(): Record<string, unknown> {
-    const ctx = SerializeContext.create();
-    return this.__serialize(ctx);
-}
-
-  __serialize(ctx: SerializeContext): Record<string, unknown> {
-    const existingId = ctx.getId(this);
-    if (existingId !== undefined) {
-        return {
-            __ref: existingId
-        };
-    }
-    const __id = ctx.register(this);
-    const result: Record<string, unknown> = {
-        __type: "User",
-        __id
-    };
-    result["user_id"] = this.id;
-    result["name"] = this.name;
-    {
-        const __flattened = record < string, unknown;
-        const { __type: _, __id: __, ...rest } = __flattened as any;
-        Object.assign(result, rest);
-    }
-    return result;
+  static serializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown> {
+    return userSerializeWithContext(value, ctx);
 }
 }
+
+export function userToString(value: User): string {const parts: string[]= []; parts.push("userId: " + value.id); parts.push("name: " + value.name); parts.push("metadata: " + value.metadata); return "User { " + parts.join(", " )+ " }" ; }
+
+/** Serializes a value to a JSON string.
+@param value - The value to serialize
+@returns JSON string representation with cycle detection metadata */export function userSerialize(value: User): string {const ctx = SerializeContext.create(); return JSON.stringify(userSerializeWithContext(value, ctx));}/** @internal Serializes with an existing context for nested/cyclic object graphs.
+@param value - The value to serialize
+@param ctx - The serialization context */export function userSerializeWithContext(value: User, ctx: SerializeContext): Record<string, unknown>{const existingId = ctx.getId(value); if(existingId!== undefined){return {__ref: existingId};}const __id = ctx.register(value); const result: Record<string, unknown>= {__type: "User" , __id,}; result["user_id" ]= value.id; result["name" ]= value.name; {const __flattened = record<string, unknown>SerializeWithContext(value.metadata, ctx); const {__type: _, __id: __,...rest}= __flattened as any; Object.assign(result, rest);}return result;}
 ``` Syntax rules:
  - Must be inside a JSDoc comment immediately before the field
  - Options use object literal syntax: `@attr({ key: value })`

package/docs/concepts/how-macros-work.md

@@ -18,12 +18,16 @@ class User {
 class User {
     name: string;
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('name: ' + this.name);
-        return 'User { ' + parts.join(', ') + ' }';
+    static toString(value: User): string {
+        return userToString(value);
     }
 }
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('name: ' + value.name);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 ``` ## Zero Runtime Overhead
  Because code generation happens at compile time, there's no:
  - Runtime reflection or metadata

package/docs/getting-started/first-macro.md

@@ -30,33 +30,39 @@ export class User {
         this.email = email;
     }
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('name: ' + this.name);
-        parts.push('age: ' + this.age);
-        parts.push('email: ' + this.email);
-        return 'User { ' + parts.join(', ') + ' }';
+    static toString(value: User): string {
+        return userToString(value);
     }
 
-    clone(): User {
-        const cloned = Object.create(Object.getPrototypeOf(this));
-        cloned.name = this.name;
-        cloned.age = this.age;
-        cloned.email = this.email;
-        return cloned;
+    static clone(value: User): User {
+        return userClone(value);
     }
 
-    equals(other: unknown): boolean {
-        if (this === other) return true;
-        if (!(other instanceof User)) return false;
-        const typedOther = other as User;
-        return (
-            this.name === typedOther.name &&
-            this.age === typedOther.age &&
-            this.email === typedOther.email
-        );
+    static equals(a: User, b: User): boolean {
+        return userEquals(a, b);
     }
 }
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('name: ' + value.name);
+    parts.push('age: ' + value.age);
+    parts.push('email: ' + value.email);
+    return 'User { ' + parts.join(', ') + ' }';
+}
+
+export function userClone(value: User): User {
+    const cloned = Object.create(Object.getPrototypeOf(value));
+    cloned.name = value.name;
+    cloned.age = value.age;
+    cloned.email = value.email;
+    return cloned;
+}
+
+export function userEquals(a: User, b: User): boolean {
+    if (a === b) return true;
+    return a.name === b.name && a.age === b.age && a.email === b.email;
+}
 ``` ## Using the Generated Methods
  ```
 const user = new User("Alice", 30, "alice@example.com");
@@ -110,13 +116,17 @@ export class User {
         this.password = password;
     }
 
-    toString(): string {
-        const parts: string[] = [];
-        parts.push('userId: ' + this.id);
-        parts.push('name: ' + this.name);
-        return 'User { ' + parts.join(', ') + ' }';
+    static toString(value: User): string {
+        return userToString(value);
     }
 }
+
+export function userToString(value: User): string {
+    const parts: string[] = [];
+    parts.push('userId: ' + value.id);
+    parts.push('name: ' + value.name);
+    return 'User { ' + parts.join(', ') + ' }';
+}
 ``` ```
 const user = new User(42, "Alice", "secret123");
 console.log(user.toString());

package/docs/sections.json

@@ -103,13 +103,91 @@
     "path": "builtin-macros/partial-ord.md",
     "use_cases": "compareTo, partial ordering, sorting, nullable comparison"
   },
+  {
+    "id": "serialize/overview",
+    "title": "Serialize: Overview",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/serialize/overview.md",
+    "use_cases": "toJSON, serialization, serialize, classnameserialize(value), enumnameserialize(value), enumnameserializewithcontext",
+    "parent_id": "serialize"
+  },
+  {
+    "id": "serialize/type-specific-serialization",
+    "title": "Serialize: Type-Specific Serialization",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/serialize/type-specific-serialization.md",
+    "use_cases": "toJSON, serialization, date, toisostring(), serializewithcontext(ctx)",
+    "parent_id": "serialize"
+  },
+  {
+    "id": "serialize/example",
+    "title": "Serialize: Example",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/serialize/example.md",
+    "use_cases": "toJSON, serialization",
+    "parent_id": "serialize"
+  },
   {
     "id": "serialize",
     "title": "Serialize",
     "category": "builtin-macros",
     "category_title": "Built-in Macros",
     "path": "builtin-macros/serialize.md",
-    "use_cases": "toJSON, serialization, json, api, data transfer"
+    "use_cases": "toJSON, serialization, json, api, data transfer",
+    "is_chunked": true,
+    "chunk_ids": [
+      "serialize/overview",
+      "serialize/type-specific-serialization",
+      "serialize/example"
+    ]
+  },
+  {
+    "id": "deserialize/overview",
+    "title": "Deserialize: Overview",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/overview.md",
+    "use_cases": "fromJSON, deserialization, deserialize, classnamedeserialize(input), enumnamedeserialize(input)",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/cycleforward-reference-support",
+    "title": "Deserialize: Cycle/Forward-Reference Support",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/cycleforward-reference-support.md",
+    "use_cases": "fromJSON, deserialization, pendingref, ctx.applypatches(), __ref",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/validation",
+    "title": "Deserialize: Validation",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/validation.md",
+    "use_cases": "fromJSON, deserialization, @serde(validate(...)), email, url, uuid",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/union-type-deserialization",
+    "title": "Deserialize: Union Type Deserialization",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/union-type-deserialization.md",
+    "use_cases": "fromJSON, deserialization, typeof, __type",
+    "parent_id": "deserialize"
+  },
+  {
+    "id": "deserialize/example",
+    "title": "Deserialize: Example",
+    "category": "builtin-macros",
+    "category_title": "Built-in Macros",
+    "path": "builtin-macros/deserialize/example.md",
+    "use_cases": "fromJSON, deserialization",
+    "parent_id": "deserialize"
   },
   {
     "id": "deserialize",
@@ -117,7 +195,15 @@
     "category": "builtin-macros",
     "category_title": "Built-in Macros",
     "path": "builtin-macros/deserialize.md",
-    "use_cases": "fromJSON, deserialization, parsing, validation, json"
+    "use_cases": "fromJSON, deserialization, parsing, validation, json",
+    "is_chunked": true,
+    "chunk_ids": [
+      "deserialize/overview",
+      "deserialize/cycleforward-reference-support",
+      "deserialize/validation",
+      "deserialize/union-type-deserialization",
+      "deserialize/example"
+    ]
   },
   {
     "id": "custom-overview",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macroforge/mcp-server",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "MCP server for Macroforge documentation and code analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "typescript": "^5.7.0"
   },
   "peerDependencies": {
-    "macroforge": "^0.1.37"
+    "macroforge": "^0.1.38"
   },
   "peerDependenciesMeta": {
     "macroforge": {