Make search_issues semantic by default

Author: kelsey-myers

README.md

@@ -974,7 +974,7 @@ The following sets of tools are available:
   - `owner`: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub issues search syntax (string, required)
+  - `query`: The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR. (string, required)
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 

docs/feature-flags.md

@@ -413,7 +413,7 @@ runtime behavior (such as output formatting) won't appear here.
   - `owner`: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub issues search syntax (string, required)
+  - `query`: The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR. (string, required)
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 

docs/insiders-features.md

@@ -208,7 +208,7 @@ The list below is generated from the Go source. It covers tool **inventory and s
   - `owner`: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub issues search syntax (string, required)
+  - `query`: The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR. (string, required)
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 

internal/ghmcp/server.go

@@ -138,6 +138,11 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		return nil, fmt.Errorf("failed to parse API host: %w", err)
 	}
 
+	hostType, err := utils.ParseHostType(cfg.Host)
+	if err != nil {
+		return nil, fmt.Errorf("failed to classify API host: %w", err)
+	}
+
 	clients, err := createGitHubClients(cfg, apiHost)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create GitHub clients: %w", err)
@@ -165,7 +170,7 @@ func NewStdioMCPServer(ctx context.Context, cfg github.MCPServerConfig) (*mcp.Se
 		obs,
 	)
 	// Build and register the tool/resource/prompt inventory
-	inventoryBuilder := github.NewInventory(cfg.Translator).
+	inventoryBuilder := github.NewInventory(cfg.Translator, github.WithHost(hostType)).
 		WithDeprecatedAliases(github.DeprecatedToolAliases).
 		WithReadOnly(cfg.ReadOnly).
 		WithToolsets(github.ResolvedEnabledToolsets(cfg.EnabledToolsets, cfg.EnabledTools)).

pkg/github/__toolsnaps__/search_issues.snap

@@ -4,7 +4,7 @@
     "readOnlyHint": true,
     "title": "Search issues"
   },
