Allow MCP dictionary searches to return Markdown

The search_dictionary MCP tool now accepts an optional format parameter. Omitting it preserves the existing JSON text output, while format=markdown converts each HTML definition through html-to-markdown and returns Markdown text content for clients that prefer readable dictionary output.

Constraint: Frontend copy behavior is intentionally unchanged for this iteration
Constraint: format must remain optional so existing MCP clients continue working
Rejected: Changing the default MCP output to Markdown | would break clients expecting the current JSON text content
Confidence: high
Scope-risk: moderate
Directive: Keep format handling backward-compatible; add new formats explicitly instead of changing the default
Tested: cd backend && go test ./...
Tested: cd backend && go vet ./...
Tested: git diff --check

Author: Owl Builder

README.md

@@ -116,6 +116,7 @@ The initial SSE connection must include the token. After the connection is estab
   - Searches dictionaries available to the token owner.
   - Accepts `query`.
   - Optional: `dictionary_id` or `dictionary_name`.
+  - Optional: `format=markdown` returns Markdown text content for the MCP response; omit `format` to keep the default JSON text output.
   - If no dictionary is specified, Owl searches all dictionaries available to the token user, matching the web search scope.
 
 ### Token management

README_ZH.md

@@ -117,6 +117,7 @@ Authorization: Bearer <MCP_TOKEN>
   - 查询当前 token 用户可访问的词典。
   - 必填：`query`
   - 可选：`dictionary_id` 或 `dictionary_name`
+  - 可选：`format=markdown` 会让 MCP 响应的文本内容以 Markdown 输出；不传 `format` 时保持默认 JSON 文本输出。
   - 如果不指定词典，则按 Web 查询相同范围搜索全部可访问词典。
 
 ### Token 管理

backend/go.mod

