gopls/internal/mcp: add diagnostics tool

The diagnostics tool returns the error for the given file. This helps LLM
to self-correct the code change it made.

The input parameter's URI is required but range is marked as optional.

For golang/go#73580

Change-Id: Ia1b944036497991108c3bf458beeb11148f41203
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682515
Reviewed-by: Alan Donovan <[email protected]>
Auto-Submit: Hongxiang Jiang <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: h9jiang

gopls/internal/mcp/context.go

@@ -27,8 +27,6 @@ import (
 )
 
 type ContextParams struct {
-	// TODO(hxjiang): experiment if the LLM can correctly provide the right
-	// location information.
 	Location protocol.Location `json:"location"`
 }
 

gopls/internal/mcp/diagnostics.go

@@ -0,0 +1,51 @@
+// Copyright 2025 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package mcp
+
+// This file defines the "diagnostics" operation, which is responsible for
+// returning diagnostics for the input file.
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"golang.org/x/tools/gopls/internal/cache"
+	"golang.org/x/tools/gopls/internal/golang"
+	"golang.org/x/tools/gopls/internal/protocol"
+	"golang.org/x/tools/internal/mcp"
+)
+
+type DiagnosticsParams struct {
+	Location protocol.Location `json:"location"`
+}
+
+func diagnosticsHandler(ctx context.Context, session *cache.Session, params *mcp.CallToolParamsFor[DiagnosticsParams]) (*mcp.CallToolResultFor[struct{}], error) {
+	fh, snapshot, release, err := session.FileOf(ctx, params.Arguments.Location.URI)
+	if err != nil {
+		return nil, err
+	}
+	defer release()
+
+	diagnostics, err := golang.DiagnoseFile(ctx, snapshot, fh.URI())
+	if err != nil {
+		return nil, err
+	}
+
+	var builder strings.Builder
+	if len(diagnostics) == 0 {
+		builder.WriteString("No diagnostics")
+	} else {
+		for _, d := range diagnostics {
+			fmt.Fprintf(&builder, "%d:%d-%d:%d: [%s] %s\n", d.Range.Start.Line, d.Range.Start.Character, d.Range.End.Line, d.Range.End.Character, d.Severity, d.Message)
+		}
+	}
+
+	return &mcp.CallToolResultFor[struct{}]{
+		Content: []*mcp.Content{
+			mcp.NewTextContent(builder.String()),
+		},
+	}, nil
+}

gopls/internal/mcp/mcp.go

@@ -136,6 +136,37 @@ func newServer(session *cache.Session) *mcp.Server {
 					mcp.Property("uri", mcp.Description("URI of the text document")),
 					mcp.Property("range",
 						mcp.Description("range within text document"),
+						mcp.Required(false),
+						mcp.Property(
+							"start",
+							mcp.Description("start position of range"),
+							mcp.Property("line", mcp.Description("line number (zero-based)")),
+							mcp.Property("character", mcp.Description("column number (zero-based, UTF-16 encoding)")),
+						),
+						mcp.Property(
+							"end",
+							mcp.Description("end position of range"),
+							mcp.Property("line", mcp.Description("line number (zero-based)")),
+							mcp.Property("character", mcp.Description("column number (zero-based, UTF-16 encoding)")),
+						),
+					),
+				),
+			),
+		),
+		mcp.NewTool(
+			"diagnostics",
+			"Provide diagnostics for a region within a Go file",
+			func(ctx context.Context, _ *mcp.ServerSession, request *mcp.CallToolParamsFor[DiagnosticsParams]) (*mcp.CallToolResultFor[struct{}], error) {
+				return diagnosticsHandler(ctx, session, request)
+			},
+			mcp.Input(
+				mcp.Property(
+					"location",
+					mcp.Description("location inside of a text file"),
+					mcp.Property("uri", mcp.Description("URI of the text document")),
+					mcp.Property("range",
+						mcp.Description("range within text document"),
+						mcp.Required(false),
 						mcp.Property(
 							"start",
 							mcp.Description("start position of range"),
@@ -153,6 +184,5 @@ func newServer(session *cache.Session) *mcp.Server {
 			),
 		),
 	)
-
 	return s
 }

gopls/internal/server/diagnostics.go

@@ -212,7 +212,7 @@ func (s *server) diagnoseSnapshot(ctx context.Context, snapshot *cache.Snapshot,
 		// The second phase runs after the delay, and does everything.
 
 		if len(changedURIs) > 0 {
-			diagnostics, err := s.diagnoseChangedFiles(ctx, snapshot, changedURIs)
+			diagnostics, err := diagnoseChangedFiles(ctx, snapshot, changedURIs)
 			if err != nil {
 				if ctx.Err() == nil {
 					event.Error(ctx, "warning: while diagnosing changed files", err, snapshot.Labels()...)
@@ -239,7 +239,7 @@ func (s *server) diagnoseSnapshot(ctx context.Context, snapshot *cache.Snapshot,
 	s.updateDiagnostics(ctx, snapshot, diagnostics, true)
 }
 
-func (s *server) diagnoseChangedFiles(ctx context.Context, snapshot *cache.Snapshot, uris []protocol.DocumentURI) (diagMap, error) {
+func diagnoseChangedFiles(ctx context.Context, snapshot *cache.Snapshot, uris []protocol.DocumentURI) (diagMap, error) {
 	ctx, done := event.Start(ctx, "server.diagnoseChangedFiles", snapshot.Labels()...)
 	defer done()
 

gopls/internal/test/marker/testdata/mcptools/context.txt

@@ -1,4 +1,4 @@
-This test exercises mcp tool context.
+This test exercises the "context" MCP tool.
 
 -- flags --
 -mcp

gopls/internal/test/marker/testdata/mcptools/diagnostics.txt

@@ -0,0 +1,39 @@
+This test exercises the "diagnostics" MCP tool.
+
+-- flags --
+-mcp
+
+-- go.mod --
+module example.com
+
+-- a/main.go --
+package main
+
+func foo() {} //@loc(foo, "foo")
+
+//@mcptool("diagnostics", `{}`, foo, output=unused)
+//@diag(foo, re"unused")
+
+-- @unused --
+2:5-2:8: [Information] function "foo" is unused
+-- b/main.go --
+package main
+
+func _() {
+	_ = deprecated([]string{"a"}, "a") //@loc(inline, "deprecated")
+}
+
+//go:fix inline
+func deprecated(slice []string, s string) bool {
+	return proposed(slice, s, true)
+}
+
+func proposed(_ []string, _ string, _ bool) bool {
+	return false // fake
+}
+
+//@mcptool("diagnostics", `{}`, inline, output=bloop)
+//@diag(inline, re"inline")
+
+-- @bloop --
+3:5-3:35: [Hint] Call of main.deprecated should be inlined