feat: Overhaul MCP server for 2025-11-25 spec and add llms.txt doc (#386)

Refactors the MCP server to conform to current MCP spec best practices
and adds an
llmstxt.org-style docs index so AI clients can pull documentation on
demand rather
than having it pre-baked into tool responses.

MCP server
- Upgrade mcp-go v0.43.2 -> v0.47.1
- Declare listChanged on tool/resource capabilities and subscribe on
resources
- Add WithOutputSchema on every tool using new Go output structs
- Cursor-based pagination (opaque base64 offsets) on list_workspaces,
  list_executables, get_execution_logs
- Structured error responses with machine-readable codes (INVALID_INPUT,
  NOT_FOUND, EXECUTION_FAILED, CANCELLED, VALIDATION_FAILED, etc.)
- Progress notifications and context cancellation for
execute/sync_executables
- New MCP resources: flow://workspace/{name},
flow://executable/{ws}/{ns}/{name},
  flow://flowfile/{path}, flow://logs/{run-id}
- Emit resources/list_changed after switch_workspace, sync_executables,
and
  write_flowfile
- New tools: write_flowfile (YAML-validated flowfile authoring) and
  get_workspace_config
- Split tools.go into tools_workspace.go / tools_executable.go /
tools_system.go
- Extend CommandExecutor with ExecuteContext for cancellation support

get_info slimdown
- Dropped embedded concepts/file-types markdown and JSON schemas (~20KB)
- Returns compact summary, docsUrl, llmsTxtUrl, schemaUrls, guideUrls
instead
- Removed the now-unused MCP resource copies and the docsgen path that
produced
  them

Docs
- Add docs/public/llms.txt following the llmstxt.org format
- Add docs/public/robots.txt pointing at the sitemap
- Enable VitePress built-in sitemap generation
- Update server-instructions.md to describe the new get_info shape and
point
  agents at llmsTxtUrl / schemaUrls / guideUrls

Tests
- New pagination unit tests (empty, first/middle/last page, invalid
cursor,
  cursor past end, round-trip)
- New Ginkgo specs: resource template registration, output schema
presence,
structured error responses, write_flowfile (valid/invalid
extension/invalid
  YAML/exists/overwrite), list_executables pagination

Author: jahvon

docs/.vitepress/config.mts

@@ -8,6 +8,10 @@ export default defineConfig({
   base: '/',
   outDir: './dist',
 
+  sitemap: {
+    hostname: 'https://flowexec.io'
+  },
+
   head: [
     ['link', { rel: 'icon', href: '/favicon.ico' }]
   ],

docs/public/llms.txt

@@ -0,0 +1,124 @@
+# Flow
+
+> Flow is a local-first automation platform that helps you organize and execute any kind of workflow through declarative YAML. It provides a CLI, an interactive TUI, secret management via vaults, templating for code generation, and an MCP server for AI-agent integration.
+
+Flow organizes automation into **workspaces** (projects/domains), each rooted at a `flow.yaml` config file. Inside a workspace, **executables** are declared in `*.flow` (or `*.flow.yaml`) files and run by invoking a **verb** (e.g. `run`, `build`, `test`, `deploy`) optionally combined with a `workspace/namespace:name` reference. Executables can be simple commands, HTTP requests, or orchestrated serial/parallel pipelines. **Templates** (`*.flow.tmpl`) generate new workflows interactively.
+
+## Getting Started
+
+- [Home](https://flowexec.io/): Landing page with feature overview
+- [Installation](https://flowexec.io/installation): Install flow on macOS, Linux, or Windows
+- [Quick Start](https://flowexec.io/quickstart): Five-minute walkthrough from install to first executable
+
+## Core Guides
+
+- [Guides Overview](https://flowexec.io/guides/): Index of all user guides
+- [Concepts](https://flowexec.io/guides/concepts): Executables, verbs, workspaces, namespaces, templates, vaults, execution model
+- [Your First Workflow](https://flowexec.io/guides/first-workflow): End-to-end tutorial for building a workflow
+- [Executables](https://flowexec.io/guides/executables): Full reference for executable types (exec, serial, parallel, request, launch, render)
+- [Workspaces](https://flowexec.io/guides/workspaces): How workspaces organize projects and domains
+- [Secrets](https://flowexec.io/guides/secrets): Vault-backed secret storage and injection into executions
+- [Execution History & Logs](https://flowexec.io/guides/execution-history): Viewing, attaching to, and inspecting past runs
+
+## Advanced
+
+- [Imported Executables](https://flowexec.io/guides/generated-config): Auto-import from Makefile, package.json, docker-compose, shell scripts
+- [Templates & Workflow Generation](https://flowexec.io/guides/templating): Generate executables from templates with interactive forms
+- [Advanced Workflows](https://flowexec.io/guides/advanced): Serial/parallel pipelines, retries, conditional execution, arguments/params
+- [Interactive UI](https://flowexec.io/guides/interactive): TUI customization and keybindings
+- [Integrations](https://flowexec.io/guides/integrations): MCP server, GitHub Actions, Docker, CI pipelines
+
+## Configuration Reference
+
+- [Config Reference Overview](https://flowexec.io/types/): Index with direct JSON schema links
+- [FlowFile Schema](https://flowexec.io/types/flowfile): Structure of `*.flow` / `*.flow.yaml` files
+- [Workspace Schema](https://flowexec.io/types/workspace): Structure of `flow.yaml` workspace config
+- [Template Schema](https://flowexec.io/types/template): Structure of `*.flow.tmpl` template files
+- [Config Schema](https://flowexec.io/types/config): Structure of the user-level flow config
+
+## JSON Schemas
+
+- [flowfile_schema.json](https://flowexec.io/schemas/flowfile_schema.json): Use this to validate or generate `*.flow` files
+- [workspace_schema.json](https://flowexec.io/schemas/workspace_schema.json): Use this to validate or generate `flow.yaml` files
+- [template_schema.json](https://flowexec.io/schemas/template_schema.json): Use this to validate or generate `*.flow.tmpl` files
+- [config_schema.json](https://flowexec.io/schemas/config_schema.json): Use this to validate or generate the user-level config
+
+## CLI Reference
+
+- [CLI Overview](https://flowexec.io/cli/flow): Top-level `flow` command and global flags
+- [flow browse](https://flowexec.io/cli/flow_browse): Interactive TUI for discovering and running executables
+- [flow exec](https://flowexec.io/cli/flow_exec): Run an executable directly
+- [flow sync](https://flowexec.io/cli/flow_sync): Refresh cached executable and workspace state
+- [flow mcp](https://flowexec.io/cli/flow_mcp): Start the MCP server over stdio for AI-agent integration
+
+### Logs
+
+- [flow logs](https://flowexec.io/cli/flow_logs): View execution history
+- [flow logs attach](https://flowexec.io/cli/flow_logs_attach): Attach to a running background execution
+- [flow logs clear](https://flowexec.io/cli/flow_logs_clear): Clear log history
+- [flow logs kill](https://flowexec.io/cli/flow_logs_kill): Terminate a background execution
+
+### Cache
+
+- [flow cache](https://flowexec.io/cli/flow_cache): Manage cached executable metadata
+- [flow cache clear](https://flowexec.io/cli/flow_cache_clear): Clear all cache entries
+- [flow cache get](https://flowexec.io/cli/flow_cache_get): Read a specific cache entry
+- [flow cache list](https://flowexec.io/cli/flow_cache_list): List cache entries
+- [flow cache remove](https://flowexec.io/cli/flow_cache_remove): Remove a specific entry
+- [flow cache set](https://flowexec.io/cli/flow_cache_set): Write a cache entry
+
+### Config
+
+- [flow config](https://flowexec.io/cli/flow_config): User-level configuration commands
+- [flow config get](https://flowexec.io/cli/flow_config_get): Read current config
+- [flow config reset](https://flowexec.io/cli/flow_config_reset): Reset to defaults
+- [flow config set](https://flowexec.io/cli/flow_config_set): Update a config value
+- [flow config set namespace](https://flowexec.io/cli/flow_config_set_namespace): Set current namespace
+- [flow config set workspace](https://flowexec.io/cli/flow_config_set_workspace): Set current workspace
+- [flow config set workspace-mode](https://flowexec.io/cli/flow_config_set_workspace-mode): Set fixed vs dynamic workspace mode
+- [flow config set log-mode](https://flowexec.io/cli/flow_config_set_log-mode): Set default log output format
+- [flow config set timeout](https://flowexec.io/cli/flow_config_set_timeout): Set default execution timeout
+- [flow config set theme](https://flowexec.io/cli/flow_config_set_theme): Customize TUI theme
+- [flow config set tui](https://flowexec.io/cli/flow_config_set_tui): Toggle interactive mode defaults
+- [flow config set notifications](https://flowexec.io/cli/flow_config_set_notifications): Configure notification behavior
+
+### Secrets & Vaults
+
+- [flow secret](https://flowexec.io/cli/flow_secret): Manage secrets in the active vault
+- [flow secret get](https://flowexec.io/cli/flow_secret_get): Read a secret value
+- [flow secret list](https://flowexec.io/cli/flow_secret_list): List secrets
+- [flow secret remove](https://flowexec.io/cli/flow_secret_remove): Delete a secret
+- [flow secret set](https://flowexec.io/cli/flow_secret_set): Store a secret
+- [flow vault](https://flowexec.io/cli/flow_vault): Manage vaults
+- [flow vault create](https://flowexec.io/cli/flow_vault_create): Create a new vault (AES256, Age, Keyring, or unencrypted)
+- [flow vault edit](https://flowexec.io/cli/flow_vault_edit): Edit vault metadata
+- [flow vault get](https://flowexec.io/cli/flow_vault_get): Show vault details
+- [flow vault list](https://flowexec.io/cli/flow_vault_list): List registered vaults
+- [flow vault remove](https://flowexec.io/cli/flow_vault_remove): Remove a vault
+- [flow vault switch](https://flowexec.io/cli/flow_vault_switch): Switch active vault
+
+### Templates
+
+- [flow template](https://flowexec.io/cli/flow_template): Manage workflow templates
+- [flow template add](https://flowexec.io/cli/flow_template_add): Register a template
+- [flow template generate](https://flowexec.io/cli/flow_template_generate): Generate a workflow from a template
+- [flow template get](https://flowexec.io/cli/flow_template_get): Show template metadata
+- [flow template list](https://flowexec.io/cli/flow_template_list): List registered templates
+
+### Workspaces
+
+- [flow workspace](https://flowexec.io/cli/flow_workspace): Workspace management commands
+- [flow workspace add](https://flowexec.io/cli/flow_workspace_add): Register a workspace
+- [flow workspace get](https://flowexec.io/cli/flow_workspace_get): Show workspace details
+- [flow workspace list](https://flowexec.io/cli/flow_workspace_list): List registered workspaces
+- [flow workspace remove](https://flowexec.io/cli/flow_workspace_remove): Unregister a workspace
+- [flow workspace switch](https://flowexec.io/cli/flow_workspace_switch): Change active workspace
+- [flow workspace view](https://flowexec.io/cli/flow_workspace_view): Open workspace in TUI
+
+## Optional
+
+- [Contributing](https://flowexec.io/development): Development setup and contribution guide
+- [TUI Kit](https://flowexec.io/tuikit): Companion Bubble Tea-based TUI framework
+- [GitHub Repository](https://github.com/flowexec/flow): Source code, issues, releases
+- [Examples Repository](https://github.com/flowexec/examples): Real-world workflow examples
+- [Discord Community](https://discord.gg/CtByNKNMxM): Community chat

docs/public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://flowexec.io/sitemap.xml

go.mod

@@ -13,7 +13,7 @@ require (
 	github.com/gen2brain/beeep v0.11.2
 	github.com/google/uuid v1.6.0
 	github.com/jahvon/expression v0.1.4
-	github.com/mark3labs/mcp-go v0.43.2
+	github.com/mark3labs/mcp-go v0.47.1
 	github.com/onsi/ginkgo/v2 v2.28.1
 	github.com/onsi/gomega v1.39.0
 	github.com/otiai10/copy v1.14.1
@@ -40,8 +40,6 @@ require (
 	github.com/alecthomas/chroma/v2 v2.20.0 // indirect
 	github.com/aymanbagabas/go-udiff v0.4.1 // indirect
 	github.com/aymerick/douceur v0.2.0 // indirect
-	github.com/bahlo/generic-list-go v0.2.0 // indirect
-	github.com/buger/jsonparser v1.1.2 // indirect
 	github.com/catppuccin/go v0.3.0 // indirect
 	github.com/charmbracelet/ultraviolet v0.0.0-20260205113103-524a6607adb8 // indirect
 	github.com/charmbracelet/x/ansi v0.11.6 // indirect
@@ -66,13 +64,12 @@ require (
 	github.com/go-task/slim-sprig/v3 v3.0.0 // indirect
 	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/jsonschema-go v0.4.2 // indirect
 	github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/invopop/jsonschema v0.13.0 // indirect
 	github.com/jackmordaunt/icns/v3 v3.0.1 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
-	github.com/mailru/easyjson v0.9.0 // indirect
 	github.com/mattn/go-runewidth v0.0.23 // indirect
 	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
@@ -87,7 +84,6 @@ require (
 	github.com/sergeymakinen/go-ico v1.0.0-beta.0 // indirect
 	github.com/spf13/cast v1.9.2 // indirect
 	github.com/tadvi/systray v0.0.0-20190226123456-11a2b8fa57af // indirect
-	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/yuin/goldmark v1.7.13 // indirect

go.sum

@@ -34,10 +34,6 @@ github.com/aymanbagabas/go-udiff v0.4.1 h1:OEIrQ8maEeDBXQDoGCbbTTXYJMYRCRO1fnodZ
 github.com/aymanbagabas/go-udiff v0.4.1/go.mod h1:0L9PGwj20lrtmEMeyw4WKJ/TMyDtvAoK9bf2u/mNo3w=
 github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
 github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
-github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
-github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
-github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk=
-github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0=
 github.com/catppuccin/go v0.3.0 h1:d+0/YicIq+hSTo5oPuRi5kOpqkVA5tAsU6dNhvRu+aY=
 github.com/catppuccin/go v0.3.0/go.mod h1:8IHJuMGaUUjQM82qBrGNBv7LFq6JI3NnQCF6MOlZjpc=
 github.com/charmbracelet/colorprofile v0.4.3 h1:QPa1IWkYI+AOB+fE+mg/5/4HRMZcaXex9t5KX76i20Q=
@@ -120,6 +116,8 @@ github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
 github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
+github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
@@ -132,8 +130,6 @@ github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUq
 github.com/hexops/gotextdiff v1.0.3/go.mod h1:pSWU5MAI3yDq+fZBTazCSJysOMbxWL1BSow5/V2vxeg=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
-github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
-github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
 github.com/jackmordaunt/icns/v3 v3.0.1 h1:xxot6aNuGrU+lNgxz5I5H0qSeCjNKp8uTXB1j8D4S3o=
 github.com/jackmordaunt/icns/v3 v3.0.1/go.mod h1:5sHL59nqTd2ynTnowxB/MDQFhKNqkK8X687uKNygaSQ=
 github.com/jahvon/expression v0.1.4 h1:4q/jvM5G2mBJDqXtTUDThtJ4Sfajx+vIhUf4r6EAy6A=
@@ -148,10 +144,8 @@ github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lucasb-eyer/go-colorful v1.3.0 h1:2/yBRLdWBZKrf7gB40FoiKfAWYQ0lqNcbuQwVHXptag=
 github.com/lucasb-eyer/go-colorful v1.3.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
-github.com/mailru/easyjson v0.9.0 h1:PrnmzHw7262yW8sTBwxi1PdJA3Iw/EKBa8psRf7d9a4=
-github.com/mailru/easyjson v0.9.0/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
-github.com/mark3labs/mcp-go v0.43.2 h1:21PUSlWWiSbUPQwXIJ5WKlETixpFpq+WBpbMGDSVy/I=
-github.com/mark3labs/mcp-go v0.43.2/go.mod h1:YnJfOL382MIWDx1kMY+2zsRHU/q78dBg9aFb8W6Thdw=
+github.com/mark3labs/mcp-go v0.47.1 h1:A9sJJ20mscl/ssLYHjodfaoBmq6uuhMG7pAPNYaQymQ=
+github.com/mark3labs/mcp-go v0.47.1/go.mod h1:JKTC7R2LLVagkEWK7Kwu7DbmA6iIvnNAod6yrHiQMag=
 github.com/maruel/natural v1.1.1 h1:Hja7XhhmvEFhcByqDoHz9QZbkWey+COd9xWfCfn1ioo=
 github.com/maruel/natural v1.1.1/go.mod h1:v+Rfd79xlw1AgVBjbO0BEQmptqb5HvL/k9GRHB7ZKEg=
 github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
@@ -222,8 +216,6 @@ github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
 github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
 github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
-github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
-github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no=
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=

internal/mcp/command_executor.go

@@ -1,6 +1,7 @@
 package mcp
 
 import (
+	"context"
 	"os"
 	"os/exec"
 
@@ -12,6 +13,7 @@ const cliBinaryEnvKey = "FLOW_CLI_BINARY"
 //go:generate mockgen -destination=mocks/command_executor.go -package=mocks . CommandExecutor
 type CommandExecutor interface {
 	Execute(args ...string) (string, error)
+	ExecuteContext(ctx context.Context, args ...string) (string, error)
 }
 
 // FlowCLIExecutor runs the flow CLI with provided arguments. The CLI is being executed instead of importing the
@@ -23,11 +25,15 @@ type CommandExecutor interface {
 type FlowCLIExecutor struct{}
 
 func (c *FlowCLIExecutor) Execute(args ...string) (string, error) {
+	return c.ExecuteContext(context.Background(), args...)
+}
+
+func (c *FlowCLIExecutor) ExecuteContext(ctx context.Context, args ...string) (string, error) {
 	name := "flow"
 	if envName := os.Getenv(cliBinaryEnvKey); envName != "" {
 		name = envName
 	}
-	cmd := exec.Command(name, args...) // #nosec G204,G702
+	cmd := exec.CommandContext(ctx, name, args...) // #nosec G204,G702
 	output, err := cmd.CombinedOutput()
 	if err != nil {
 		// Only return an error if it's not an exit error.

internal/mcp/errors.go

@@ -0,0 +1,48 @@
+package mcp
+
+import (
+	"encoding/json"
+
+	"github.com/mark3labs/mcp-go/mcp"
+)
+
+// Machine-readable error codes for structured error responses.
+const (
+	ErrCodeInvalidInput     = "INVALID_INPUT"
+	ErrCodeNotFound         = "NOT_FOUND"
+	ErrCodeExecutionFailed  = "EXECUTION_FAILED"
+	ErrCodeTimeout          = "TIMEOUT"
+	ErrCodeCancelled        = "CANCELLED"
+	ErrCodeValidationFailed = "VALIDATION_FAILED"
+	ErrCodeInternal         = "INTERNAL_ERROR"
+	ErrCodePermissionDenied = "PERMISSION_DENIED"
+)
+
+type errorPayload struct {
+	Error errorDetail `json:"error"`
+}
+
+type errorDetail struct {
+	Code    string         `json:"code"`
+	Message string         `json:"message"`
+	Details map[string]any `json:"details,omitempty"`
+}
+
+// toolError returns a CallToolResult with IsError set and a structured JSON error payload.
+func toolError(code, message string) *mcp.CallToolResult {
+	return toolErrorWithDetails(code, message, nil)
+}
+
+// toolErrorWithDetails is like toolError but includes a details object in the error payload.
+func toolErrorWithDetails(code, message string, details map[string]any) *mcp.CallToolResult {
+	payload := errorPayload{Error: errorDetail{
+		Code:    code,
+		Message: message,
+		Details: details,
+	}}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return mcp.NewToolResultError(message)
+	}
+	return mcp.NewToolResultError(string(data))
+}