vsc_tasks_json #

This package is an MCP server that enables AI agents to execute tasks defined in VSCode's .vscode/tasks.json.

• README(English)
• README(日本語)

Overview #

By adding the options.mcp property to task definitions in tasks.json, those tasks are registered as individual MCP tools. Each task can be called as an independent tool, and required variables are automatically defined as input schemas.

Prerequisites #

The following environment is required to use this MCP server:

• tasks.json: Tasks must be defined in .vscode/tasks.json

Cursor MCP Configuration #

MCP Server Registration #

Add the following to Cursor's configuration file (.cursor/mcp.json):

{
  "mcpServers": {
    "vsc_tasks_json": {
      "command": "dart",
      "args": ["run", "vsc_tasks_json"],
      "env": {}
    }
  }
}

Installation #

Adding to pubspec.yaml

To add as a project dependency, add the following to pubspec.yaml:

dependencies:
  vsc_tasks_mcp: ^1.0.0

Then install the dependencies:

dart pub get

When installed using this method, the Cursor configuration file (.cursor/mcp.json) should be as follows:

{
  "mcpServers": {
    "vsc_tasks_json": {
      "command": "dart",
      "args": ["run", "vsc_tasks_mcp"],
      "env": {}
    }
  }
}

Project Root Detection #

The MCP server detects the project root using the following method:

1. Check for the existence of .vscode/tasks.json from the current directory
2. If not found, search up to 10 parent directory levels
3. Use the found directory as the project root

Starting the Server #

You can start the MCP server from the project root with the following command:

dart run vsc_tasks_json

tasks.json Configuration #

This MCP server only registers tasks as individual tools if they have the options.mcp property set in their task definition in tasks.json.

Configuration Example #

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "dart",
      "args": [
        "run",
        "grinder",
        "build",
        "--${input:platform}",
        "--release",
        "--flavor=${input:flavor}"
      ],
      "options": {
        "mcp": {
          "tool": "app_build",
          "description": "Execute Flutter app build"
        }
      }
    }
  ],
  "inputs": [
    {
      "id": "platform",
      "type": "pickString",
      "description": "Target platform for build",
      "options": ["android", "ios"]
    },
    {
      "id": "flavor",
      "type": "pickString",
      "description": "Build flavor",
      "options": ["development", "staging", "production"]
    }
  ]
}

With the above configuration, an MCP tool named app_build will be registered.

options.mcp Configuration Fields #

• tool: MCP tool name (required)
• description: Tool description (optional)

Provided Tools #

Tool Input Schema #

Required variables are automatically detected from the task's command and args, and an input schema is generated:

• ${input:platform} → platform argument (required)
• ${input:flavor} → flavor argument (required)
• ${file} → file argument (required)

Variable Support #

The following variable formats are supported:

• ${input:variable_name}: Variables defined in tasks.json inputs
• ${file}: File path

Logging #

Log File Locations #

The MCP server outputs execution logs to the following locations:

• Server log: build/vsc_tasks_mcp/mcp_server.log
  • Records server startup, initialization, and errors
• Tool logs: build/vsc_tasks_mcp/{tool_name}.log
  • Creates individual log files for each tool execution
  • Records execution command, standard output, standard error output, and exit code

Viewing Logs #

Viewing Server Log

cat build/vsc_tasks_json/mcp_server.log

Viewing Tool Logs

# View app_build tool log
cat build/vsc_tasks_mcp/app_build.log

Troubleshooting #

Task Not Found #

Symptom: Task is not recognized as an MCP tool

Causes and Solutions:

• Verify that the options.mcp property is set
• Verify that the options.mcp.tool field exists

Task Execution Error #

Symptom: Error is returned when calling the tool

Solutions:

1. Get the log file path from the logFile field in the response
2. Check the log file for detailed error information
3. Check the command field for the actual command that was executed

# Example of checking log file
cat /path/to/project/build/vsc_tasks_mcp/app_build.log

Project Root Not Detected #

Symptom: Error indicating .vscode/tasks.json was not found

Solutions:

• Start the MCP server from the project root (or a subdirectory)
• Verify that .vscode/tasks.json exists
• Check the server log for the detected project root

cat build/vsc_tasks_mcp/mcp_server.log

Variables Not Replaced #

Symptom: ${input:xxx} remains unchanged in the command

Solutions:

• Verify that all required arguments are passed when calling the tool
• Verify that argument names match the variable names in tasks.json (the input: prefix is not required)