Add support for Claude MCP configuration files in CLI run command

[Copilot]

This PR adds support for loading MCP (Model Context Protocol) servers from Claude format configuration files using the new --mcp-config option in the genaiscript run command.

Problem

Previously, MCP servers could only be configured directly in script files using the mcpServers property. Users working with Claude Desktop who already have MCP configuration files (.vscode/mcp.json or similar) had to duplicate their server configurations when using GenAIScript.

Solution

Added a new --mcp-config <file> CLI option that:

1. Loads Claude format MCP configuration files with support for both servers and mcpServers object structures
2. Supports enhanced environment variable interpolation using Claude's syntax:
   • ${workspaceFolder} - resolves to workspace directory or config file directory
   • ${env:VARIABLE_NAME} - resolves to environment variable values
   • ${VARIABLE_NAME} - resolves to capitalized environment variable values
3. Merges with existing script configurations - servers from config files are combined with any mcpServers defined in the script
4. Provides comprehensive error handling for missing files, invalid JSON, and malformed configurations
5. Includes debug logging using genaiscriptDebug to trace MCP server resolution

Usage

# Load MCP servers from Claude configuration file
genaiscript run my-script --mcp-config .vscode/mcp.json

Example MCP configuration file:

{
    "mcpServers": {
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
            "env": {
                "DEBUG": "${env:DEBUG}",
                "API_KEY": "${API_KEY}"
            }
        },
        "memory": {
            "command": "npx", 
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        }
    }
}

Implementation Details

• New module: packages/core/src/mcp-config.ts handles configuration parsing and variable interpolation
• CLI integration: Added option to run command and integrated loading into script execution pipeline
• Type safety: Extended PromptScriptRunOptions interface to include mcpConfig property
• Documentation: Updated CLI reference and added comprehensive usage examples
• Debug logging: Added comprehensive debug tracing for MCP server resolution

Testing

The implementation includes comprehensive testing for:

• Basic configuration loading and parsing
• Environment variable interpolation scenarios (including new capitalized variable syntax)
• Error handling for various failure cases
• Integration with the script execution pipeline
• Security validation (CodeQL analysis passed)

This change is backwards compatible and doesn't affect existing functionality when the --mcp-config option is not used.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• cdn.sheetjs.com
  • Triggering command: node /home/REDACTED/.local/share/pnpm/.tools/pnpm/10.12.3/bin/pnpm install (dns block)
• esm.ubuntu.com
  • Triggering command: /usr/lib/apt/methods/https (dns block)
• example.com
• https://api.github.com/markdown
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/branches
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/contents/README.md
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/contents/packages%2Fcore%2Fsrc
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/git/blobs
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/git/ref/heads%2Ftest-ignore
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/issues
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/labels
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/languages
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/pulls
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/repos/microsoft/genaiscript/pulls/999999
  • Triggering command: node (vitest 3) (http block)
• https://api.github.com/test
  • Triggering command: node (vitest 3) (http block)
• microsoft.github.io
  • Triggering command: node (vitest 2) (dns block)
• telemetry.astro.build
  • Triggering command: node /home/REDACTED/work/genaiscript/genaiscript/docs/node_modules/.bin/../astro/astro.js build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

Warning

LLM error (403): error

Warning

LLM error (403): error

Warning

LLM error (403): error

AI-generated content by docs may be incorrect.