feat(cli): add coder exp mcp command (#17066)

Adds a `coder exp mcp` command which will start a local MCP server listening on stdio with the following capabilities: * Show logged in user (`coder whoami`) * List workspaces (`coder list`) * List templates (`coder templates list`) * Start a workspace (`coder start`) * Stop a workspace (`coder stop`) * Fetch a single workspace (no direct CLI analogue) * Execute a command inside a workspace (`coder exp rpty`) * Report the status of a task (currently a no-op, pending task support) This can be tested as follows: ``` # Start a local Coder server. ./scripts/develop.sh # Start a workspace. Currently, creating workspaces is not supported. ./scripts/coder-dev.sh create -t docker --yes # Add the MCP to your Claude config. claude mcp add coder ./scripts/coder-dev.sh exp mcp # Tell Claude to do something Coder-related. You may need to nudge it to use the tools. claude 'start a docker workspace and tell me what version of python is installed' ```
2026-09-24 15:04:27 +08:00 · 2025-03-31 18:52:09 +01:00
parent 8ea956fc11
commit 057cbd4d80
9 changed files with 1469 additions and 5 deletions
@@ -11,7 +11,9 @@ import (
 	"strings"
 	"testing"

+	"github.com/google/go-cmp/cmp"
 	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"

 	"github.com/coder/coder/v2/cli/config"
@@ -117,11 +119,7 @@ func TestGoldenFile(t *testing.T, fileName string, actual []byte, replacements m
 	require.NoError(t, err, "read golden file, run \"make gen/golden-files\" and commit the changes")

 	expected = normalizeGoldenFile(t, expected)
-	require.Equal(
-		t, string(expected), string(actual),
-		"golden file mismatch: %s, run \"make gen/golden-files\", verify and commit the changes",
-		goldenPath,
-	)
+	assert.Empty(t, cmp.Diff(string(expected), string(actual)), "golden file mismatch (-want +got): %s, run \"make gen/golden-files\", verify and commit the changes", goldenPath)
 }

 // normalizeGoldenFile replaces any strings that are system or timing dependent
@@ -13,6 +13,7 @@ func (r *RootCmd) expCmd() *serpent.Command {
 		Children: []*serpent.Command{
 			r.scaletestCmd(),
 			r.errorExample(),
+			r.mcpCommand(),
 			r.promptExample(),
 			r.rptyCommand(),
 		},
@@ -0,0 +1,284 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log"
+	"os"
+	"path/filepath"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+	"github.com/coder/coder/v2/cli/cliui"
+	"github.com/coder/coder/v2/codersdk"
+	codermcp "github.com/coder/coder/v2/mcp"
+	"github.com/coder/serpent"
+)
+
+func (r *RootCmd) mcpCommand() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "mcp",
+		Short: "Run the Coder MCP server and configure it to work with AI tools.",
+		Long:  "The Coder MCP server allows you to automatically create workspaces with parameters.",
+		Handler: func(i *serpent.Invocation) error {
+			return i.Command.HelpHandler(i)
+		},
+		Children: []*serpent.Command{
+			r.mcpConfigure(),
+			r.mcpServer(),
+		},
+	}
+	return cmd
+}
+
+func (r *RootCmd) mcpConfigure() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "configure",
+		Short: "Automatically configure the MCP server.",
+		Handler: func(i *serpent.Invocation) error {
+			return i.Command.HelpHandler(i)
+		},
+		Children: []*serpent.Command{
+			r.mcpConfigureClaudeDesktop(),
+			r.mcpConfigureClaudeCode(),
+			r.mcpConfigureCursor(),
+		},
+	}
+	return cmd
+}
+
+func (*RootCmd) mcpConfigureClaudeDesktop() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "claude-desktop",
+		Short: "Configure the Claude Desktop server.",
+		Handler: func(_ *serpent.Invocation) error {
+			configPath, err := os.UserConfigDir()
+			if err != nil {
+				return err
+			}
+			configPath = filepath.Join(configPath, "Claude")
+			err = os.MkdirAll(configPath, 0o755)
+			if err != nil {
+				return err
+			}
+			configPath = filepath.Join(configPath, "claude_desktop_config.json")
+			_, err = os.Stat(configPath)
+			if err != nil {
+				if !os.IsNotExist(err) {
+					return err
+				}
+			}
+			contents := map[string]any{}
+			data, err := os.ReadFile(configPath)
+			if err != nil {
+				if !os.IsNotExist(err) {
+					return err
+				}
+			} else {
+				err = json.Unmarshal(data, &contents)
+				if err != nil {
+					return err
+				}
+			}
+			binPath, err := os.Executable()
+			if err != nil {
+				return err
+			}
+			contents["mcpServers"] = map[string]any{
+				"coder": map[string]any{"command": binPath, "args": []string{"exp", "mcp", "server"}},
+			}
+			data, err = json.MarshalIndent(contents, "", "  ")
+			if err != nil {
+				return err
+			}
+			err = os.WriteFile(configPath, data, 0o600)
+			if err != nil {
+				return err
+			}
+			return nil
+		},
+	}
+	return cmd
+}
+
+func (*RootCmd) mcpConfigureClaudeCode() *serpent.Command {
+	cmd := &serpent.Command{
+		Use:   "claude-code",
+		Short: "Configure the Claude Code server.",
+		Handler: func(_ *serpent.Invocation) error {
+			return nil
+		},
+	}
+	return cmd
+}
+
+func (*RootCmd) mcpConfigureCursor() *serpent.Command {
+	var project bool
+	cmd := &serpent.Command{
+		Use:   "cursor",
+		Short: "Configure Cursor to use Coder MCP.",
+		Options: serpent.OptionSet{
+			serpent.Option{
+				Flag:        "project",
+				Env:         "CODER_MCP_CURSOR_PROJECT",
+				Description: "Use to configure a local project to use the Cursor MCP.",
+				Value:       serpent.BoolOf(&project),
+			},
+		},
+		Handler: func(_ *serpent.Invocation) error {
+			dir, err := os.Getwd()
+			if err != nil {
+				return err
+			}
+			if !project {
+				dir, err = os.UserHomeDir()
+				if err != nil {
+					return err
+				}
+			}
+			cursorDir := filepath.Join(dir, ".cursor")
+			err = os.MkdirAll(cursorDir, 0o755)
+			if err != nil {
+				return err
+			}
+			mcpConfig := filepath.Join(cursorDir, "mcp.json")
+			_, err = os.Stat(mcpConfig)
+			contents := map[string]any{}
+			if err != nil {
+				if !os.IsNotExist(err) {
+					return err
+				}
+			} else {
+				data, err := os.ReadFile(mcpConfig)
+				if err != nil {
+					return err
+				}
+				// The config can be empty, so we don't want to return an error if it is.
+				if len(data) > 0 {
+					err = json.Unmarshal(data, &contents)
+					if err != nil {
+						return err
+					}
+				}
+			}
+			mcpServers, ok := contents["mcpServers"].(map[string]any)
+			if !ok {
+				mcpServers = map[string]any{}
+			}
+			binPath, err := os.Executable()
+			if err != nil {
+				return err
+			}
+			mcpServers["coder"] = map[string]any{
+				"command": binPath,
+				"args":    []string{"exp", "mcp", "server"},
+			}
+			contents["mcpServers"] = mcpServers
+			data, err := json.MarshalIndent(contents, "", "  ")
+			if err != nil {
+				return err
+			}
+			err = os.WriteFile(mcpConfig, data, 0o600)
+			if err != nil {
+				return err
+			}
+			return nil
+		},
+	}
+	return cmd
+}
+
+func (r *RootCmd) mcpServer() *serpent.Command {
+	var (
+		client       = new(codersdk.Client)
+		instructions string
+		allowedTools []string
+	)
+	return &serpent.Command{
+		Use: "server",
+		Handler: func(inv *serpent.Invocation) error {
+			return mcpServerHandler(inv, client, instructions, allowedTools)
+		},
+		Short: "Start the Coder MCP server.",
+		Middleware: serpent.Chain(
+			r.InitClient(client),
+		),
+		Options: []serpent.Option{
+			{
+				Name:        "instructions",
+				Description: "The instructions to pass to the MCP server.",
+				Flag:        "instructions",
+				Value:       serpent.StringOf(&instructions),
+			},
+			{
+				Name:        "allowed-tools",
+				Description: "Comma-separated list of allowed tools. If not specified, all tools are allowed.",
+				Flag:        "allowed-tools",
+				Value:       serpent.StringArrayOf(&allowedTools),
+			},
+		},
+	}
+}
+
+func mcpServerHandler(inv *serpent.Invocation, client *codersdk.Client, instructions string, allowedTools []string) error {
+	ctx, cancel := context.WithCancel(inv.Context())
+	defer cancel()
+
+	logger := slog.Make(sloghuman.Sink(inv.Stdout))
+
+	me, err := client.User(ctx, codersdk.Me)
+	if err != nil {
+		cliui.Errorf(inv.Stderr, "Failed to log in to the Coder deployment.")
+		cliui.Errorf(inv.Stderr, "Please check your URL and credentials.")
+		cliui.Errorf(inv.Stderr, "Tip: Run `coder whoami` to check your credentials.")
+		return err
+	}
+	cliui.Infof(inv.Stderr, "Starting MCP server")
+	cliui.Infof(inv.Stderr, "User          : %s", me.Username)
+	cliui.Infof(inv.Stderr, "URL           : %s", client.URL)
+	cliui.Infof(inv.Stderr, "Instructions  : %q", instructions)
+	if len(allowedTools) > 0 {
+		cliui.Infof(inv.Stderr, "Allowed Tools : %v", allowedTools)
+	}
+	cliui.Infof(inv.Stderr, "Press Ctrl+C to stop the server")
+
+	// Capture the original stdin, stdout, and stderr.
+	invStdin := inv.Stdin
+	invStdout := inv.Stdout
+	invStderr := inv.Stderr
+	defer func() {
+		inv.Stdin = invStdin
+		inv.Stdout = invStdout
+		inv.Stderr = invStderr
+	}()
+
+	options := []codermcp.Option{
+		codermcp.WithInstructions(instructions),
+		codermcp.WithLogger(&logger),
+	}
+
+	// Add allowed tools option if specified
+	if len(allowedTools) > 0 {
+		options = append(options, codermcp.WithAllowedTools(allowedTools))
+	}
+
+	srv := codermcp.NewStdio(client, options...)
+	srv.SetErrorLogger(log.New(invStderr, "", log.LstdFlags))
+
+	done := make(chan error)
+	go func() {
+		defer close(done)
+		srvErr := srv.Listen(ctx, invStdin, invStdout)
+		done <- srvErr
+	}()
+
+	if err := <-done; err != nil {
+		if !errors.Is(err, context.Canceled) {
+			cliui.Errorf(inv.Stderr, "Failed to start the MCP server: %s", err)
+			return err
+		}
+	}
+
+	return nil
+}
@@ -0,0 +1,142 @@
+package cli_test
+
+import (
+	"context"
+	"encoding/json"
+	"runtime"
+	"slices"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/coder/coder/v2/cli/clitest"
+	"github.com/coder/coder/v2/coderd/coderdtest"
+	"github.com/coder/coder/v2/pty/ptytest"
+	"github.com/coder/coder/v2/testutil"
+)
+
+func TestExpMcp(t *testing.T) {
+	t.Parallel()
+
+	// Reading to / writing from the PTY is flaky on non-linux systems.
+	if runtime.GOOS != "linux" {
+		t.Skip("skipping on non-linux")
+	}
+
+	t.Run("AllowedTools", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+		cancelCtx, cancel := context.WithCancel(ctx)
+		t.Cleanup(cancel)
+
+		// Given: a running coder deployment
+		client := coderdtest.New(t, nil)
+		_ = coderdtest.CreateFirstUser(t, client)
+
+		// Given: we run the exp mcp command with allowed tools set
+		inv, root := clitest.New(t, "exp", "mcp", "server", "--allowed-tools=coder_whoami,coder_list_templates")
+		inv = inv.WithContext(cancelCtx)
+
+		pty := ptytest.New(t)
+		inv.Stdin = pty.Input()
+		inv.Stdout = pty.Output()
+		clitest.SetupConfig(t, client, root)
+
+		cmdDone := make(chan struct{})
+		go func() {
+			defer close(cmdDone)
+			err := inv.Run()
+			assert.NoError(t, err)
+		}()
+
+		// When: we send a tools/list request
+		toolsPayload := `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`
+		pty.WriteLine(toolsPayload)
+		_ = pty.ReadLine(ctx) // ignore echoed output
+		output := pty.ReadLine(ctx)
+
+		cancel()
+		<-cmdDone
+
+		// Then: we should only see the allowed tools in the response
+		var toolsResponse struct {
+			Result struct {
+				Tools []struct {
+					Name string `json:"name"`
+				} `json:"tools"`
+			} `json:"result"`
+		}
+		err := json.Unmarshal([]byte(output), &toolsResponse)
+		require.NoError(t, err)
+		require.Len(t, toolsResponse.Result.Tools, 2, "should have exactly 2 tools")
+		foundTools := make([]string, 0, 2)
+		for _, tool := range toolsResponse.Result.Tools {
+			foundTools = append(foundTools, tool.Name)
+		}
+		slices.Sort(foundTools)
+		require.Equal(t, []string{"coder_list_templates", "coder_whoami"}, foundTools)
+	})
+
+	t.Run("OK", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+		cancelCtx, cancel := context.WithCancel(ctx)
+		t.Cleanup(cancel)
+
+		client := coderdtest.New(t, nil)
+		_ = coderdtest.CreateFirstUser(t, client)
+		inv, root := clitest.New(t, "exp", "mcp", "server")
+		inv = inv.WithContext(cancelCtx)
+
+		pty := ptytest.New(t)
+		inv.Stdin = pty.Input()
+		inv.Stdout = pty.Output()
+		clitest.SetupConfig(t, client, root)
+
+		cmdDone := make(chan struct{})
+		go func() {
+			defer close(cmdDone)
+			err := inv.Run()
+			assert.NoError(t, err)
+		}()
+
+		payload := `{"jsonrpc":"2.0","id":1,"method":"initialize"}`
+		pty.WriteLine(payload)
+		_ = pty.ReadLine(ctx) // ignore echoed output
+		output := pty.ReadLine(ctx)
+		cancel()
+		<-cmdDone
+
+		// Ensure the initialize output is valid JSON
+		t.Logf("/initialize output: %s", output)
+		var initializeResponse map[string]interface{}
+		err := json.Unmarshal([]byte(output), &initializeResponse)
+		require.NoError(t, err)
+		require.Equal(t, "2.0", initializeResponse["jsonrpc"])
+		require.Equal(t, 1.0, initializeResponse["id"])
+		require.NotNil(t, initializeResponse["result"])
+	})
+
+	t.Run("NoCredentials", func(t *testing.T) {
+		t.Parallel()
+
+		ctx := testutil.Context(t, testutil.WaitShort)
+		cancelCtx, cancel := context.WithCancel(ctx)
+		t.Cleanup(cancel)
+
+		client := coderdtest.New(t, nil)
+		inv, root := clitest.New(t, "exp", "mcp", "server")
+		inv = inv.WithContext(cancelCtx)
+
+		pty := ptytest.New(t)
+		inv.Stdin = pty.Input()
+		inv.Stdout = pty.Output()
+		clitest.SetupConfig(t, client, root)
+
+		err := inv.Run()
+		assert.ErrorContains(t, err, "your session has expired")
+	})
+}