Merge branch 'main' into issue-2873-vmcp-default-resources

Author: 4t8dd

docs/operator/advanced-workflow-patterns.md

@@ -189,6 +189,7 @@ Workflows use Go's [text/template](https://pkg.go.dev/text/template) with these
 
 **Custom Functions**:
 - `json` - JSON encode a value
+- `fromJson` - Parse a JSON string into a value (useful when MCP servers return JSON as text content)
 - `quote` - Quote a string value
 
 **Built-in Functions**: All Go template built-ins are available (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`, `index`, `len`, `range`, `with`, `printf`, etc.)

docs/operator/composite-tools-quick-reference.md

@@ -80,11 +80,18 @@ Workflows use Go's [text/template](https://pkg.go.dev/text/template) syntax with
 
 ### Functions
 
+Composite Tools supports all the built-in functions from the [text/template](https://pkg.go.dev/text/template#hdr-Functions) library in addition to some functions for converting to/from JSON.
+
 ```yaml
-# JSON encoding
+# JSON encoding - convert value to JSON string
 arguments:
   data: "{{json .steps.step1.output}}"
 
+# JSON decoding - parse JSON string to access fields
+# Useful when MCP servers return JSON as text content
+arguments:
+  name: "{{(fromJson .steps.api.output.text).user.name}}"
+
 # String quoting
 arguments:
   quoted: "{{quote .params.value}}"

docs/operator/virtualmcpcompositetooldefinition-guide.md

@@ -330,6 +330,14 @@ arguments:
 - `.params.<name>`: Access workflow parameters
 - `.steps.<step_id>.<field>`: Access step results (Phase 2)
 
+**Available Template Functions**:
+
+Composite Tools supports all the built-in functions from [text/template](https://pkg.go.dev/text/template#hdr-Functions) (`eq`, `ne`, `lt`, `le`, `gt`, `ge`, `and`, `or`, `not`, `index`, `len`, `printf`, etc.) plus custom functions:
+
+- `json`: Encode a value as a JSON string
+- `fromJson`: Parse a JSON string into a value (useful when tools return JSON as text)
+- `quote`: Quote a string value
+
 ### Step Output Format
 
 Backend tools can return results in two formats, which affects how you access the data in templates:
@@ -355,6 +363,15 @@ arguments:
   message: "{{.steps.echo_tool.output.text}}"
 ```
 
+If a tool returns JSON as text content, use the `fromJson` function to parse it and access fields:
+
+```yaml
+# If api_call returns text: '{"user": {"name": "Alice", "email": "alice@example.com"}}'
+arguments:
+  name: "{{(fromJson .steps.api_call.output.text).user.name}}"
+  email: "{{(fromJson .steps.api_call.output.text).user.email}}"
+```
+
 > **Important**: Structured content must be an object (map). If a tool returns an array, primitive, or other non-object type, it falls back to unstructured content handling.
 
 ### Numeric Values in Templates

pkg/vmcp/composer/template_expander.go

@@ -34,6 +34,7 @@ func NewTemplateExpander() TemplateExpander {
 			"quote": func(s string) string {
 				return fmt.Sprintf("%q", s)
 			},
+			"fromJson": fromJson,
 		},
 	}
 }
@@ -245,3 +246,13 @@ func jsonEncode(v any) (string, error) {
 	}
 	return string(b), nil
 }
+
+// fromJson is a template function that parses a JSON string into a value.
+// It is useful when the underlying MCP server does not support structured content.
+func fromJson(s string) (any, error) {
+	var v any
+	if err := json.Unmarshal([]byte(s), &v); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal JSON: %w", err)
+	}
+	return v, nil
+}

pkg/vmcp/composer/template_expander_test.go

@@ -399,3 +399,95 @@ func TestTemplateExpander_WorkflowMetadataEmpty(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, map[string]any{"id": "<no value>"}, result)
 }
+
+func TestTemplateExpander_FromJsonFunction(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		data     map[string]any
+		steps    map[string]*StepResult
+		expected map[string]any
+		wantErr  bool
+	}{
+		{
+			name: "parse JSON from step output and access field",
+			data: map[string]any{"name": `{{(fromJson .steps.fetch.output.text).name}}`},
+			steps: map[string]*StepResult{
+				"fetch": {
+					Status: StepStatusCompleted,
+					Output: map[string]any{"text": `{"name": "Alice", "email": "alice@example.com"}`},
+				},
+			},
+			expected: map[string]any{"name": "Alice"},
+		},
+		{
+			name: "parse JSON and access nested field",
+			data: map[string]any{"email": `{{(fromJson .steps.fetch.output.text).user.email}}`},
+			steps: map[string]*StepResult{
+				"fetch": {
+					Status: StepStatusCompleted,
+					Output: map[string]any{"text": `{"user": {"email": "bob@example.com"}}`},
+				},
+			},
+			expected: map[string]any{"email": "bob@example.com"},
+		},
+		{
+			name: "parse JSON array and use with index",
+			data: map[string]any{"first": `{{index (fromJson .steps.fetch.output.text) 0}}`},
+			steps: map[string]*StepResult{
+				"fetch": {
+					Status: StepStatusCompleted,
+					Output: map[string]any{"text": `["apple", "banana", "cherry"]`},
+				},
+			},
+			expected: map[string]any{"first": "apple"},
+		},
+		{
+			name: "combine fromJson with json function",
+			data: map[string]any{"data": `{{json (fromJson .steps.fetch.output.text)}}`},
+			steps: map[string]*StepResult{
+				"fetch": {
+					Status: StepStatusCompleted,
+					Output: map[string]any{"text": `{"key": "value"}`},
+				},
+			},
+			expected: map[string]any{"data": `{"key":"value"}`},
+		},
+		{
+			name: "fromJson with invalid JSON causes error",
+			data: map[string]any{"val": `{{(fromJson .steps.fetch.output.text).key}}`},
+			steps: map[string]*StepResult{
+				"fetch": {
+					Status: StepStatusCompleted,
+					Output: map[string]any{"text": `not valid json`},
+				},
+			},
+			wantErr: true,
+		},
+	}
+
+	expander := NewTemplateExpander()
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			ctx := &WorkflowContext{
+				WorkflowID: "test",
+				Params:     map[string]any{},
+				Steps:      tt.steps,
+				Variables:  map[string]any{},
+			}
+
+			result, err := expander.Expand(context.Background(), tt.data, ctx)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}