MCP Server

Devlish includes a built-in MCP (Model Context Protocol) server that exposes Devlish programs as callable tools. Any LLM client that supports MCP can discover and invoke your programs.

Starting the Server

devlish mcp

The server communicates over stdin/stdout using JSON-RPC, following the MCP 2024-11-05 protocol.

Tool Discovery

Point the server at directories containing your tools:

devlish mcp --tools-dir ~/.devlish/tools --tools-dir ./my-project/tools

The default tools directory is ~/.devlish/tools/. Each directory is scanned for a devlish.toml manifest that declares available tools.

devlish.toml Manifest

Each tool project contains a devlish.toml that declares metadata and tool definitions:

name = "invoice-processor"
description = "Process and validate invoices"

[[tools]]
name = "validate_invoice"
description = "Validate an invoice against business rules"
source = "validate_invoice.dvl"

  [tools.parameters.invoice_path]
  type = "string"
  description = "Path to the invoice JSON file"
  required = true

  [tools.parameters.strict_mode]
  type = "boolean"
  description = "Whether to enforce all optional rules"

[[tools]]
name = "summarize_invoices"
description = "Produce a summary report for a batch of invoices"
source = "summarize.dvl"

  [tools.parameters.directory]
  type = "string"
  description = "Directory containing invoice files"
  required = true

Built-in Tools

The MCP server always exposes four built-in tools:

Tool	Description
compile	Compile a .dvl source string to bytecode JSON
run	Compile and run a .dvl source string, returning results
validate	Check if source code is syntactically valid
lint	Lint source code and return structured diagnostics

Claude Desktop Configuration

Add Devlish to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "devlish": {
      "command": "devlish",
      "args": ["mcp", "--tools-dir", "/path/to/your/tools"]
    }
  }
}

Cursor Configuration

For Cursor, add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "devlish": {
      "command": "devlish",
      "args": ["mcp", "--tools-dir", "./devlish/tools"]
    }
  }
}

How Ask Maps to Tool Inputs

When a .dvl program uses Ask statements, those become tool input parameters. The MCP client provides them as the arguments object:

Ask "What is the project ID?" as project id
Ask "What credit type?" as credit type

The LLM calls the tool with:

{
  "project_id": "PROJ-42",
  "credit_type": "ITC"
}

Input values are injected into the program’s context before execution begins.

Tool Output

Programs that use Respond with return structured JSON to the LLM. Programs that use Print or Export return their output as text content. Failed programs return error messages that the LLM can interpret and retry.