feat(mcp): unwrap the MCP envelope in JSON output, add --envelope (#30)

praxis mcp <mcp> <fn> --json (and any piped/non-TTY invocation) used to
pass the raw gateway envelope through, forcing every scripted caller —
the skill tells AI hosts to always use --json — into a
`jq -r '.content[0].text' | jq` double-parse. Human mode already
unwrapped; the machine-facing mode was the only one that didn't.

JSON mode now prints the tool payload directly when the response is a
single text content item whose payload is valid JSON. Everything else
keeps the canonical envelope so JSON output stays valid JSON: plain-text
payloads, multi-item/non-text content, non-envelope bodies, and tool
errors (isError: true still exits 1 with the error shape intact). The
new --envelope flag disables unwrapping in both output modes.

parseMCPResponse is now the one place that knows the envelope shape: a
single parse feeds the exit-code decision and both output paths
(replacing the envelopeIsError + prettyMCPOutput split, which parsed
the same bytes up to three times).

The embedded praxis skill text and CHANGELOG call out the break:
scripts parsing .content[0].text should drop that step or pass
--envelope.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: anujhydrabadi

CHANGELOG.md

@@ -8,6 +8,17 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **Breaking:** `praxis mcp <mcp> <fn>` JSON output (explicit `--json`
+  *and* any piped/non-TTY invocation) now unwraps the MCP envelope:
+  when the response is a single text content item whose payload is
+  valid JSON, the payload is printed directly, so callers consume the
+  tool result without the `jq -r '.content[0].text' | jq` double-parse.
+  Tool errors (`isError: true`, exit 1), plain-text payloads,
+  multi-item content, and non-envelope bodies still emit the canonical
+  envelope, so JSON output stays valid JSON. Scripts that parse
+  `.content[0].text` must drop that step — or pass the new `--envelope`
+  flag, which always prints the raw envelope (in human output mode
+  too).
 - `praxis status --json` now lives up to "small JSON snapshot":
   `skills_installed` / `agents_installed` are deduped, sorted name
   arrays instead of per-(name, harness) objects with paths and

cmd/mcp.go

@@ -19,10 +19,11 @@ import (
 )
 
 var (
-	mcpJSON    bool
-	mcpArgs    []string
-	mcpBody    string
-	mcpTimeout time.Duration
+	mcpJSON     bool
+	mcpArgs     []string
+	mcpBody     string
+	mcpEnvelope bool
+	mcpTimeout  time.Duration
 )
 
 func init() {
@@ -33,6 +34,7 @@ func init() {
 	// tests covering raptor commands like `--arg command='... "quoted" ...'`.
 	mcpCmd.Flags().StringArrayVar(&mcpArgs, "arg", nil, "key=value pair (repeatable); merged into request body")
 	mcpCmd.Flags().StringVar(&mcpBody, "body", "", "raw JSON body (use '-' for stdin); overrides --arg")
+	mcpCmd.Flags().BoolVar(&mcpEnvelope, "envelope", false, "always print the raw MCP envelope ({content:[...],isError?}) instead of unwrapping JSON tool output")
 	mcpCmd.Flags().DurationVar(&mcpTimeout, "timeout", 60*time.Second, "request timeout")
 	rootCmd.AddCommand(mcpCmd)
 }
@@ -128,18 +130,18 @@ Examples:
 			os.Exit(exitcode.Usage)
 		}
 
-		// HTTP 200 — print the body verbatim (pass-through MCP envelope).
-		// If isError is true on a dict-shape response, exit 1 so callers
-		// can detect tool-level failure even with JSON output.
-		exitWithToolError := envelopeIsError(resp)
+		// HTTP 200 — render the body (see parseMCPResponse for the unwrap
+		// contract). If isError is true on a dict-shape response, exit 1
+		// so callers can detect tool-level failure even with JSON output.
+		res := parseMCPResponse(resp)
 
 		if asJSON {
-			_, _ = out.Write(append(bytes.TrimRight(resp, "\n"), '\n'))
+			_, _ = out.Write(append(mcpJSONOutput(resp, res, mcpEnvelope), '\n'))
 		} else {
-			fmt.Fprintln(out, prettyMCPOutput(resp))
+			fmt.Fprintln(out, mcpHumanOutput(resp, res, mcpEnvelope))
 		}
 
-		if exitWithToolError {
+		if res.isError {
 			os.Exit(exitcode.Error)
 		}
 		return nil
@@ -395,16 +397,6 @@ func extractDetail(raw []byte, fallback string) string {
 	return fallback
 }
 
-// envelopeIsError detects the MCP `{isError: true, ...}` envelope so the
-// process can exit non-zero even though the HTTP call succeeded.
-func envelopeIsError(raw []byte) bool {
-	var probe struct {
-		IsError bool `json:"isError"`
-	}
-	_ = json.Unmarshal(raw, &probe)
-	return probe.IsError
-}
-
 func prettyJSON(raw []byte) string {
 	var v any
 	if err := json.Unmarshal(raw, &v); err != nil {
@@ -417,32 +409,69 @@ func prettyJSON(raw []byte) string {
 	return string(out)
 }
 
-// prettyMCPOutput renders an MCP response for human (non-JSON) output.
 // The gateway wraps tool output as
 //
-//	{"content":[{"type":"text","text":"<payload>"}]}
+//	{"content":[{"type":"text","text":"<payload>"}],"isError"?:bool}
 //
-// where the payload is itself usually escaped JSON. When the envelope
-// carries exactly one text item, unwrap it: pretty-print the inner JSON
-// if it parses, otherwise surface the text verbatim. Anything that
-// isn't this single-text shape (plain responses, multi-item content,
-// non-text items) falls through to ordinary pretty-printing so we never
-// hide structure by guessing. JSON output (`--json`) is unaffected — it
-// still passes the canonical envelope through untouched.
-func prettyMCPOutput(raw []byte) string {
+// where the payload is itself usually escaped JSON. parseMCPResponse is
+// the one place that knows this shape; its single parse feeds the
+// exit-code decision and both output modes. Either mode unwraps only
+// the single-text shape — anything else (multi-item content, non-text
+// items, non-envelope bodies) is passed through so we never hide
+// structure by guessing — with one asymmetry: JSON mode keeps the
+// envelope on tool errors so the isError shape survives for scripted
+// callers, while human mode unwraps them for readability. `--envelope`
+// disables unwrapping in both modes.
+
+type mcpResponse struct {
+	isError    bool
+	singleText string // payload when content is exactly one non-empty text item
+	isSingle   bool
+}
+
+func parseMCPResponse(raw []byte) mcpResponse {
 	var env struct {
+		IsError bool `json:"isError"`
 		Content []struct {
 			Type string `json:"type"`
 			Text string `json:"text"`
 		} `json:"content"`
 	}
-	if err := json.Unmarshal(raw, &env); err == nil &&
-		len(env.Content) == 1 && env.Content[0].Type == "text" && env.Content[0].Text != "" {
-		inner := env.Content[0].Text
-		if json.Valid([]byte(inner)) {
-			return prettyJSON([]byte(inner))
+	var res mcpResponse
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return res
+	}
+	res.isError = env.IsError
+	if len(env.Content) == 1 && env.Content[0].Type == "text" && env.Content[0].Text != "" {
+		res.singleText = env.Content[0].Text
+		res.isSingle = true
+	}
+	return res
+}
+
+// mcpJSONOutput picks the bytes to emit in JSON mode (no trailing
+// newline). On success, a single-text envelope whose payload is valid
+// JSON unwraps to that payload, so callers can consume the tool result
+// directly instead of double-parsing `.content[0].text`. Everything
+// else — plain-text payloads (output must stay valid JSON), tool
+// errors, non-single-text shapes, or --envelope — emits the canonical
+// envelope untouched.
+func mcpJSONOutput(raw []byte, res mcpResponse, forceEnvelope bool) []byte {
+	if res.isSingle && !res.isError && !forceEnvelope {
+		if inner := bytes.TrimSpace([]byte(res.singleText)); json.Valid(inner) {
+			return inner
 		}
-		return inner
 	}
-	return prettyJSON(raw)
+	return bytes.TrimRight(raw, "\n")
+}
+
+// mcpHumanOutput renders for human (non-JSON) output: pretty-print the
+// unwrapped payload of a single-text envelope (prettyJSON surfaces
+// non-JSON payloads verbatim), otherwise pretty-print the raw body.
+// forceEnvelope (--envelope) skips unwrapping entirely.
+func mcpHumanOutput(raw []byte, res mcpResponse, forceEnvelope bool) string {
+	if forceEnvelope || !res.isSingle {
+		return prettyJSON(raw)
+	}
+	return prettyJSON([]byte(res.singleText))
 }

cmd/mcp_test.go

@@ -19,6 +19,7 @@ func resetMcpFlags() {
 	mcpJSON = false
 	mcpArgs = nil
 	mcpBody = ""
+	mcpEnvelope = false
 	mcpTimeout = 60 * time.Second
 }
 
@@ -163,15 +164,6 @@ func TestExtractDetail(t *testing.T) {
 	}
 }
 
-func TestEnvelopeIsError(t *testing.T) {
-	if !envelopeIsError([]byte(`{"isError":true,"content":[]}`)) {
-		t.Error("expected true")
-	}
-	if envelopeIsError([]byte(`{"ok":true}`)) {
-		t.Error("expected false")
-	}
-}
-
 func TestPrettyJSON(t *testing.T) {
 	out := prettyJSON([]byte(`{"a":1}`))
 	if !strings.Contains(out, "  ") {
@@ -297,9 +289,14 @@ func TestIsDomainOrSubdomain(t *testing.T) {
 // {"content":[{"type":"text","text":"<escaped JSON>"}]}. For human
 // (pretty) output the single text payload should be unwrapped and its
 // inner JSON pretty-printed, instead of showing double-encoded escapes.
-func TestPrettyMCPOutput_UnwrapsSingleTextEnvelope(t *testing.T) {
-	envelope := []byte(`{"content":[{"type":"text","text":"{\"projects\":[\"a\",\"b\"]}"}]}`)
-	out := prettyMCPOutput(envelope)
+// humanOutput parses raw and renders it the way the command's human
+// (non-JSON) path does.
+func humanOutput(raw string, forceEnvelope bool) string {
+	return mcpHumanOutput([]byte(raw), parseMCPResponse([]byte(raw)), forceEnvelope)
+}
+
+func TestMcpHumanOutput_UnwrapsSingleTextEnvelope(t *testing.T) {
+	out := humanOutput(`{"content":[{"type":"text","text":"{\"projects\":[\"a\",\"b\"]}"}]}`, false)
 	if strings.Contains(out, `\"`) {
 		t.Errorf("output still double-encoded: %q", out)
 	}
@@ -312,17 +309,16 @@ func TestPrettyMCPOutput_UnwrapsSingleTextEnvelope(t *testing.T) {
 }
 
 // Inner text that isn't JSON should be surfaced verbatim, not wrapped.
-func TestPrettyMCPOutput_UnwrapsPlainTextEnvelope(t *testing.T) {
-	envelope := []byte(`{"content":[{"type":"text","text":"only for Kubernetes-based environments"}]}`)
-	out := prettyMCPOutput(envelope)
+func TestMcpHumanOutput_UnwrapsPlainTextEnvelope(t *testing.T) {
+	out := humanOutput(`{"content":[{"type":"text","text":"only for Kubernetes-based environments"}]}`, false)
 	if out != "only for Kubernetes-based environments" {
 		t.Errorf("plain-text payload = %q, want unwrapped verbatim", out)
 	}
 }
 
 // A non-envelope payload falls through to ordinary pretty-printing.
-func TestPrettyMCPOutput_NonEnvelopeFallsThrough(t *testing.T) {
-	out := prettyMCPOutput([]byte(`{"integrations":["aws-prod"]}`))
+func TestMcpHumanOutput_NonEnvelopeFallsThrough(t *testing.T) {
+	out := humanOutput(`{"integrations":["aws-prod"]}`, false)
 	if !strings.Contains(out, "  ") {
 		t.Errorf("expected indented JSON, got %q", out)
 	}
@@ -333,14 +329,128 @@ func TestPrettyMCPOutput_NonEnvelopeFallsThrough(t *testing.T) {
 
 // A multi-item content array is not the single-text shape, so it should
 // be left as the raw (pretty-printed) envelope rather than guessing.
-func TestPrettyMCPOutput_MultiContentNotUnwrapped(t *testing.T) {
-	envelope := []byte(`{"content":[{"type":"text","text":"a"},{"type":"text","text":"b"}]}`)
-	out := prettyMCPOutput(envelope)
+func TestMcpHumanOutput_MultiContentNotUnwrapped(t *testing.T) {
+	out := humanOutput(`{"content":[{"type":"text","text":"a"},{"type":"text","text":"b"}]}`, false)
 	if !strings.Contains(out, "content") {
 		t.Errorf("multi-item envelope should fall through to raw pretty, got %q", out)
 	}
 }
 
+// --envelope means "never unwrap" in human mode too.
+func TestMcpHumanOutput_EnvelopeFlag(t *testing.T) {
+	envelope := `{"content":[{"type":"text","text":"{\"a\":1}"}]}`
+	if out := humanOutput(envelope, true); !strings.Contains(out, "content") {
+		t.Errorf("forceEnvelope should preserve the envelope, got %q", out)
+	}
+	if out := humanOutput(envelope, false); strings.Contains(out, "content") {
+		t.Errorf("default human output should unwrap, got %q", out)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// JSON-mode envelope unwrapping
+// ---------------------------------------------------------------------------
+
+func TestParseMCPResponse(t *testing.T) {
+	tests := []struct {
+		name     string
+		raw      string
+		wantText string
+		isSingle bool
+		isError  bool
+	}{
+		{"json inner", `{"content":[{"type":"text","text":"{\"a\":1}"}]}`, `{"a":1}`, true, false},
+		{"plain text inner", `{"content":[{"type":"text","text":"all good"}]}`, "all good", true, false},
+		{"error envelope", `{"isError":true,"content":[{"type":"text","text":"boom"}]}`, "boom", true, true},
+		{"multi item", `{"content":[{"type":"text","text":"a"},{"type":"text","text":"b"}]}`, "", false, false},
+		{"empty content", `{"content":[]}`, "", false, false},
+		{"missing content", `{"isError":false}`, "", false, false},
+		{"non-text item", `{"content":[{"type":"image","text":"x"}]}`, "", false, false},
+		{"empty text", `{"content":[{"type":"text","text":""}]}`, "", false, false},
+		{"non-envelope", `{"integrations":["aws-prod"]}`, "", false, false},
+		{"malformed", `not json`, "", false, false},
+		{"non-string text", `{"content":[{"type":"text","text":42}]}`, "", false, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := parseMCPResponse([]byte(tt.raw))
+			if got.isSingle != tt.isSingle || got.singleText != tt.wantText || got.isError != tt.isError {
+				t.Errorf("parseMCPResponse(%s) = %+v, want {singleText:%q isSingle:%v isError:%v}",
+					tt.raw, got, tt.wantText, tt.isSingle, tt.isError)
+			}
+		})
+	}
+}
+
+func TestMCPJSONOutput(t *testing.T) {
+	jsonEnvelope := `{"content":[{"type":"text","text":"{\"projects\":[\"a\"]}"}]}`
+	proseEnvelope := `{"content":[{"type":"text","text":"deployment succeeded"}]}`
+	errorEnvelope := `{"isError":true,"content":[{"type":"text","text":"{\"detail\":\"boom\"}"}]}`
+	tests := []struct {
+		name          string
+		raw           string
+		forceEnvelope bool
+		want          string
+	}{
+		{"object inner unwrapped", jsonEnvelope, false, `{"projects":["a"]}`},
+		{"bare scalar inner unwrapped", `{"content":[{"type":"text","text":"42"}]}`, false, `42`},
+		{"padded inner trimmed", `{"content":[{"type":"text","text":"\n{\"a\":1}\n"}]}`, false, `{"a":1}`},
+		{"prose inner keeps envelope", proseEnvelope, false, proseEnvelope},
+		{"non-single-text shape passes through", `{"integrations":["aws-prod"]}`, false, `{"integrations":["aws-prod"]}`},
+		{"trailing newline stripped from envelope", proseEnvelope + "\n", false, proseEnvelope},
+		{"isError keeps envelope", errorEnvelope, false, errorEnvelope},
+		{"forceEnvelope keeps envelope", jsonEnvelope, true, jsonEnvelope},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			raw := []byte(tt.raw)
+			got := string(mcpJSONOutput(raw, parseMCPResponse(raw), tt.forceEnvelope))
+			if got != tt.want {
+				t.Errorf("mcpJSONOutput() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// Wiring test: RunE routes the response through mcpJSONOutput with the
+// mcpEnvelope flag (shape rules themselves are pinned by TestMCPJSONOutput).
+func TestMcpCmd_JsonOutputWiring(t *testing.T) {
+	envelope := `{"content":[{"type":"text","text":"{\"projects\":[\"a\"]}"}]}`
+	tests := []struct {
+		name          string
+		forceEnvelope bool
+		want          string
+	}{
+		{"unwraps by default", false, `{"projects":["a"]}` + "\n"},
+		{"--envelope passes through", true, envelope + "\n"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			resetMcpFlags()
+			defer resetMcpFlags()
+			mcpJSON = true
+			mcpEnvelope = tt.forceEnvelope
+
+			seedDefaultProfile(t)
+			orig := callMCP
+			callMCP = func(_, _, _, _ string, _ []byte, _ time.Duration) ([]byte, int, error) {
+				return []byte(envelope), http.StatusOK, nil
+			}
+			defer func() { callMCP = orig }()
+
+			var buf bytes.Buffer
+			mcpCmd.SetOut(&buf)
+			mcpCmd.SetErr(&buf)
+			if err := mcpCmd.RunE(mcpCmd, []string{"cloud_cli", "list_cloud_integrations"}); err != nil {
+				t.Fatalf("RunE err = %v", err)
+			}
+			if got := buf.String(); got != tt.want {
+				t.Errorf("output = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestMcpCmd_HappyPath(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 	t.Setenv("PRAXIS_PROFILE", "")

internal/skillinstall/dummy.go

@@ -144,8 +144,12 @@ holds AWS / kube secrets.
     every ` + "`praxis login`" + ` and ` + "`praxis refresh-skills`" + `. Grep when you
     need tool names without going to the network.
   - **Call**: ` + "`praxis mcp <mcp> <fn> --arg k=v ... --json`" + ` (or
-    ` + "`--body '<json>'`" + ` for nested args). Output is the raw MCP envelope
-    (` + "`{content: [...], isError?: bool}`" + `).
+    ` + "`--body '<json>'`" + ` for nested args). Output is the tool's JSON
+    result directly — the CLI unwraps the MCP envelope when the payload
+    is a single JSON text item. On tool error (exit 1) or non-JSON
+    payloads you get the raw envelope
+    (` + "`{content: [...], isError?: bool}`" + `). Pass ` + "`--envelope`" + ` to
+    always get the raw envelope.
 
 Example flow:
 ` + "```bash" + `