-  "description": "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue",
+  "description": "Search issues using natural-language semantic matching. Best for conceptual or paraphrased queries (e.g. \"login fails after password reset\"). Already scoped to is:issue.",
   "inputSchema": {
     "properties": {
       "order": {
@@ -31,7 +31,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub issues search syntax",
+        "description": "The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR.",
         "type": "string"
       },
       "repo": {

pkg/github/__toolsnaps__/search_issues_ff_fields_param.snap

@@ -4,7 +4,7 @@
     "readOnlyHint": true,
     "title": "Search issues"
   },
-  "description": "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue",
+  "description": "Search issues using natural-language semantic matching. Best for conceptual or paraphrased queries (e.g. \"login fails after password reset\"). Already scoped to is:issue.",
   "inputSchema": {
     "properties": {
       "fields": {
@@ -64,7 +64,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub issues search syntax",
+        "description": "The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR.",
         "type": "string"
       },
       "repo": {

pkg/github/inventory.go

@@ -10,9 +10,9 @@ import (
 // This function is stateless - no dependencies are captured.
 // Handlers are generated on-demand during registration via RegisterAll(ctx, server, deps).
 // The "default" keyword in WithToolsets will expand to toolsets marked with Default: true.
-func NewInventory(t translations.TranslationHelperFunc) *inventory.Builder {
+func NewInventory(t translations.TranslationHelperFunc, opts ...ToolOption) *inventory.Builder {
 	return inventory.NewBuilder().
-		SetTools(AllTools(t)).
+		SetTools(AllTools(t, opts...)).
 		SetResources(AllResources(t)).
 		SetPrompts(AllPrompts(t))
 }

pkg/github/issues.go

@@ -1601,8 +1601,8 @@ func ReprioritizeSubIssue(ctx context.Context, client *github.Client, owner stri
 // LegacySearchIssues register under the tool name "search_issues"; exactly one is
 // active for any given request thanks to mutually exclusive FeatureFlagEnable /
 // FeatureFlagDisable annotations.
-func SearchIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
-	st := searchIssuesTool(t, true)
+func SearchIssues(t translations.TranslationHelperFunc, opts ...ToolOption) inventory.ServerTool {
+	st := searchIssuesTool(t, true, newToolConfig(opts))
 	st.FeatureFlagEnable = FeatureFlagFieldsParam
 	return st
 }
@@ -1612,23 +1612,50 @@ func SearchIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
 // filters results, so it acts as the kill switch when the flag is off. It owns
 // the canonical search_issues.snap; the flag-enabled variant owns
 // search_issues_ff_<flag>.snap. Delete this function when the flag is removed.
-func LegacySearchIssues(t translations.TranslationHelperFunc) inventory.ServerTool {
-	st := searchIssuesTool(t, false)
+func LegacySearchIssues(t translations.TranslationHelperFunc, opts ...ToolOption) inventory.ServerTool {
+	st := searchIssuesTool(t, false, newToolConfig(opts))
 	st.FeatureFlagDisable = []string{FeatureFlagFieldsParam}
 	return st
 }
 
+// The two search engines want opposite things from a caller, so steering advice
+// for one is counterproductive for the other: semantic rewards paraphrased
+// natural language and degrades on boolean operators, while lexical needs the
+// caller's literal keywords and handles OR fine. The description has to describe
+// the engine the host will actually use.
+const (
+	searchIssuesSemanticDescription = "Search issues using natural-language semantic matching. Best for conceptual or paraphrased queries (e.g. \"login fails after password reset\"). Already scoped to is:issue."
+	searchIssuesLexicalDescription  = "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue"
+
+	searchIssuesSemanticQueryDescription = "The search query, as natural language. When the user gives alternative wordings, include them as plain words rather than joining them with OR."
+	searchIssuesLexicalQueryDescription  = "Search query using GitHub issues search syntax"
+)
+
 // searchIssuesTool builds the search_issues tool. When includeFields is true the
 // tool advertises the optional `fields` parameter, filters each result to the
 // requested subset, and emits fields telemetry. When false it is the original
 // tool with no fields parameter and no filtering.
-func searchIssuesTool(t translations.TranslationHelperFunc, includeFields bool) inventory.ServerTool {
+func searchIssuesTool(t translations.TranslationHelperFunc, includeFields bool, cfg toolConfig) inventory.ServerTool {
+	// Semantic is the default; however as it is not available on GHES, we fall back to
+	// lexical search for that host type.
+	mode := searchModeSemantic
+	if cfg.hostType == utils.HostTypeGHES {
+		mode = searchModeLexical
+	}
+
+	toolDescription := searchIssuesSemanticDescription
+	queryDescription := searchIssuesSemanticQueryDescription
+	if mode == searchModeLexical {
+		toolDescription = searchIssuesLexicalDescription
+		queryDescription = searchIssuesLexicalQueryDescription
+	}
+
 	schema := &jsonschema.Schema{
 		Type: "object",
 		Properties: map[string]*jsonschema.Schema{
 			"query": {
 				Type:        "string",
-				Description: "Search query using GitHub issues search syntax",
+				Description: queryDescription,
 			},
 			"owner": {
 				Type:        "string",
@@ -1675,7 +1702,7 @@ func searchIssuesTool(t translations.TranslationHelperFunc, includeFields bool)
 		ToolsetMetadataIssues,
 		mcp.Tool{
 			Name:        "search_issues",
-			Description: t("TOOL_SEARCH_ISSUES_DESCRIPTION", "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue"),
+			Description: t("TOOL_SEARCH_ISSUES_DESCRIPTION", toolDescription),
 			Annotations: &mcp.ToolAnnotations{
 				Title:        t("TOOL_SEARCH_ISSUES_USER_TITLE", "Search issues"),
 				ReadOnlyHint: true,
@@ -1692,7 +1719,7 @@ func searchIssuesTool(t translations.TranslationHelperFunc, includeFields bool)
 				}
 				options = append(options, withFieldsFiltering(deps, "search_issues", fields))
 			}
-			result, err := searchIssuesHandler(ctx, deps, args, options...)
+			result, err := searchIssuesHandler(ctx, deps, args, mode, options...)
 			return result, nil, err
 		})
 }
@@ -1960,10 +1987,15 @@ func fetchIssueReadEnrichment(ctx context.Context, gqlClient *githubv4.Client, n
 // searchIssuesHandler runs the REST issues search, enriches each hit with custom field values
 // fetched via a single follow-up GraphQL nodes() query, and applies any post-process options
 // (e.g. IFC labelling).
-func searchIssuesHandler(ctx context.Context, deps ToolDependencies, args map[string]any, options ...searchOption) (*mcp.CallToolResult, error) {
+func searchIssuesHandler(ctx context.Context, deps ToolDependencies, args map[string]any, mode searchMode, options ...searchOption) (*mcp.CallToolResult, error) {
 	const errorPrefix = "failed to search issues"
 
-	query, opts, err := prepareSearchArgs(args, "issue")
+	cfg := searchConfig{}
+	for _, opt := range options {
+		opt(&cfg)
+	}
+
+	query, opts, err := prepareSearchArgs(args, "issue", mode)
 	if err != nil {
 		return utils.NewToolResultError(err.Error()), nil
 	}
@@ -2013,11 +2045,6 @@ func searchIssuesHandler(ctx context.Context, deps ToolDependencies, args map[st
 		Items:             items,
 	}
 
-	cfg := searchConfig{}
-	for _, opt := range options {
-		opt(&cfg)
-	}
-
 	filtered := false
 	var payload any = response
 	if len(cfg.fields) > 0 {

pkg/github/issues_test.go

@@ -874,11 +874,12 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue repo:owner/repo is:open",
-						"sort":     "created",
-						"order":    "desc",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue repo:owner/repo is:open",
+						"sort":        "created",
+						"order":       "desc",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -900,11 +901,12 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "repo:test-owner/test-repo is:issue is:open",
-						"sort":     "created",
-						"order":    "asc",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "repo:test-owner/test-repo is:issue is:open",
+						"sort":        "created",
+						"order":       "asc",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -926,9 +928,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue bug",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue bug",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -947,9 +950,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue feature",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue feature",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -979,9 +983,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "repo:github/github-mcp-server is:issue is:open (label:critical OR label:urgent)",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "repo:github/github-mcp-server is:issue is:open (label:critical OR label:urgent)",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -999,9 +1004,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue repo:github/github-mcp-server critical",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue repo:github/github-mcp-server critical",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -1021,9 +1027,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue repo:octocat/Hello-World bug",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue repo:octocat/Hello-World bug",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -1041,9 +1048,10 @@ func Test_SearchIssues(t *testing.T) {
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "repo:github/github-mcp-server is:issue (label:critical OR label:urgent OR label:high-priority OR label:blocker)",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "repo:github/github-mcp-server is:issue (label:critical OR label:urgent OR label:high-priority OR label:blocker)",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),
@@ -1064,6 +1072,7 @@ func Test_SearchIssues(t *testing.T) {
 						"q":               "is:issue field.priority:P1",
 						"page":            "1",
 						"per_page":        "30",
+						"search_type":     "semantic",
 						"advanced_search": "true",
 					},
 				).andThen(
@@ -1077,14 +1086,15 @@ func Test_SearchIssues(t *testing.T) {
 			expectedResult: mockSearchResult,
 		},
 		{
-			name: "query without field. qualifier does not set advanced_search",
+			name: "semantic search sets search_type",
 			mockedClient: MockHTTPClientWithHandlers(map[string]http.HandlerFunc{
 				GetSearchIssues: expectQueryParams(
 					t,
 					map[string]string{
-						"q":        "is:issue is:open",
-						"page":     "1",
-						"per_page": "30",
+						"q":           "is:issue is:open",
+						"page":        "1",
+						"per_page":    "30",
+						"search_type": "semantic",
 					},
 				).andThen(
 					mockResponse(t, http.StatusOK, mockSearchResult),