docs added,

.serena/project.yml

@@ -3,22 +3,26 @@ project_name: "lda-workflow-as-struct"
 
 
 # list of languages for which language servers are started; choose from:
-#   al                  bash                clojure             cpp                 csharp
+#   al                  angular             ansible             bash                clojure
-#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   cpp                 cpp_ccls            crystal             csharp              csharp_omnisharp
-#   fortran             fsharp              go                  groovy              haskell
+#   dart                elixir              elm                 erlang              fortran
-#   haxe                java                julia               kotlin              lua
+#   fsharp              go                  groovy              haskell             haxe
-#   markdown
+#   hlsl                html                java                json                julia
-#   matlab              nix                 pascal              perl                php
+#   kotlin              lean4               lua                 luau                markdown
-#   php_phpactor        powershell          python              python_jedi         r
+#   matlab              msl                 nix                 ocaml               pascal
-#   rego                ruby                ruby_solargraph     rust                scala
+#   perl                php                 php_phpactor        powershell          python
-#   swift               terraform           toml                typescript          typescript_vts
+#   python_jedi         python_ty           r                   rego                ruby
-#   vue                 yaml                zig
+#   ruby_solargraph     rust                scala               scss                solidity
+#   swift               systemverilog       terraform           toml                typescript
+#   typescript_vts      vue                 yaml                zig
 #   (This list may be outdated. For the current list, see values of Language enum here:
 #   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
 #   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
 # Note:
 #   - For C, use cpp
 #   - For JavaScript, use typescript
+#   - For Angular projects, use angular (subsumes typescript+html; requires `npm install` in the project root)
+#   - For SCSS / Sass / plain CSS, use scss (some-sass-language-server handles all three)
 #   - For Free Pascal/Lazarus, use pascal
 # Special requirements:
 #   Some languages require additional setup/installations.
@@ -66,54 +70,17 @@ read_only: false
 
 # list of tool names to exclude.
 # This extends the existing exclusions (e.g. from the global configuration)
-#
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project based on the project name or path.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
-#       for example by saying that the information retrieved from a memory file is no longer correct
-#       or no longer relevant for the project.
-#  * `edit_memory`: Replaces content matching a regular expression in a memory.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_file`: Finds files in the given relative paths
-#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
-#  * `find_symbol`: Performs a global (or local) search using the language server backend.
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
-#       for clients that do not read the initial instructions when the MCP server is connected.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
-#       is relevant to the current task. You can infer whether the information
-#       is relevant from the memory file name.
-#       You should not read the same memory file multiple times in the same conversation.
-#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
-#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
-#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
-#       For JB, we use a separate tool.
-#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
-#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
-#  * `safe_delete_symbol`:
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
-#       The memory name should be meaningful.
 excluded_tools: []
 
 # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
 # This extends the existing inclusions (e.g. from the global configuration).
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 included_optional_tools: []
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
 # This cannot be combined with non-empty excluded_tools or included_optional_tools.
+# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html
 fixed_tools: []
 
 # list of mode names to that are always to be included in the set of active modes
@@ -124,11 +91,14 @@ fixed_tools: []
 # Set this to a list of mode names to always include the respective modes for this project.
 base_modes:
 
-# list of mode names that are to be activated by default.
+# list of mode names that are to be activated by default, overriding the setting in the global configuration.
-# The full set of modes to be activated is base_modes + default_modes.
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
-# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply.
 # Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply
+# for this project.
 # This setting can, in turn, be overridden by CLI parameters (--mode).
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
 default_modes:
 
 # initial prompt for the project. It will always be given to the LLM upon activating the project
@@ -152,3 +122,19 @@ read_only_memory_patterns: []
 # Extends the list from the global configuration, merging the two lists.
 # Example: ["_archive/.*", "_episodes/.*"]
 ignored_memory_patterns: []
+
+# list of mode names to be activated additionally for this project, e.g. ["query-projects"]
+# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes.
+# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes
+added_modes:
+
+# list of additional workspace folder paths for cross-package reference support (e.g. in monorepos).
+# Paths can be absolute or relative to the project root.
+# Each folder is registered as an LSP workspace folder, enabling language servers to discover
+# symbols and references across package boundaries.
+# Currently supported for: TypeScript.
+# Example:
+#   additional_workspace_folders:
+#     - ../sibling-package
+#     - ../shared-lib
+additional_workspace_folders: []

