MCP Server

Spark includes an MCP (Model Context Protocol) server that exposes CLI tools for AI agents and IDEs. This enables AI assistants to create projects, run development servers, build for production, and scaffold pages, endpoints, and components programmatically.

Starting the Server

Start the MCP server with:

spark mcp

The server communicates via JSON-RPC 2.0 over stdin/stdout. It runs continuously until the process is terminated.

Configuration

To use the Spark MCP server with an AI agent like Claude Desktop, add it to your MCP client configuration:

{
  "mcpServers": {
    "spark": {
      "command": "spark",
      "args": ["mcp"]
    }
  }
}

Available Tools

The MCP server exposes six tools that mirror the Spark CLI commands.

spark_init

Initialize a new Spark project with full scaffolding.

  • `project_name` (required) - The name of the project to create

Creates a complete project with `pubspec.yaml`, server entry point, example page, component, and endpoint.

spark_dev

Start the development server with hot reload.

  • `working_directory` (optional) - Project directory, defaults to current directory

The server runs in the background with hot reload and live browser refresh enabled.

spark_build

Build the project for production.

  • `working_directory` (optional) - Project directory, defaults to current directory
  • `output` (optional) - Output directory path, defaults to `"build"`
  • `clean` (optional) - Whether to clean the build directory before building, defaults to `true`

Runs code generation, compiles the server to a native executable, compiles web assets to JavaScript, and copies static files.

spark_create_page

Create a new page with routing and template.

  • `name` (required) - Page name in PascalCase, camelCase, or snake_case
  • `working_directory` (optional) - Project directory, defaults to current directory

Generates a page file in `lib/pages/` with the `@Page` annotation and route.

spark_create_endpoint

Create a new API endpoint.

  • `name` (required) - Endpoint name in PascalCase, camelCase, or snake_case
  • `working_directory` (optional) - Project directory, defaults to current directory

Generates an endpoint file in `lib/endpoints/` with the `@Endpoint` annotation.

spark_create_component

Create a new web component.

  • `name` (required) - Component name, must be multi-word (e.g., `"my_counter"`, `"NavBar"`)
  • `working_directory` (optional) - Project directory, defaults to current directory

Generates a component directory in `lib/components/` with the export wrapper and base template. Single-word names are rejected because web component tags require a hyphen.

See Code Generation for details on naming conventions and generated file structure.