feat(mcp): praxis mcp listing + ~/.praxis/mcp-tools.json snapshot (v0.6.0) (#2)

feat(mcp): praxis mcp listing + ~/.praxis/mcp-tools.json snapshot (v0.6.0)

Adds tool discovery for AI hosts that drive the CLI:

- Live: `praxis mcp` (no args) hits GET /ai-api/v1/mcp/manifest and pretty-prints, or --json for AI hosts. Authoritative, always fresh.
- Snapshot: ~/.praxis/mcp-tools.json rewritten by `praxis install-skill` and `praxis refresh-skills` after catalog pull. AI hosts grep this file when they want tool names without a network call. Soft-skipped when not logged in.
- Praxis meta-skill body and per-skill execution preamble both gain a Discovery section pointing at these two paths.

Server side: agent-factory PR #1048 adds GET /ai-api/v1/mcp/manifest. Each registered dispatcher exposes describe() returning per-function FunctionSpec (description + ArgSpec list); names mirror the in-process MCP exactly so seeded skill content keeps working.

Includes CodeRabbit fixes: Fetch handles non-positive timeouts (defaults instead of disabling deadline) and explicitly checks resp.Body.Close error, matching WriteSnapshot's strict close-error pattern.

Author: anshulsao

CHANGELOG.md

@@ -6,7 +6,41 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-(Empty — see 0.5.0 below.)
+(Empty — see 0.6.0 below.)
+
+## [0.6.0] — 2026-05-07
+
+### Added
+- `praxis mcp` (no args) — list every MCP namespace and function the
+  gateway exposes, including each function's description and arg shape.
+  Use `--json` for AI-host-friendly output. Live fetch from
+  `/ai-api/v1/mcp/manifest`.
+- `~/.praxis/mcp-tools.json` snapshot — written automatically by
+  `praxis install-skill` and `praxis refresh-skills` after the skill
+  catalog pull. AI hosts can grep this file for available tool names
+  without making a network call. Soft-skipped when not logged in (live
+  `praxis mcp` still works as a fallback).
+- New `internal/mcpmanifest` package — `Fetch()` and `WriteSnapshot()`
+  helpers, separated so both `cmd/mcp.go` (live) and `cmd/skill.go`
+  (snapshot) can reuse them.
+- `paths.MCPTools()` — canonical location for the snapshot.
+- Discovery section added to the praxis meta-skill body, teaching AI
+  hosts to use `praxis mcp --json` (live) and the snapshot file (cached).
+- Skill execution preamble extended with the same discovery hint, so
+  every server-fetched org skill inherits the rule too.
+
+### Changed
+- `praxis refresh-skills` now also re-fetches the MCP tool manifest and
+  rewrites the snapshot. Pre-0.6 behavior (just rewriting SKILL.md
+  files) is preserved when not logged in.
+
+### Server (agent-factory)
+- `GET /ai-api/v1/mcp/manifest` — new gateway route, API-key
+  authenticated. Returns `{mcps: {<mcp>: {<fn>: {description, args}}}}`
+  by introspecting registered dispatchers.
+- Each dispatcher now exposes `describe()` returning per-function
+  `FunctionSpec` (description + `ArgSpec` list). Names mirror the
+  in-process MCP exactly so seeded skill content works verbatim.
 
 ## [0.5.0] — 2026-05-07
 

cmd/mcp.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/Facets-cloud/praxis-cli/internal/credentials"
 	"github.com/Facets-cloud/praxis-cli/internal/exitcode"
+	"github.com/Facets-cloud/praxis-cli/internal/mcpmanifest"
 	"github.com/Facets-cloud/praxis-cli/internal/render"
 	"github.com/spf13/cobra"
 )
