more context for better responses

Author: jahvon

internal/mcp/prompts.go

@@ -207,7 +207,6 @@ func createWorkspacePrompt(_ context.Context, request mcp.GetPromptRequest) (*mc
 	name := getArgOrDefault(args, "name", "my-project")
 	projectType := getArgOrDefault(args, "type", "web")
 	techStack := getArgOrDefault(args, "tech_stack", "")
-
 	prompt := fmt.Sprintf(`I want to set up a new Flow workspace for a %s project:
 
 **Project Details:**

internal/mcp/resources.go

@@ -16,64 +16,81 @@ import (
 )
 
 var (
-	//go:embed resources/info.md
-	infoMD string
+	//go:embed resources/concepts-guide.md
+	conceptsMD string
+
+	//go:embed resources/file-types-guide.md
+	fileTypesMD string
 
 	//go:embed resources/flowfile_schema.json
 	flowFileSchema string
 
+	//go:embed resources/template_schema.json
+	templateSchema string
+
 	//go:embed resources/workspace_schema.json
 	workspaceSchema string
-
-	flowFileSchemaURI        = "flow://schema/flowfile"
-	workspaceConfigSchemaURI = "flow://schema/workspace"
 )
 
 func addServerResources(srv *server.MCPServer) {
 	getCtx := mcp.NewResource(
 		"flow://context/current",
 		"context",
 		mcp.WithResourceDescription("Current flow execution context (workspace, namespace, vault)"),
-		mcp.WithMIMEType("application/json"),
-	)
+		mcp.WithMIMEType("application/json"))
 	srv.AddResource(getCtx, getContextResourceHandler)
 
 	getWorkspace := mcp.NewResourceTemplate(
 		"flow://workspace/{name}",
 		"workspace",
-		mcp.WithTemplateDescription("Flow workspace configuration and details"),
-	)
+		mcp.WithTemplateDescription("Flow workspace configuration and details"))
 	srv.AddResourceTemplate(getWorkspace, getWorkspaceResourceHandler)
 
 	getWorkspaceExecutables := mcp.NewResourceTemplate(
 		"flow://workspace/{name}/executables",
 		"workspace_executables",
-		mcp.WithTemplateDescription("Flow executables for a given workspace"),
-	)
+		mcp.WithTemplateDescription("Flow executables for a given workspace"))
 	srv.AddResourceTemplate(getWorkspaceExecutables, getWorkspaceExecutablesHandler)
 
-	getFlowInfo := mcp.NewResource(
-		"flow://info",
-		"flow_info",
-		mcp.WithResourceDescription("Information about Flow and it's usage"),
-		mcp.WithMIMEType("text/markdown"),
-	)
-	srv.AddResource(getFlowInfo, getFlowInfoResourceHandler)
+	getExecutable := mcp.NewResourceTemplate(
+		"flow://executable/{ref}",
+		"executable",
+		mcp.WithTemplateDescription("Flow executable details by reference"))
+	srv.AddResourceTemplate(getExecutable, getExecutableResourceHandler)
+
+	getFlowConcepts := mcp.NewResource(
+		"flow://guide/concepts",
+		"flow_concepts",
+		mcp.WithResourceDescription("Information about flow and it's usage"),
+		mcp.WithMIMEType("text/markdown"))
+	srv.AddResource(getFlowConcepts, getFlowConceptsResourceHandler)
+
+	getFlowFileTypes := mcp.NewResource(
+		"flow://guide/file-types",
+		"flow_file_types",
+		mcp.WithResourceDescription("Information about flow file types and their usage"),
+		mcp.WithMIMEType("text/markdown"))
+	srv.AddResource(getFlowFileTypes, getFlowFileTypesResourceHandler)
 
 	getFlowFileSchema := mcp.NewResource(
-		flowFileSchemaURI,
+		"flow://schema/flowfile",
 		"flowfile_schema",
 		mcp.WithResourceDescription("Flow file (*.flow, *.flow.yaml, *.flow.yml) schema"),
-		mcp.WithMIMEType("application/json"),
-	)
+		mcp.WithMIMEType("application/json"))
 	srv.AddResource(getFlowFileSchema, getFlowFileSchemaResourceHandler)
 
+	getTemplateSchema := mcp.NewResource(
+		"flow://schema/template",
+		"template_schema",
+		mcp.WithResourceDescription("Flow template (*.flow.tmpl, *.flow.yaml.tmpl, *.flow.yml.tmpl) schema"),
+		mcp.WithMIMEType("application/json"))
+	srv.AddResource(getTemplateSchema, getTemplateSchemaResourceHandler)
+
 	getWorkspaceSchema := mcp.NewResource(
-		workspaceConfigSchemaURI,
+		"flow://schema/workspace",
 		"workspace_schema",
 		mcp.WithResourceDescription("Flow workspace configuration (flow.yaml) schema"),
-		mcp.WithMIMEType("application/json"),
-	)
+		mcp.WithMIMEType("application/json"))
 	srv.AddResource(getWorkspaceSchema, getWorkspaceSchemaResourceHandler)
 }
 
@@ -152,26 +169,49 @@ func getWorkspaceExecutablesHandler(_ context.Context, request mcp.ReadResourceR
 	}, nil
 }
 
-func extractWsName(uri string) (string, error) {
-	// Assuming the URI is in the format "flow://workspace/{name}" or "flow://workspace/{name}/executables"
-	if len(uri) < len("flow://workspace/") {
-		return "", fmt.Errorf("invalid workspace URI: %s", uri)
+func getExecutableResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
+	executableVerb, executableID, err := extractExecutableRef(request.Params.URI)
+	if err != nil {
+		return nil, err
 	}
 
-	wsName := uri[len("flow://workspace/"):]
-	strings.TrimSuffix(wsName, "/executables")
-	if wsName == "" {
-		return "", fmt.Errorf("workspace name cannot be empty in URI: %s", uri)
+	cmdArgs := []string{"browse", "--output", "json", executableVerb}
+	if executableID != "" {
+		cmdArgs = append(cmdArgs, executableID)
 	}
-	return wsName, nil
+	cmd := exec.Command("flow", cmdArgs...)
+
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		ref := strings.Join([]string{executableVerb, executableID}, " ")
+		return nil, fmt.Errorf("%s executable details retrieval failed: %s", ref, output)
+	}
+
+	return []mcp.ResourceContents{
+		mcp.TextResourceContents{
+			URI:      request.Params.URI,
+			MIMEType: "application/json",
+			Text:     string(output),
+		},
+	}, nil
+}
+
+func getFlowConceptsResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
+	return []mcp.ResourceContents{
+		mcp.TextResourceContents{
+			URI:      request.Params.URI,
+			MIMEType: "text/markdown",
+			Text:     conceptsMD,
+		},
+	}, nil
 }
 
-func getFlowInfoResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
+func getFlowFileTypesResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
 	return []mcp.ResourceContents{
 		mcp.TextResourceContents{
 			URI:      request.Params.URI,
 			MIMEType: "text/markdown",
-			Text:     infoMD,
+			Text:     fileTypesMD,
 		},
 	}, nil
 }
@@ -186,6 +226,16 @@ func getFlowFileSchemaResourceHandler(_ context.Context, request mcp.ReadResourc
 	}, nil
 }
 
+func getTemplateSchemaResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
+	return []mcp.ResourceContents{
+		mcp.TextResourceContents{
+			URI:      request.Params.URI,
+			MIMEType: "application/json",
+			Text:     templateSchema,
+		},
+	}, nil
+}
+
 func getWorkspaceSchemaResourceHandler(_ context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
 	return []mcp.ResourceContents{
 		mcp.TextResourceContents{
@@ -195,3 +245,38 @@ func getWorkspaceSchemaResourceHandler(_ context.Context, request mcp.ReadResour
 		},
 	}, nil
 }
+
+func extractWsName(uri string) (string, error) {
+	// Assuming the URI is in the format "flow://workspace/{name}" or "flow://workspace/{name}/executables"
+	if len(uri) < len("flow://workspace/") {
+		return "", fmt.Errorf("invalid workspace URI: %s", uri)
+	}
+
+	wsName := uri[len("flow://workspace/"):]
+	strings.TrimSuffix(wsName, "/executables")
+	if wsName == "" {
+		return "", fmt.Errorf("workspace name cannot be empty in URI: %s", uri)
+	}
+	return wsName, nil
+}
+
+func extractExecutableRef(uri string) (string, string, error) {
+	if len(uri) < len("flow://executable/") {
+		return "", "", fmt.Errorf("invalid executable URI: %s", uri)
+	}
+
+	ref := uri[len("flow://executable/"):]
+	if ref == "" {
+		return "", "", fmt.Errorf("executable reference cannot be empty in URI: %s", uri)
+	}
+
+	parts := strings.SplitN(ref, " ", 2)
+	switch len(parts) {
+	case 1:
+		return parts[0], "", nil
+	case 2:
+		return parts[0], parts[1], nil
+	default:
+		return "", "", fmt.Errorf("invalid executable reference format in URI: %s", uri)
+	}
+}

internal/mcp/resources/info.md internal/mcp/resources/concepts-guide.mdinternal/mcp/resources/info.md renamed to internal/mcp/resources/concepts-guide.md

@@ -1,10 +1,12 @@
-# Flow Platform Concepts Guide
+# Flow Concepts Guide
 
 ## What is flow?
 
 flow is a local-first, customizable CLI automation platform designed to streamline development and operations workflows. 
 It helps developers organize, discover, and execute tasks across projects through a unified interface.
 
+More comprehensive details can be found in the [flow documentation](https://flowexec.io).
+
 ## Core Philosophy
 
 - **Local-First**: All data and execution happens on your machine
@@ -40,6 +42,16 @@ executables:
           text: production
 ```
 
+#### Executable References
+Executables are identified by its reference: combination of **Verb** and **ID**. The  ID is in the form `<workspace>/<namespace>:<name>`.
+A full reference must be unique across all registered workspaces.
+
+For instance:
+- `build app` - current workspace, root namespace
+- `build backend/app` - current workspace, backend namespace
+- `build my-project/backend:app` - specific workspace and namespace
+- `build` - current workspace, root namespace, no name set
+
 ### Verbs
 **Verbs** describe what action an executable performs. Flow groups related verbs together, allowing natural language-like commands.
 By default, flow provide the following verb alias groups:
@@ -57,41 +69,27 @@ Users can invoke executables using any verb using the CLI (e.g. `flow build app`
 ### Workspaces
 **Workspaces** are project containers that organize related executables. Each workspace:
 - Has a root directory containing the workspace configuration file (`flow.yaml`)
-- Flow files can be located anywhere within the workspace directory
 - Can contain multiple namespaces (defined in flow files)
 - Provides isolation between projects
 
-**Example workspace structure:**
-```
-my-project/
-├── flow.yaml           # Workspace config
-├── backend.flow        # Backend executables
-├── frontend.flow       # Frontend executables  
-└── deployment/
-    └── k8s.flow       # Deployment executables
-```
-
 ### Namespaces
 **Namespaces** provide logical grouping within workspaces. They help organize executables by:
 - Feature area (auth, payments, notifications)
 - Environment (dev, staging, production)
 - Technology stack (backend, frontend, mobile)
 - Team ownership (platform, product, data)
 
-**Referencing executables:**
-- `VERB app` - current workspace, root namespace
-- `VERB backend/app` - current workspace, backend namespace
-- `VERB my-project/backend:app` - specific workspace and namespace
 
 Executable names are optional. When not specified, the verb is used as the identifier, 
 e.g. `flow build` refers to the executable with the verb "build" in the current workspace.
 
-### Flow Files
+### Executable Definitions (Flow Files)
 **Flow files** (`.flow`, `.flow.yaml`, `.flow.yml`) are YAML configuration files that define executables. They support:
 - Multiple executables per file
 - Shared metadata (namespace, tags, descriptions)
 - Environment variable management
 - Conditional execution logic
+- Can be located anywhere within the workspace directory
 
 ### Secrets and Vaults
 **Vaults** provide secure secret storage with multiple encryption backends:
@@ -110,7 +108,27 @@ Executables reference secrets using `secretRef` parameters, keeping sensitive da
 
 ## Execution Model
 
-### Command Structure
+### Sync
+
+Anytime a new workspace is registered, an executable is added, or it's identifier changes, flow state will need to be synchronized.
+This ensures that the latest workspace and executable definitions are available in the cache for execution.
+This can be done using the `flow sync` command or with the `--sync` flag on any command.
+
+### Management Commands
+
+Flow provides a set of management commands to interact with workspaces, executables, and configurations:
+```bash
+flow config # Manage flow's user configuration (get, set, reset)
+flow workspace # Manage workspaces (add, get, switch, list, remove)
+flow browse # Discover executables (interactive TUI)
+flow vault # Manage secrets and vaults (create, edit, get, list, remove, switch)
+flow cache # Manage cache data (get, set, remove, list, clear)
+flow secret # Manage secrets (get, list, remove, set)
+flow template # Manage templates (add, generate, get, list)
+flow logs # View execution logs
+```
+
+### Execution Command Structure
 ```bash
 flow <verb> <reference> [arguments] [flags]
 ```
@@ -129,16 +147,19 @@ serial:
       cmd: brew install mytool
     - if: env["CI"] == "true"  
       cmd: run-ci-specific-setup
-    - if: len(store["build-id"]) > 0
+    - if: len(store["build-id"]) > 0 # checks the cache for a build ID key
       cmd: use-cached-build
 ```
 
 ### State Management
 flow provides state persistence through:
-- **Cache**: Key-value store for sharing data between executables
+- **Cache**: Key-value store for sharing data between executables. State is only persisted during execution 
+  - Use `flow cache set KEY VALUE` and `flow cache get KEY` to manage cache entries within executable scripts
+  - Users can also manage global keys outside the execution context using `flow cache` commands
 - **Context variables**: OS, architecture, workspace, and path information
-- **Environment inheritance**: Variables flow from parent to child executables
-- **Temporary directories**: Isolated scratch space for executable runs (set the `dir` to `f:tmp`)
+- **Environment inheritance**: Variables (`params` and `args`) flow from parent to child executables (for serial and parallel)
+- **Temporary directories**: Isolated scratch space for executable runs
+  - A temporary directory is created for the execution when the executable's `dir` is set to `f:tmp`)
 
 ## Workflow Patterns