docs/mcp_protocol_proxy_inventory.md

@@ -0,0 +1,319 @@
+# MCP Protocol Proxy Inventory
+
+This document records observed behavior of `wf-mcp` unified mode against real
+upstream MCP servers. It is not a design spec. It is a fact log for deciding
+which proxy features need explicit implementation.
+
+## Live Everything Server Probe
+
+Probe date: 2026-05-13
+
+Server command in config:
+
+```text
+pnpx @modelcontextprotocol/server-everything
+```
+
+Connection id:
+
+```text
+everything.default
+```
+
+Proxy mode:
+
+```text
+wf-mcp serve --mode unified
+```
+
+### Working
+
+- `tools/list` shows Everything tools through `wf-mcp`.
+- `tools/call` works for normal tools such as `everything.default_echo`.
+- Tool metadata is preserved for proxy inventory, including title, description,
+  and JSON input schema.
+- Annotated text content is preserved.
+- Tiny image content returns through the proxy.
+- Structured content returns structured JSON.
+- `trigger-long-running-operation` completes through the proxy as a normal tool
+  call.
+- `toggle-simulated-logging` and `toggle-subscriber-updates` return success.
+- Native listed resources are namespaced by FastMCP mount/proxy transforms.
+- Native listed resource templates are namespaced by FastMCP mount/proxy
+  transforms.
+- Namespaced static and dynamic resources can be read through `wf-mcp`.
+
+Example listed resource mapping:
+
+```text
+upstream: demo://resource/static/document/instructions.md
+proxied:  demo://everything.default/resource/static/document/instructions.md
+```
+
+### Gaps
+
+- Resource links embedded inside tool results are not rewritten by the proxy.
+  For example, `get-resource-links` returns raw upstream URIs such as:
+
+```text
+demo://resource/dynamic/text/2
+```
+
+  `wf-mcp` cannot read that raw URI. The manually namespaced URI works for
+  normal dynamic resources:
+
+```text
+demo://everything.default/resource/dynamic/text/2
+```
+
+- Session resource links from `gzip-file-as-resource` are not currently usable
+  through `wf-mcp`. The tool returned:
+
+```text
+demo://resource/session/probe.txt
+```
+
+  Neither the raw URI nor the manually namespaced URI was readable through
+  `wf-mcp` during the live probe. Direct `everything` read also failed in this
+  Codex session, so this may be session-affinity, lifecycle, or returned-link
+  behavior rather than only URI rewriting.
+
+- `simulate-research-query` is discovered, but calling it fails cleanly:
+
+```text
+Tool simulate-research-query requires task augmentation (taskSupport: 'required')
+```
+
+  This is a task/protocol support gap, not an ordinary tool-call failure.
+
+- Logging and subscriber update tools return success, but no separate logging
+  or resource-update notification was visible in the Codex tool channel during
+  this probe.
+
+- Sampling was not visible as a direct listed tool in the current Everything
+  server inventory.
+
+### Current Classification
+
+- Proxy tool projection: healthy for ordinary tools.
+- Proxy resource list/read projection: healthy for listed resources and
+  templates.
+- Tool-result resource links: incomplete; embedded resource URIs need explicit
+  rewrite or a documented limitation.
+- Session resources: unresolved; needs a focused test because session affinity
+  may matter.
+- Tasks: unsupported; task-required tools should remain clearly diagnosed until
+  MCP task support is implemented.
+- Notifications/logging/subscriptions: unverified; current client did not show
+  forwarded notifications.
+
+## Next Test Targets
+
+- Add automated tests for listed resource/template namespacing through unified
+  mode.
+- Add a fixture or Everything integration test showing tool-returned
+  `resource_link` URIs are not rewritten today.
+- Decide whether to rewrite embedded resource links in tool results or expose a
+  helper that resolves upstream resource links into proxied resource URIs.
+- Investigate session resource lifecycle separately from URI rewriting.
+- Inventory current FastMCP/MCP SDK APIs for tasks, logging notifications, and
+  resource update notifications before implementing protocol forwarding.
+
+## Notification Inventory
+
+Spec version checked: 2025-11-25
+
+Official spec pages checked:
+
+- <https://modelcontextprotocol.io/specification/2025-11-25/server/tools>
+- <https://modelcontextprotocol.io/specification/2025-11-25/server/resources>
+- <https://modelcontextprotocol.io/specification/2025-11-25/server/prompts>
+- <https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress>
+
+Installed local packages checked:
+
+- `fastmcp==3.2.4`
+- `mcp==1.27.0`
+
+### Protocol Notifications
+
+The MCP spec defines these relevant server-to-client notifications:
+
+| Event | MCP notification | Notes |
+| --- | --- | --- |
+| Tool catalog changed | `notifications/tools/list_changed` | Requires server `tools.listChanged` capability. |
+| Resource catalog changed | `notifications/resources/list_changed` | Requires server `resources.listChanged` capability. |
+| Prompt catalog changed | `notifications/prompts/list_changed` | Requires server `prompts.listChanged` capability. |
+| Specific resource updated | `notifications/resources/updated` | Requires resource subscription flow. Params include resource `uri`. |
+| Request progress | `notifications/progress` | Requires an active request with `_meta.progressToken`. |
+| Logging message | `notifications/message` | Uses MCP logging level and client logging preferences. |
+| Task status | `notifications/tasks/status` | Used by MCP task-augmented execution. |
+
+The spec also defines client-to-server requests that matter for notifications:
+
+| Request | Purpose |
+| --- | --- |
+| `resources/subscribe` | Client subscribes to updates for a specific resource URI. |
+| `resources/unsubscribe` | Client stops receiving updates for a specific resource URI. |
+| request `_meta.progressToken` | Client asks for progress notifications for that request. |
+
+### FastMCP / SDK Reality
+
+MCP SDK has concrete notification types in `mcp.types`, including:
+
+- `ToolListChangedNotification`
+- `ResourceListChangedNotification`
+- `PromptListChangedNotification`
+- `ResourceUpdatedNotification`
+- `ProgressNotification`
+- `LoggingMessageNotification`
+- `TaskStatusNotification`
+
+FastMCP low-level server advertises notification support for all three list
+changed capabilities by default:
+
+```text
+prompts_changed=True
+resources_changed=True
+tools_changed=True
+```
+
+FastMCP `Context` exposes request-scoped helpers:
+
+- `ctx.send_notification(notification)`
+- `ctx.report_progress(progress, total=None, message=None)`
+- `ctx.log(...)`, plus convenience `ctx.info`, `ctx.warning`, `ctx.error`, etc.
+- `ctx.enable_components(...)`, `ctx.disable_components(...)`, and
+  `ctx.reset_visibility(...)`, which send list-changed notifications for the
+  current session.
+
+Important constraint: no global `FastMCP.notify_all(...)` style API was found.
+The obvious notification path is request/session scoped through FastMCP
+`Context` or lower-level server sessions. This matters because our internal
+event bus can emit outside a currently executing MCP tool call, while MCP
+notifications need a connected client session.
+
+### Mapping From wf-mcp Events
+
+Current internal events that can map to MCP notifications:
+
+| Internal event | Candidate MCP notification | Caveat |
+| --- | --- | --- |
+| `tools_changed` | `notifications/tools/list_changed` | Needs a session-aware sink. |
+| `resources_changed` | `notifications/resources/list_changed` | Needs a session-aware sink. |
+| `prompts_changed` | `notifications/prompts/list_changed` | Needs a session-aware sink. |
+| future `resource_updated` | `notifications/resources/updated` | Requires subscription ownership and namespaced URI mapping. |
+| future `workflow_run_progress` | `notifications/progress` | Only valid when a caller supplied a progress token. |
+| future broker log events | `notifications/message` | Needs client logging level behavior. |
+| future workflow task events | `notifications/tasks/status` | Should wait for task execution support. |
+
+### Implementation Guidance
+
+Do not emit MCP notifications directly from `WfMcpService`.
+
+Recommended shape:
+
+```text
+WfMcpService
+  -> EventBus
+    -> InMemoryEventSink
+    -> later: McpSessionNotificationSink
+```
+
+Near-term implementation should add a notification mapping layer with a fake
+sink first. Real MCP emission needs one of these session-aware entry points:
+
+- a FastMCP tool/resource/prompt handler with injected `Context`
+- middleware that can access the active `Context` or session
+- explicit lower-level session management if FastMCP exposes enough stable API
+
+Until we have a session-aware sink, list-changed events should remain internal
+events exposed through `get_broker_events` / `wf-mcp://events`.
+
+### Concrete Notification Plan
+
+Implement notifications in this order.
+
+1. Add a pure mapping layer from internal events to MCP notification objects.
+
+```text
+tools_changed     -> ToolListChangedNotification
+resources_changed -> ResourceListChangedNotification
+prompts_changed   -> PromptListChangedNotification
+```
+
+This layer should not know about FastMCP sessions. It should be easy to test
+with plain `mcp.types` objects.
+
+2. Add a fake/test notification sink.
+
+The first sink should only record which MCP notification objects would be sent.
+This proves the event-to-notification mapping without depending on Codex,
+Inspector, stdio behavior, or Streamable HTTP behavior.
+
+3. Add a FastMCP `Context` notification sink.
+
+This sink can call:
+
+```text
+ctx.send_notification(...)
+```
+
+It is only valid while handling a request that has an active FastMCP context.
+This should be treated as a session-scoped projection, not a global broadcast
+system.
+
+4. Wire local admin operations first.
+
+Best first live target:
+
+```text
+wf.admin.reload_config
+```
+
+When reload changes mounted capabilities, it should:
+
+- perform the reload
+- emit internal catalog/tool/resource/prompt change events
+- send list-changed MCP notifications to the current client session when a
+  FastMCP context is available
+
+This is intentionally local. It does not require solving upstream notification
+forwarding.
+
+5. Verify with Inspector/Codex.
+
+Expected outcomes:
+
+- clients that honor list-changed notifications refresh their tool/resource/
+  prompt lists
+- clients that ignore notifications can still manually call list/search tools
+- no workflow or broker correctness depends on notification delivery
+
+6. Only after local list-changed works, investigate upstream notification
+forwarding.
+
+Upstream forwarding is a separate problem because mounted proxies may or may
+not already forward upstream notifications. It also needs namespaced resource
+URIs for `notifications/resources/updated`.
+
+### Deferred Notification Work
+
+- `notifications/resources/updated`: requires explicit resource subscription
+  ownership and URI rewriting.
+- `notifications/progress`: requires an active request `_meta.progressToken`.
+- `notifications/message`: should respect client logging level behavior.
+- `notifications/tasks/status`: should wait for task-augmented execution.
+- Upstream-to-downstream notification forwarding: needs a focused FastMCP proxy
+  behavior test before implementation.
+
+### Open Questions
+
+- Can a mounted FastMCP proxy forward upstream notifications to the downstream
+  client automatically, or only notifications generated by local handlers?
+- Can we attach a durable notification sink to every active FastMCP session
+  without relying on private APIs?
+- Does Codex surface list-changed, resource-updated, logging, or progress
+  notifications from an MCP server in this environment?
+- For streamable HTTP, does FastMCP event-store support make notification
+  replay possible for disconnected clients?

