rearchitect resources

Author: lkingland

docs/reference/func_mcp.md

@@ -13,22 +13,30 @@ SYNOPSIS
 
 DESCRIPTION
 	Manages a Model Context Protocol (MCP) server over standard input/output (stdio) transport.
-	This implementation aims to support tools for deploying and creating serverless functions.
+	This server enables AI language models to interact with Knative Functions through the
+	Model Context Protocol.
 
-	Note: This command is still under development.
+	IMPORTANT: This command is designed to be invoked by MCP clients (such as Claude Desktop,
+	Cursor, VS Code, Windsurf, etc.), not run directly by users. The MCP client automatically
+	launches and manages the server based on its configuration.
+
+	For setup instructions and client configuration examples, see:
+	https://github.com/knative/func/blob/main/docs/mcp-integration/integration.md
+
+	Note: This is an EXPERIMENTAL feature. The FUNC_ENABLE_MCP environment variable must be
+	set to "true" for the server to start. See documentation for details.
 
 AVAILABLE COMMANDS
 	start    Start the MCP server
 
 EXAMPLES
 
-	o Start an MCP server:
-		func mcp start
-
-	o Display this help:
-		func mcp
+	o View this help:
 		func mcp --help
 
+	Note: End users should configure their MCP client, not run these commands directly.
+	See the documentation link above for configuration instructions.
+
 
 ### Options
 

docs/reference/func_mcp_start.md

@@ -13,12 +13,34 @@ SYNOPSIS
 
 DESCRIPTION
 	Starts a Model Context Protocol (MCP) server over standard input/output (stdio) transport.
-	This server provides tools for deploying and creating serverless functions.
+	This server provides tools for AI language models to deploy and create Knative serverless
+	functions through the Model Context Protocol.
+
+	IMPORTANT: This command is designed to be invoked by MCP clients (such as Claude Desktop,
+	Cursor, VS Code, Windsurf, etc.), not run directly by users. The MCP client automatically
+	launches this command based on its configuration and manages the server lifecycle.
+
+	PREREQUISITES:
+	- The FUNC_ENABLE_MCP environment variable must be set to "true"
+	- The MCP client must be properly configured
+
+	For detailed setup instructions and client configuration examples, see:
+	https://github.com/knative/func/blob/main/docs/mcp-integration/integration.md
 
 EXAMPLES
 
