mcp-scripts: dependencies field is documented and schema-validated but never implemented

[shubhamtanwar23]

Analysis

The dependencies field for mcp-scripts tools is defined in the JSON schema and documented in the specification, but it is silently dropped during parsing and never acted upon. A workflow author can declare dependencies: on a tool, pass gh aw compile and schema validation with no warning, and get zero installation behavior at runtime. Tools that rely on non-stdlib packages then fail at execution time with confusing "module/command not found" errors — unless the package happens to already exist in the runner/container image.

I traced this through the source:

1. Schema accepts it — dependencies is a defined property in docs/public/schemas/mcp-scripts-config.schema.json (around line 69), so authoring it never fails validation.

2. Spec documents it — docs/src/content/docs/specs/mcp-scripts-specification.md §4.3 describes per-language install behavior (npm/pip/go get/apt) and includes Python requests and shell jq examples.

3. The parser ignores it — MCPScriptToolConfig in pkg/workflow/mcp_scripts_parser.go has no Dependencies field, and parseMCPScriptToolConfig only reads description, inputs, script/run/py/go, env, and timeout. There is no case handling dependencies.

4. No generator/renderer/runtime references it — searching for dependenc across pkg/workflow/mcp_scripts*.go and actions/setup/js/mcp_handler_*.cjs returns nothing. tools.json (MCPScriptsToolJSON in pkg/workflow/mcp_scripts_generator.go) carries no dependency data, and the language handlers execute user code directly with no install step.

5. The spec's own Sync Notes are inaccurate — §4 Implementation Notes claim: "The dependencies field (added in v1.1.0) is handled in parseMCPScriptToolConfig." This is not true in the current code.

Decision needed

Two viable directions — I recommend Option A (implement), but flagging in case the team prefers to defer:

• Option A — Implement the field so declared dependencies are installed before tool execution, per spec §4.3.
• Option B — Remove/deprecate it from the schema and spec until it's implemented, so authors aren't misled.

Implementation Plan (Option A)

Please implement the following changes:

1. Parse the field (pkg/workflow/mcp_scripts_parser.go):

   • Add Dependencies []string to the MCPScriptToolConfig struct.
   • In parseMCPScriptToolConfig, parse dependencies from toolMap (expects a list of strings; ignore/skip non-string entries defensively).
   • Ensure mergeMCPScripts preserves Dependencies for imported tools.

2. Thread into the tools manifest (pkg/workflow/mcp_scripts_generator.go):

   • Add a Dependencies []string field with json:"dependencies,omitempty" to MCPScriptsToolJSON.
   • Populate it in GenerateMCPScriptsToolsConfig from toolConfig.Dependencies (sorted for stable output, consistent with existing patterns).

3. Install before execution (actions/setup/js/mcp_handler_*.cjs and/or the setup step in pkg/workflow/mcp_setup_generator.go):

   • Infer the package manager from the implementation language, per spec §4.3:
     • script → npm install
     • py → pip install
     • go → go get / generated go.mod
     • run → apt/yum
   • Install declared dependencies before the first tool invocation; cache where practical.
   • Honor spec §4.3 failure semantics: fail-fast on deterministic failures (package not found, invalid version, permission denied); bounded retry (max 2) on transient failures; surface a terminal tool error if retries are exhausted.

4. Validate dependency names (follow the existing validation architecture in scratchpad/validation-architecture.md; reuse pip_validation.go / npm_validation.go patterns where applicable):

   • Reject obviously invalid package names with an error following the style guide template [what's wrong]. [what's expected]. [example], e.g.:

     invalid dependency name "re quests" for tool "fetch-url". Expected a valid package name for the inferred package manager. Example: dependencies: [requests]

5. Add tests:

   • pkg/workflow/mcp_scripts_parser_test.go — parsing of dependencies (single, multiple, empty, non-string entries).
   • pkg/workflow/mcp_scripts_generator_test.go — dependencies appears in generated tools.json.
   • Cover at least one language's install path, addressing spec conformance IDs T-DEP-001..006.

6. Update documentation / spec:

   • Correct the inaccurate Sync Note in docs/src/content/docs/specs/mcp-scripts-specification.md §4 so it matches the implementation.
   • Verify §4.3 examples compile and run.
   • Update docs/src/content/docs/reference/mcp-scripts.md if dependency behavior needs author-facing notes.

7. Follow project guidelines:

   • Use console formatting from pkg/console for any CLI output.
   • Follow the error message style guide and run make lint-errors.
   • Run make recompile after any workflow markdown / generator changes.
   • Run make agent-finish (build, test, recompile, format, lint) before completing.

Acceptance criteria

• A tool declaring dependencies installs them before first invocation (Option A), OR the field is explicitly rejected/deprecated with a clear message (Option B).
• Spec §4.3 and the §4 Sync Notes match the implementation.
• Tests cover at least one language's dependency install path and the parsing/generation changes.

[pelikhan]

@copilot option A

[pelikhan]

@copilot integrate with runtime manager