src/wf_mcp/server/unified.py

@@ -87,15 +87,29 @@ def _register_workflow_tools(
 ) -> None:
     """Register stable workflow tools on the unified MCP surface."""
 
-    @server.tool(name="wf.workflow.list_artifacts")
+    @server.tool(
+        name="wf.workflow.list_artifacts",
+        title="List Workflow Artifacts",
+        description="List saved workflow artifacts available to run or inspect.",
+    )
     async def list_artifacts() -> dict[str, Any]:
         return await handlers.list_artifacts()
 
-    @server.tool(name="wf.workflow.save_artifact")
+    @server.tool(
+        name="wf.workflow.save_artifact",
+        title="Save Workflow Artifact",
+        description="Persist a complete workflow artifact JSON document.",
+    )
     async def save_artifact(artifact: dict[str, Any]) -> dict[str, Any]:
         return await handlers.save_artifact(artifact)
 
-    @server.tool(name="wf.workflow.create_artifact_from_plan")
+    @server.tool(
+        name="wf.workflow.create_artifact_from_plan",
+        title="Create Workflow Artifact From Plan",
+        description=(
+            "Validate a raw workflow plan and save it as a versioned artifact."
+        ),
+    )
     async def create_artifact_from_plan(
         artifact_id: str,
         version: int,
@@ -117,7 +131,11 @@ def _register_workflow_tools(
             created_from_catalog_version=created_from_catalog_version,
         )
 
-    @server.tool(name="wf.workflow.inspect_artifact")
+    @server.tool(
+        name="wf.workflow.inspect_artifact",
+        title="Inspect Workflow Artifact",
+        description="Return the full saved artifact for artifact_id and version.",
+    )
     async def inspect_artifact(
         artifact_id: str,
         version: int,
@@ -127,19 +145,40 @@ def _register_workflow_tools(
             version=version,
         )
 
-    @server.tool(name="wf.workflow.list_deployments")
+    @server.tool(
+        name="wf.workflow.list_deployments",
+        title="List Workflow Deployments",
+        description="List saved workflow deployments and their source bindings.",
+    )
     async def list_deployments() -> dict[str, Any]:
         return await handlers.list_deployments()
 
-    @server.tool(name="wf.workflow.save_deployment")
+    @server.tool(
+        name="wf.workflow.save_deployment",
+        title="Save Workflow Deployment",
+        description="Persist a workflow deployment that binds logical sources.",
+    )
     async def save_deployment(deployment: dict[str, Any]) -> dict[str, Any]:
         return await handlers.save_deployment(deployment)
 
-    @server.tool(name="wf.workflow.validate_deployment")
+    @server.tool(
+        name="wf.workflow.validate_deployment",
+        title="Validate Workflow Deployment",
+        description=(
+            "Check whether a deployment_id can run with currently enabled sources."
+        ),
+    )
     async def validate_deployment(deployment_id: str) -> dict[str, Any]:
         return await handlers.validate_deployment(deployment_id=deployment_id)
 
-    @server.tool(name="wf.workflow.run_deployment")
+    @server.tool(
+        name="wf.workflow.run_deployment",
+        title="Run Workflow Deployment",
+        description=(
+            "Run deployment_id with workflow_input and return status, output, "
+            "diagnostics, and trace_count."
+        ),
+    )
     async def run_deployment(
         deployment_id: str,
         workflow_input: dict[str, Any],

src/wf_mcp/transparent_proxy/admin.py

@@ -17,23 +17,43 @@ def create_proxy_admin_server(
     )
     handlers = TransparentAdminHandlers(runtime)
 
-    @admin.tool()
+    @admin.tool(
+        title="List Connections",
+        description="List configured MCP connections known to this proxy instance.",
+    )
     async def list_connections() -> list[dict[str, Any]]:
         return handlers.list_connections()
 
-    @admin.tool()
+    @admin.tool(
+        title="Get Connection Statuses",
+        description="Show configured MCP connection status and basic catalog counts.",
+    )
     async def get_connection_statuses() -> list[dict[str, Any]]:
         return handlers.get_connection_statuses()
 
-    @admin.tool()
+    @admin.tool(
+        title="Get Config",
+        description="Return the current proxy configuration payload.",
+    )
     async def get_config() -> dict[str, Any]:
         return handlers.get_config()
 
-    @admin.tool()
+    @admin.tool(
+        title="Reload Config",
+        description=(
+            "Reload the config file and remount enabled upstream MCP connections."
+        ),
+    )
     async def reload_config() -> dict[str, Any]:
         return handlers.reload_config()
 
-    @admin.tool()
+    @admin.tool(
+        title="List Proxy Tools",
+        description=(
+            "List upstream tools projected through this proxy, with optional "
+            "connection_id, query, limit, and cursor filters."
+        ),
+    )
     async def list_proxy_tools(
         connection_id: str | None = None,
         query: str | None = None,
@@ -47,11 +67,17 @@ def create_proxy_admin_server(
             cursor=cursor,
         )
 
-    @admin.tool()
+    @admin.tool(
+        title="Get Proxy Tool",
+        description="Return admin metadata and schema for one projected proxy tool.",
+    )
     async def get_proxy_tool(proxy_name: str) -> dict[str, Any]:
         return await handlers.get_proxy_tool(proxy_name)
 
-    @admin.tool()
+    @admin.tool(
+        title="Add Connection",
+        description="Add a new MCP connection to the file-backed proxy config.",
+    )
     async def add_connection(
         connection_id: str,
         server: str,
@@ -67,7 +93,10 @@ def create_proxy_admin_server(
             enabled=enabled,
         )
 
-    @admin.tool()
+    @admin.tool(
+        title="Update Connection",
+        description="Update server, account, metadata, or enabled state for a connection.",
+    )
     async def update_connection(
         connection_id: str,
         server: str | None = None,
@@ -83,15 +112,24 @@ def create_proxy_admin_server(
             enabled=enabled,
         )
 
-    @admin.tool()
+    @admin.tool(
+        title="Enable Connection",
+        description="Mark a configured MCP connection as enabled.",
+    )
     async def enable_connection(connection_id: str) -> dict[str, Any]:
         return handlers.enable_connection(connection_id)
 
-    @admin.tool()
+    @admin.tool(
+        title="Disable Connection",
+        description="Mark a configured MCP connection as disabled.",
+    )
     async def disable_connection(connection_id: str) -> dict[str, Any]:
         return handlers.disable_connection(connection_id)
 
-    @admin.tool()
+    @admin.tool(
+        title="Remove Connection",
+        description="Remove a configured MCP connection from the file-backed config.",
+    )
     async def remove_connection(connection_id: str) -> dict[str, Any]:
         return handlers.remove_connection(connection_id)
 

tests/wf_mcp/test_unified_server.py

@@ -82,3 +82,47 @@ def test_unified_server_can_hide_admin_tools() -> None:
             assert "wf.admin.list_connections" not in names
 
     asyncio.run(run_proxy())
+
+
+def test_unified_workflow_tools_have_human_metadata() -> None:
+    config = BrokerConfig(
+        store_root=local_temp_root() / "unified_metadata_store",
+        connections=[],
+    )
+
+    async def run_proxy() -> None:
+        client = create_unified_proxy_client(config, admin_tools=False)
+        async with client:
+            tools = await client.list_tools()
+            by_name = {tool.name: tool for tool in tools}
+            list_artifacts = by_name["wf.workflow.list_artifacts"]
+            run_deployment = by_name["wf.workflow.run_deployment"]
+
+            assert list_artifacts.title == "List Workflow Artifacts"
+            assert "saved workflow artifacts" in (list_artifacts.description or "")
+            assert run_deployment.title == "Run Workflow Deployment"
+            assert "deployment_id" in (run_deployment.description or "")
+
+    asyncio.run(run_proxy())
+
+
+def test_unified_admin_tools_have_human_metadata() -> None:
+    config = BrokerConfig(
+        store_root=local_temp_root() / "unified_admin_metadata_store",
+        connections=[],
+    )
+
+    async def run_proxy() -> None:
+        client = create_unified_proxy_client(config)
+        async with client:
+            tools = await client.list_tools()
+            by_name = {tool.name: tool for tool in tools}
+            list_connections = by_name["wf.admin.list_connections"]
+            reload_config = by_name["wf.admin.reload_config"]
+
+            assert list_connections.title == "List Connections"
+            assert "configured MCP connections" in (list_connections.description or "")
+            assert reload_config.title == "Reload Config"
+            assert "remount" in (reload_config.description or "")
+
+    asyncio.run(run_proxy())

wf_mcp.config.json

@@ -5,11 +5,13 @@
       "id": "context7.default",
       "server": "context7",
       "account": "default",
-      "enabled": true,
+      "enabled": false,
       "metadata": {
         "transport": "stdio",
         "command": "pnpx",
-        "args": ["@upstash/context7-mcp"],
+        "args": [
+          "@upstash/context7-mcp"
+        ],
         "env": {}
       }
     },
@@ -35,7 +37,24 @@
       "metadata": {
         "transport": "stdio",
         "command": "pnpx",
-        "args": ["@modelcontextprotocol/server-everything"],
+        "args": [
+          "@modelcontextprotocol/server-everything"
+        ],
+        "env": {}
+      }
+    },
+    {
+        "id": "serena.default",
+        "server": "serena",
+        "account": "default",
+        "enabled": false,
+        "metadata": {
+          "transport": "stdio",
+          "command": "serena",
+          "args": [
+            "start-mcp-server",
+            "--project-from-cwd"
+          ],
           "env": {}
         }
     }