-	o Start an MCP server:
-		func mcp start
+	This command is typically not run directly. Instead, configure your MCP client with:
+
+	  {
+	    "mcpServers": {
+	      "func-mcp": {
+	        "command": "func",
+	        "args": ["mcp", "start"]
+	      }
+	    }
+	  }
+
+	For complete configuration instructions, see the documentation link above.
 
 
 ```

go.mod

@@ -60,6 +60,7 @@ require (
 	golang.org/x/sync v0.17.0
 	golang.org/x/sys v0.37.0
 	golang.org/x/term v0.36.0
+	golang.org/x/text v0.30.0
 	gopkg.in/yaml.v2 v2.4.0
 	gopkg.in/yaml.v3 v3.0.1
 	gotest.tools/v3 v3.5.2
@@ -286,7 +287,6 @@ require (
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/exp v0.0.0-20250408133849-7e4ce0ab07d0 // indirect
 	golang.org/x/mod v0.29.0 // indirect
-	golang.org/x/text v0.30.0 // indirect
 	golang.org/x/time v0.12.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
 	google.golang.org/api v0.233.0 // indirect

pkg/mcp/mcp.go

@@ -2,6 +2,7 @@ package mcp
 
 import (
 	"context"
+	"os/exec"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -10,6 +11,22 @@ var templateRepos = []string{
 	"https://github.com/functions-dev/templates",
 }
 
+// Executor abstracts command execution for testability
+type Executor interface {
+	Execute(ctx context.Context, dir string, name string, args ...string) ([]byte, error)
+}
+
+// binaryExecutor implements Executor using os/exec
+type binaryExecutor struct{}
+
+func (e binaryExecutor) Execute(ctx context.Context, dir string, name string, args ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, name, args...)
+	if dir != "" {
+		cmd.Dir = dir
+	}
+	return cmd.CombinedOutput()
+}
+
 type Server struct {
 	impl      *mcp.Server
 	prefix    string   // Command prefix to use (e.g., "func" or "kn func")
@@ -26,12 +43,12 @@ type tool interface {
 
 type resource interface {
 	desc() *mcp.Resource
-	handler(prefix string) mcp.ResourceHandler
+	handle(context.Context, *mcp.ReadResourceRequest, string, Executor) (*mcp.ReadResourceResult, error)
 }
 
 type prompt interface {
 	desc() *mcp.Prompt
-	handler(prefix string) mcp.PromptHandler
+	handle(context.Context, *mcp.GetPromptRequest, string) (*mcp.GetPromptResult, error)
 }
 
 type Option func(*Server)
@@ -71,23 +88,22 @@ func New(options ...Option) *Server {
 		},
 		resources: []resource{
 			rootHelpResource{},
-			cmdHelpResource{[]string{"create"}, "func://create/docs"},
-			cmdHelpResource{[]string{"build"}, "func://build/docs"},
-			cmdHelpResource{[]string{"deploy"}, "func://deploy/docs"},
-			cmdHelpResource{[]string{"list"}, "func://list/docs"},
-			cmdHelpResource{[]string{"delete"}, "func://delete/docs"},
-			cmdHelpResource{[]string{"config", "volumes", "add"}, "func://config/volumes/add/docs"},
-			cmdHelpResource{[]string{"config", "volumes", "remove"}, "func://config/volumes/remove/docs"},
-			cmdHelpResource{[]string{"config", "labels", "add"}, "func://config/labels/add/docs"},
-			cmdHelpResource{[]string{"config", "labels", "remove"}, "func://config/labels/remove/docs"},
-			cmdHelpResource{[]string{"config", "envs", "add"}, "func://config/envs/add/docs"},
-			cmdHelpResource{[]string{"config", "envs", "remove"}, "func://config/envs/remove/docs"},
+			cmdHelpResource{[]string{"create"}, "function://help/create"},
+			cmdHelpResource{[]string{"build"}, "function://help/build"},
+			cmdHelpResource{[]string{"deploy"}, "function://help/deploy"},
+			cmdHelpResource{[]string{"list"}, "function://help/list"},
+			cmdHelpResource{[]string{"delete"}, "function://help/delete"},
+			cmdHelpResource{[]string{"config", "volumes", "add"}, "function://help/config/volumes/add"},
+			cmdHelpResource{[]string{"config", "volumes", "remove"}, "function://help/config/volumes/remove"},
+			cmdHelpResource{[]string{"config", "labels", "add"}, "function://help/config/labels/add"},
+			cmdHelpResource{[]string{"config", "labels", "remove"}, "function://help/config/labels/remove"},
+			cmdHelpResource{[]string{"config", "envs", "add"}, "function://help/config/envs/add"},
+			cmdHelpResource{[]string{"config", "envs", "remove"}, "function://help/config/envs/remove"},
+			currentFunctionResource{},
 			templatesResource{},
 		},
 		prompts: []prompt{
-			helpPrompt{},
-			cmdHelpPrompt{},
-			listTemplatesPrompt{},
+			createFunctionPrompt{},
 		},
 	}
 
@@ -100,11 +116,11 @@ func New(options ...Option) *Server {
 	}
 
 	for _, resource := range s.resources {
-		s.impl.AddResource(resource.desc(), resource.handler(s.prefix))
+		s.impl.AddResource(resource.desc(), withResourcePrefix(s.prefix, s.executor, resource.handle))
 	}
 
 	for _, prompt := range s.prompts {
-		s.impl.AddPrompt(prompt.desc(), prompt.handler(s.prefix))
+		s.impl.AddPrompt(prompt.desc(), withPromptPrefix(s.prefix, prompt.handle))
 	}
 
 	return s

pkg/mcp/mcp_test.go

@@ -109,21 +109,54 @@ func TestStart(t *testing.T) {
 		}
 	}
 
-	// List resources - should have all 13 registered resources
+	// List resources - should have all 14 registered resources
 	resourcesResult, err := clientSession.ListResources(ctx, &mcp.ListResourcesParams{})
 	if err != nil {
 		t.Fatalf("failed to list resources: %v", err)
 	}
-	if len(resourcesResult.Resources) != 13 {
-		t.Errorf("expected 13 resources, got %d", len(resourcesResult.Resources))
+	if len(resourcesResult.Resources) != 14 {
+		t.Errorf("expected 14 resources, got %d", len(resourcesResult.Resources))
+	}
+
+	// Verify new resource URIs are present
+	expectedURIs := map[string]bool{
+		"function://current":                      false,
+		"function://help/root":                    false,
+		"function://help/create":                  false,
+		"function://help/build":                   false,
+		"function://help/deploy":                  false,
+		"function://help/list":                    false,
+		"function://help/delete":                  false,
+		"function://help/config/volumes/add":      false,
+		"function://help/config/volumes/remove":   false,
+		"function://help/config/labels/add":       false,
+		"function://help/config/labels/remove":    false,
+		"function://help/config/envs/add":         false,
+		"function://help/config/envs/remove":      false,
+		"function://templates":                    false,
+	}
+	for _, resource := range resourcesResult.Resources {
+		if _, ok := expectedURIs[resource.URI]; ok {
+			expectedURIs[resource.URI] = true
+		}
+	}
+	for uri, found := range expectedURIs {
+		if !found {
+			t.Errorf("expected resource URI %q not found in resources list", uri)
+		}
 	}
 
-	// List prompts - should have all 3 registered prompts
+	// List prompts - should have the workflow prompt
 	promptsResult, err := clientSession.ListPrompts(ctx, &mcp.ListPromptsParams{})
 	if err != nil {
 		t.Fatalf("failed to list prompts: %v", err)
 	}
-	if len(promptsResult.Prompts) != 3 {
-		t.Errorf("expected 3 prompts, got %d", len(promptsResult.Prompts))
+	if len(promptsResult.Prompts) != 1 {
+		t.Errorf("expected 1 prompt, got %d", len(promptsResult.Prompts))
+	}
+
+	// Verify the workflow prompt is registered
+	if len(promptsResult.Prompts) > 0 && promptsResult.Prompts[0].Name != "create_function" {
+		t.Errorf("expected prompt name 'create_function', got %q", promptsResult.Prompts[0].Name)
 	}
 }