@@ -4,6 +4,7 @@ go 1.25.0
 
 require (
 	entgo.io/ent v0.14.6
+	github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0
 	github.com/go-sql-driver/mysql v1.9.3
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/labstack/echo/v5 v5.1.0
@@ -18,6 +19,7 @@ require (
 require (
 	ariga.io/atlas v0.36.2-0.20250730182955-2c6300d0a3e1 // indirect
 	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/JohannesKaufmann/dom v0.2.0 // indirect
 	github.com/agext/levenshtein v1.2.3 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
 	github.com/bmatcuk/doublestar v1.3.4 // indirect
@@ -47,6 +49,7 @@ require (
 	github.com/zclconf/go-cty-yaml v1.1.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	golang.org/x/mod v0.34.0 // indirect
+	golang.org/x/net v0.52.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect
 	golang.org/x/text v0.36.0 // indirect

backend/go.sum

@@ -6,6 +6,10 @@ filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/DATA-DOG/go-sqlmock v1.5.0 h1:Shsta01QNfFxHCfpW6YH2STWB0MudeXXEWMr20OEh60=
 github.com/DATA-DOG/go-sqlmock v1.5.0/go.mod h1:f/Ixk793poVmq4qj/V1dPUg2JEAKC73Q5eFN3EC/SaM=
+github.com/JohannesKaufmann/dom v0.2.0 h1:1bragmEb19K8lHAqgFgqCpiPCFEZMTXzOIEjuxkUfLQ=
+github.com/JohannesKaufmann/dom v0.2.0/go.mod h1:57iSUl5RKric4bUkgos4zu6Xt5LMHUnw3TF1l5CbGZo=
+github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0 h1:mklaPbT4f/EiDr1Q+zPrEt9lgKAkVrIBtWf33d9GpVA=
+github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0/go.mod h1:D56Cl9r8M5i3UwAchE+LlLc5hPN3kJtdZNVJn06lSHU=
 github.com/agext/levenshtein v1.2.3 h1:YB2fHEn0UJagG8T1rrWknE3ZQzWM06O8AMAatNn7lmo=
 github.com/agext/levenshtein v1.2.3/go.mod h1:JEDfjyjHDjOF/1e4FlBE/PkbqA9OfWu2ki2W0IB5558=
 github.com/apparentlymart/go-textseg/v15 v15.0.0 h1:uYvfpb3DyLSCGWnctWKGj857c6ew1u1fNQOlOtuGxQY=
@@ -20,8 +24,6 @@ github.com/c0mm4nd/go-ripemd v0.0.0-20200326052756-bd1759ad7d10 h1:wJ2csnFApV9G1
 github.com/c0mm4nd/go-ripemd v0.0.0-20200326052756-bd1759ad7d10/go.mod h1:mYPR+a1fzjnHY3VFH5KL3PkEjMlVfGXP7c8rbWlkLJg=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
-github.com/clipperhouse/displaywidth v0.6.2 h1:ZDpTkFfpHOKte4RG5O/BOyf3ysnvFswpyYrV7z2uAKo=
-github.com/clipperhouse/displaywidth v0.6.2/go.mod h1:R+kHuzaYWFkTm7xoMmK1lFydbci4X2CicfbGstSGg0o=
 github.com/clipperhouse/stringish v0.1.1 h1:+NSqMOr3GR6k1FdRhhnXrLfztGzuG+VuFDfatpWHKCs=
 github.com/clipperhouse/stringish v0.1.1/go.mod h1:v/WhFtE1q0ovMta2+m+UbpZ+2/HEXNWYXQgCt4hdOzA=
 github.com/clipperhouse/uax29/v2 v2.3.0 h1:SNdx9DVUqMoBuBoW3iLOj4FQv3dN5mDtuqwuhIGpJy4=
@@ -89,14 +91,6 @@ github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOF
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e h1:fD57ERR4JtEqsWbfPhv4DMiApHyliiK5xCTNVSPiaAs=
 github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
-github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6 h1:zrbMGy9YXpIeTnGj4EljqMiZsIcE09mmF8XsD5AYOJc=
-github.com/olekukonko/cat v0.0.0-20250911104152-50322a0618f6/go.mod h1:rEKTHC9roVVicUIfZK7DYrdIoM0EOr8mK1Hj5s3JjH0=
-github.com/olekukonko/errors v1.1.0 h1:RNuGIh15QdDenh+hNvKrJkmxxjV4hcS50Db478Ou5sM=
-github.com/olekukonko/errors v1.1.0/go.mod h1:ppzxA5jBKcO1vIpCXQ9ZqgDh8iwODz6OXIGKU8r5m4Y=
-github.com/olekukonko/ll v0.1.4-0.20260115111900-9e59c2286df0 h1:jrYnow5+hy3WRDCBypUFvVKNSPPCdqgSXIE9eJDD8LM=
-github.com/olekukonko/ll v0.1.4-0.20260115111900-9e59c2286df0/go.mod h1:b52bVQRRPObe+yyBl0TxNfhesL0nedD4Cht0/zx55Ew=
-github.com/olekukonko/tablewriter v1.1.3 h1:VSHhghXxrP0JHl+0NnKid7WoEmd9/urKRJLysb70nnA=
-github.com/olekukonko/tablewriter v1.1.3/go.mod h1:9VU0knjhmMkXjnMKrZ3+L2JhhtsQ/L38BbL3CRNE8tM=
 github.com/op/go-logging v0.0.0-20160315200505-970db520ece7 h1:lDH9UUVJtmYCjyT0CI4q8xvlXPxeZ0gYCVvWbmPlp88=
 github.com/op/go-logging v0.0.0-20160315200505-970db520ece7/go.mod h1:HzydrMdWErDVzsI23lYNej1Htcns9BCg93Dk0bBINWk=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -112,16 +106,14 @@ github.com/rodaine/table v1.3.0 h1:4/3S3SVkHnVZX91EHFvAMV7K42AnJ0XuymRR2C5HlGE=
 github.com/rodaine/table v1.3.0/go.mod h1:47zRsHar4zw0jgxGxL9YtFfs7EGN6B/TaS+/Dmk4WxU=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
+github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8rc=
+github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
 github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
 github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
 github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
 github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
-github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
-github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
-github.com/spf13/cobra v1.7.0 h1:hyqWnYt1ZQShIddO5kBpj3vu05/++x6tJ6dg8EC572I=
-github.com/spf13/cobra v1.7.0/go.mod h1:uLxZILRyS/50WlhOIKD7W6V5bgeIt+4sICxh6uRMrb0=
-github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
-github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
+github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -134,6 +126,8 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
+github.com/yuin/goldmark v1.7.13 h1:GPddIs617DnBLFFVJFgpo1aBfe/4xcvMc3SB5t/D0pA=
+github.com/yuin/goldmark v1.7.13/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 github.com/zclconf/go-cty v1.14.4 h1:uXXczd9QDGsgu0i/QFR/hzI5NYCHLf6NQw/atrbnhq8=
 github.com/zclconf/go-cty v1.14.4/go.mod h1:VvMs5i0vgZdhYawQNq5kePSpLAoz8u1xvZgrPIxfnZE=
 github.com/zclconf/go-cty-yaml v1.1.0 h1:nP+jp0qPHv2IhUVqmQSzjvqAWcObN0KBkUl2rWBdig0=

backend/internal/api/mcp.go

@@ -10,6 +10,7 @@ import (
 	"owl/backend/internal/dictionary"
 	"owl/backend/pkg/version"
 
+	htmltomarkdown "github.com/JohannesKaufmann/html-to-markdown/v2"
 	echo "github.com/labstack/echo/v5"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -35,6 +36,7 @@ type listDictionariesOutput struct {
 type searchDictionaryInput struct {
 	DictionaryID   *int    `json:"dictionary_id,omitempty" jsonschema:"Optional dictionary id returned by list_dictionaries. If omitted, all accessible dictionaries are searched."`
 	DictionaryName *string `json:"dictionary_name,omitempty" jsonschema:"Optional dictionary name or title returned by list_dictionaries. Used when dictionary_id is omitted."`
+	Format         *string `json:"format,omitempty" jsonschema:"Optional text output format. Use markdown to return Markdown text content; omit to keep the default JSON text output."`
 	Query          string  `json:"query" jsonschema:"Word, phrase, or headword to look up."`
 }
 
@@ -44,6 +46,7 @@ type searchResultInfo struct {
 	Visibility     string  `json:"visibility"`
 	Word           string  `json:"word"`
 	HTML           string  `json:"html"`
+	Markdown       string  `json:"markdown,omitempty"`
 	Score          float64 `json:"score"`
 	Source         string  `json:"source"`
 }
@@ -146,6 +149,10 @@ func (s *Server) buildMCPServer(userID int) *mcp.Server {
 		if query == "" {
 			return nil, searchDictionaryOutput{}, fmt.Errorf("query is required")
 		}
+		format, err := normalizeMCPSearchFormat(input.Format)
+		if err != nil {
+			return nil, searchDictionaryOutput{}, err
+		}
 		dictionaryID := 0
 		if input.DictionaryID != nil {
 			dictionaryID = *input.DictionaryID
@@ -154,7 +161,7 @@ func (s *Server) buildMCPServer(userID int) *mcp.Server {
 		if input.DictionaryName != nil {
 			dictionaryName = *input.DictionaryName
 		}
-		dictionaryID, err := s.resolveMCPDictionaryID(ctx, userID, dictionaryID, dictionaryName)
+		dictionaryID, err = s.resolveMCPDictionaryID(ctx, userID, dictionaryID, dictionaryName)
 		if err != nil {
 			return nil, searchDictionaryOutput{}, err
 		}
@@ -163,16 +170,28 @@ func (s *Server) buildMCPServer(userID int) *mcp.Server {
 			return nil, searchDictionaryOutput{}, err
 		}
 		out := searchDictionaryOutput{Results: make([]searchResultInfo, 0, len(results))}
+		markdownRequested := format == "markdown"
 		for _, result := range results {
-			out.Results = append(out.Results, searchResultInfo{
+			item := searchResultInfo{
 				DictionaryID:   result.DictionaryID,
 				DictionaryName: result.DictionaryName,
 				Visibility:     result.Visibility,
 				Word:           result.Word,
 				HTML:           result.HTML,
 				Score:          result.Score,
 				Source:         result.Source,
-			})
+			}
+			if markdownRequested {
+				markdown, err := htmlToMarkdown(result.HTML)
+				if err != nil {
+					return nil, searchDictionaryOutput{}, fmt.Errorf("convert %q to markdown: %w", result.Word, err)
+				}
+				item.Markdown = markdown
+			}
+			out.Results = append(out.Results, item)
+		}
+		if markdownRequested {
+			return mcpMarkdownSearchResult(query, out), out, nil
 		}
 		return mcpTextResult(out), out, nil
 	})
@@ -220,6 +239,54 @@ func (s *Server) resolveMCPDictionaryID(ctx context.Context, userID int, diction
 	return 0, fmt.Errorf("dictionary %q is not available to this token", name)
 }
 
+func normalizeMCPSearchFormat(value *string) (string, error) {
+	if value == nil {
+		return "", nil
+	}
+	format := strings.ToLower(strings.TrimSpace(*value))
+	switch format {
+	case "", "json":
+		return "", nil
+	case "markdown":
+		return "markdown", nil
+	default:
+		return "", fmt.Errorf("unsupported format %q; omit format or use markdown", *value)
+	}
+}
+
+func htmlToMarkdown(html string) (string, error) {
+	markdown, err := htmltomarkdown.ConvertString(html)
+	if err != nil {
+		return "", err
+	}
+	return strings.TrimSpace(markdown), nil
+}
+
+func mcpMarkdownSearchResult(query string, out searchDictionaryOutput) *mcp.CallToolResult {
+	var builder strings.Builder
+	if strings.TrimSpace(query) != "" {
+		fmt.Fprintf(&builder, "# Search results for %s\n\n", query)
+	} else {
+		builder.WriteString("# Search results\n\n")
+	}
+	if len(out.Results) == 0 {
+		builder.WriteString("No matching entries found.")
+		return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: builder.String()}}}
+	}
+	for index, result := range out.Results {
+		if index > 0 {
+			builder.WriteString("\n\n---\n\n")
+		}
+		fmt.Fprintf(&builder, "## %s\n\n", result.Word)
+		fmt.Fprintf(&builder, "> Dictionary: %s  \n", result.DictionaryName)
+		fmt.Fprintf(&builder, "> Visibility: %s  \n", result.Visibility)
+		fmt.Fprintf(&builder, "> Source: %s  \n", result.Source)
+		fmt.Fprintf(&builder, "> Score: %.4g\n\n", result.Score)
+		builder.WriteString(strings.TrimSpace(result.Markdown))
+	}
+	return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: strings.TrimSpace(builder.String())}}}
+}
+
 func mcpTextResult(value any) *mcp.CallToolResult {
 	payload, err := json.MarshalIndent(value, "", "  ")
 	if err != nil {

backend/internal/api/mcp_schema_test.go

@@ -3,6 +3,7 @@ package api
 import (
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -49,9 +50,78 @@ func TestMCPSearchDictionaryOptionalDictionaryInput(t *testing.T) {
 		t.Fatal(err)
 	}
 	for _, field := range schema.Required {
-		if field == "dictionary_id" || field == "dictionary_name" {
+		if field == "dictionary_id" || field == "dictionary_name" || field == "format" {
 			t.Fatalf("%s should be optional in schema: %s", field, string(encoded))
 		}
 	}
 
 }
+
+func TestNormalizeMCPSearchFormatKeepsFormatOptional(t *testing.T) {
+	format, err := normalizeMCPSearchFormat(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if format != "" {
+		t.Fatalf("expected omitted format to keep default output, got %q", format)
+	}
+
+	markdown := " markdown "
+	format, err = normalizeMCPSearchFormat(&markdown)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if format != "markdown" {
+		t.Fatalf("expected markdown format, got %q", format)
+	}
+
+	jsonFormat := "json"
+	format, err = normalizeMCPSearchFormat(&jsonFormat)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if format != "" {
+		t.Fatalf("expected json format to keep default output, got %q", format)
+	}
+
+	invalid := "html"
+	if _, err := normalizeMCPSearchFormat(&invalid); err == nil {
+		t.Fatal("expected unsupported format to fail")
+	}
+}
+
+func TestHTMLToMarkdownConvertsDictionaryHTML(t *testing.T) {
+	markdown, err := htmlToMarkdown(`<p><strong>Bold</strong> text</p><ul><li>one</li></ul><a href="/search?q=owl">owl</a>`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, expected := range []string{"**Bold** text", "- one", "[owl](/search?q=owl)"} {
+		if !strings.Contains(markdown, expected) {
+			t.Fatalf("expected markdown to contain %q, got:\n%s", expected, markdown)
+		}
+	}
+}
+
+func TestMCPMarkdownSearchResultUsesMarkdownText(t *testing.T) {
+	result := mcpMarkdownSearchResult("owl", searchDictionaryOutput{Results: []searchResultInfo{{
+		DictionaryID:   1,
+		DictionaryName: "Test Dictionary",
+		Visibility:     "public",
+		Word:           "owl",
+		Markdown:       "A **bird**.",
+		Score:          1,
+		Source:         "exact",
+	}}})
+	if len(result.Content) != 1 {
+		t.Fatalf("expected one text content item, got %d", len(result.Content))
+	}
+	textContent, ok := result.Content[0].(*mcp.TextContent)
+	if !ok {
+		t.Fatalf("expected text content, got %T", result.Content[0])
+	}
+	for _, expected := range []string{"# Search results for owl", "## owl", "> Dictionary: Test Dictionary", "A **bird**."} {
+		if !strings.Contains(textContent.Text, expected) {
+			t.Fatalf("expected MCP markdown text to contain %q, got:\n%s", expected, textContent.Text)
+		}
+	}
+}