@@ -33,26 +34,31 @@ func init() {
 }
 
 var mcpCmd = &cobra.Command{
-	Use:   "mcp <mcp> <fn>",
-	Short: "Invoke a server-side MCP tool function",
-	Long: `Call an MCP tool function exposed by the Praxis server gateway.
+	Use:   "mcp [<mcp> <fn>]",
+	Short: "List or invoke server-side MCP tool functions",
+	Long: `Call an MCP tool function exposed by the Praxis server gateway,
+or — with no arguments — list every function the gateway exposes.
 
 The CLI never holds AWS / kube / terraform credentials — the server
 resolves the org from your API key and runs the call under the
 org-managed integration credentials.
 
 Examples:
+  praxis mcp                                            # list every mcp + fn
+  praxis mcp --json                                     # same, JSON for AI hosts
   praxis mcp cloud_cli list_cloud_integrations
   praxis mcp cloud_cli run_cloud_cli --arg integration_name=aws-prod --arg command='ec2 describe-instances --output json'
   echo '{"integration_name":"aws-prod","command":"ec2 describe-regions"}' | praxis mcp cloud_cli run_cloud_cli --body -`,
-	Args: cobra.ExactArgs(2),
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) == 0 || len(args) == 2 {
+			return nil
+		}
+		return fmt.Errorf("accepts either 0 args (list manifest) or 2 args (<mcp> <fn>); got %d", len(args))
+	},
 	RunE: func(cmd *cobra.Command, args []string) error {
 		out := cmd.OutOrStdout()
 		asJSON := render.UseJSON(mcpJSON, false, out)
 
-		mcpName := args[0]
-		fnName := args[1]
-
 		active, err := credentials.ResolveActive("")
 		if err != nil {
 			return err
@@ -65,6 +71,14 @@ Examples:
 			os.Exit(exitcode.Auth)
 		}
 
+		// No args → list manifest.
+		if len(args) == 0 {
+			return runManifestList(out, asJSON, active)
+		}
+
+		mcpName := args[0]
+		fnName := args[1]
+
 		body, err := buildMCPBody(mcpArgs, mcpBody, cmd.InOrStdin())
 		if err != nil {
 			render.PrintError(out, asJSON,
@@ -180,6 +194,117 @@ func buildMCPBody(argFlags []string, bodyFlag string, stdin io.Reader) ([]byte,
 	return json.Marshal(obj)
 }
 
+// runManifestList fetches /v1/mcp/manifest, prints either JSON (AI host
+// friendly) or a human-readable grouped listing. Exits the process on
+// network/auth errors so the rest of the dispatch RunE doesn't run.
+//
+// HTTP-level errors come back from mcpmanifest.Fetch as a Go error rather
+// than (status, body) since the manifest endpoint has only one success
+// shape. We classify the error string to pick an exit code; if the user
+// wants the structured detail they can pipe `praxis mcp --json` through
+// jq instead.
+func runManifestList(out io.Writer, asJSON bool, active credentials.Active) error {
+	raw, err := mcpmanifest.Fetch(active.Profile.URL, active.Profile.Token, mcpTimeout)
+	if err != nil {
+		// Auth-failure shape from Fetch: "manifest fetch returned HTTP 401: ..."
+		errStr := err.Error()
+		if strings.Contains(errStr, "HTTP 401") || strings.Contains(errStr, "HTTP 403") {
+			render.PrintError(out, asJSON,
+				errStr,
+				"the API key may be missing or revoked; run `praxis login --profile "+active.Name+"`",
+				exitcode.Auth)
+			os.Exit(exitcode.Auth)
+		}
+		if strings.Contains(errStr, "HTTP 404") {
+			render.PrintError(out, asJSON,
+				errStr,
+				"the gateway does not expose /v1/mcp/manifest — server may be older than CLI",
+				exitcode.NoConfig)
+			os.Exit(exitcode.NoConfig)
+		}
+		render.PrintError(out, asJSON,
+			errStr,
+			"check the deployment URL and network connectivity",
+			exitcode.Network)
+		os.Exit(exitcode.Network)
+	}
+
+	if asJSON {
+		_, _ = out.Write(append(bytes.TrimRight(raw, "\n"), '\n'))
+		return nil
+	}
+	return printManifestPretty(out, raw)
+}
+
+// printManifestPretty renders a grouped human listing. Tolerant of
+// missing/extra fields — server contract may evolve.
+func printManifestPretty(out io.Writer, raw []byte) error {
+	var manifest struct {
+		Mcps map[string]map[string]struct {
+			Description string `json:"description"`
+			Args        []struct {
+				Name        string `json:"name"`
+				Required    bool   `json:"required"`
+				Description string `json:"description"`
+				Type        string `json:"type"`
+			} `json:"args"`
+		} `json:"mcps"`
+	}
+	if err := json.Unmarshal(raw, &manifest); err != nil {
+		// Server returned something we can't parse — fall back to raw.
+		fmt.Fprintln(out, prettyJSON(raw))
+		return nil
+	}
+	if len(manifest.Mcps) == 0 {
+		fmt.Fprintln(out, "(no MCPs registered on this gateway)")
+		return nil
+	}
+
+	mcpNames := make([]string, 0, len(manifest.Mcps))
+	for name := range manifest.Mcps {
+		mcpNames = append(mcpNames, name)
+	}
+	sortStrings(mcpNames)
+
+	for i, mcpName := range mcpNames {
+		if i > 0 {
+			fmt.Fprintln(out)
+		}
+		fmt.Fprintf(out, "%s\n", mcpName)
+		fns := manifest.Mcps[mcpName]
+		fnNames := make([]string, 0, len(fns))
+		for name := range fns {
+			fnNames = append(fnNames, name)
+		}
+		sortStrings(fnNames)
+		for _, fnName := range fnNames {
+			fn := fns[fnName]
+			fmt.Fprintf(out, "  %s\n", fnName)
+			if fn.Description != "" {
+				fmt.Fprintf(out, "    %s\n", fn.Description)
+			}
+			for _, a := range fn.Args {
+				marker := " "
+				if a.Required {
+					marker = "*"
+				}
+				fmt.Fprintf(out, "    %s %s — %s\n", marker, a.Name, a.Description)
+			}
+		}
+	}
+	fmt.Fprintln(out, "\n(* = required arg)")
+	return nil
+}
+
+// sortStrings is a tiny dependency-free sort to keep the list deterministic.
+func sortStrings(s []string) {
+	for i := 1; i < len(s); i++ {
+		for j := i; j > 0 && s[j-1] > s[j]; j-- {
+			s[j-1], s[j] = s[j], s[j-1]
+		}
+	}
+}
+
 // callMCP is the HTTP seam — tests swap it to avoid hitting the network.
 var callMCP = func(baseURL, token, mcp, fn string, body []byte, timeout time.Duration) ([]byte, int, error) {
 	if baseURL == "" {

cmd/mcp_test.go

@@ -3,12 +3,14 @@ package cmd
 import (
 	"bytes"
 	"encoding/json"
+	"errors"
 	"net/http"
 	"strings"
 	"testing"
 	"time"
 
 	"github.com/Facets-cloud/praxis-cli/internal/credentials"
+	"github.com/Facets-cloud/praxis-cli/internal/mcpmanifest"
 )
 
 func resetMcpFlags() {
@@ -167,3 +169,116 @@ func TestMcpCmd_HappyPath(t *testing.T) {
 		t.Errorf("output missing tool result: %s", buf.String())
 	}
 }
+
+// ---------------------------------------------------------------------------
+// `praxis mcp` (no args) — list manifest
+// ---------------------------------------------------------------------------
+
+func TestPrintManifestPretty_PopulatedManifest(t *testing.T) {
+	manifest := []byte(`{"mcps":{"k8s_cli":{"run_k8s_cli":{"description":"run kubectl","args":[{"name":"command","required":true,"description":"the kubectl command","type":"string"},{"name":"namespace","required":false,"description":"override namespace","type":"string"}]}}}}`)
+	var buf bytes.Buffer
+	if err := printManifestPretty(&buf, manifest); err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	out := buf.String()
+	for _, want := range []string{"k8s_cli", "run_k8s_cli", "run kubectl", "command", "namespace", "* = required arg"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output missing %q\n--- got ---\n%s", want, out)
+		}
+	}
+	// Required marker should appear next to `command`, not `namespace`.
+	idxCmd := strings.Index(out, "command —")
+	idxNs := strings.Index(out, "namespace —")
+	if idxCmd < 0 || idxNs < 0 {
+		t.Fatalf("missing arg lines in output:\n%s", out)
+	}
+	// Check the rune before "command —": should be '*'.
+	if !strings.Contains(out[max0(idxCmd-3):idxCmd], "*") {
+		t.Errorf("command should be marked required (* prefix); got %s", out[max0(idxCmd-3):idxCmd])
+	}
+	if strings.Contains(out[max0(idxNs-3):idxNs], "*") {
+		t.Errorf("namespace should NOT be marked required")
+	}
+}
+
+func max0(i int) int {
+	if i < 0 {
+		return 0
+	}
+	return i
+}
+
+func TestMcpCmd_NoArgs_JsonPassthrough(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	t.Setenv("PRAXIS_PROFILE", "")
+	resetMcpFlags()
+	defer resetMcpFlags()
+
+	if err := credentials.Put("default", credentials.Profile{
+		URL: "https://x.test", Username: "u@x.com", Token: "sk_test_T",
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	manifest := []byte(`{"mcps":{"cloud_cli":{}}}`)
+	orig := mcpmanifest.Fetch
+	mcpmanifest.Fetch = func(_, _ string, _ time.Duration) ([]byte, error) {
+		return manifest, nil
+	}
+	defer func() { mcpmanifest.Fetch = orig }()
+
+	mcpJSON = true
+	var buf bytes.Buffer
+	mcpCmd.SetOut(&buf)
+	mcpCmd.SetErr(&buf)
+	if err := mcpCmd.RunE(mcpCmd, []string{}); err != nil {
+		t.Fatalf("RunE err = %v", err)
+	}
+	if got := strings.TrimSpace(buf.String()); got != strings.TrimSpace(string(manifest)) {
+		t.Errorf("--json output mismatch:\n got: %q\nwant: %q", got, manifest)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Args validator: 1 positional arg is invalid (must be 0 or 2)
+// ---------------------------------------------------------------------------
+
+func TestMcpCmd_OneArg_Rejected(t *testing.T) {
+	if err := mcpCmd.Args(mcpCmd, []string{"k8s_cli"}); err == nil {
+		t.Fatal("expected error for 1 arg, got nil")
+	}
+	if err := mcpCmd.Args(mcpCmd, []string{}); err != nil {
+		t.Errorf("0 args should be valid: %v", err)
+	}
+	if err := mcpCmd.Args(mcpCmd, []string{"a", "b"}); err != nil {
+		t.Errorf("2 args should be valid: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pretty-printer tolerates malformed/empty manifest gracefully
+// ---------------------------------------------------------------------------
+
+func TestPrintManifestPretty_EmptyMcps(t *testing.T) {
+	var buf bytes.Buffer
+	if err := printManifestPretty(&buf, []byte(`{"mcps":{}}`)); err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if !strings.Contains(buf.String(), "no MCPs registered") {
+		t.Errorf("output missing empty-state message: %s", buf.String())
+	}
+}
+
+func TestPrintManifestPretty_MalformedFallsBackToRaw(t *testing.T) {
+	var buf bytes.Buffer
+	if err := printManifestPretty(&buf, []byte("not json")); err != nil {
+		t.Fatalf("err = %v", err)
+	}
+	if !strings.Contains(buf.String(), "not json") {
+		t.Errorf("output should contain raw fallback: %s", buf.String())
+	}
+}
+
+// Sanity check on the testing seam — referenced once so the import isn't
+// flagged as unused if all the tests above are temporarily disabled.
+var _ = errors.New