feat: register isphere group search tool

internal/mcpserver/server.go

@@ -45,5 +45,6 @@ func NewServerWithReceiveSource(source tools.ReceiveMessagesSource) *mcp.Server
 	tools.RegisterWinHelperTools(server, helperclient.Client{})
 	tools.RegisterISphereReadTools(server, source)
 	tools.RegisterISphereContactTools(server, source)
+	tools.RegisterISphereGroupTools(server, source)
 	return server
 }

internal/mcpserver/server_test.go

@@ -57,7 +57,7 @@ func TestNewServerRegistersN8WinHelperToolsWithoutCallingHelper(t *testing.T) {
 		gotNames = append(gotNames, tool.Name)
 	}
 	sort.Strings(gotNames)
-	wantNames := []string{"isphere_receive_messages", "isphere_search_contacts", "win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"}
+	wantNames := []string{"isphere_receive_messages", "isphere_search_contacts", "isphere_search_groups", "win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"}
 	if !reflect.DeepEqual(gotNames, wantNames) {
 		t.Fatalf("server tool names = %#v, want %#v", gotNames, wantNames)
 	}

internal/tools/isphere_groups.go

@@ -0,0 +1,64 @@
+package tools
+
+import (
+	"context"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+const ToolNameSearchGroups = "isphere_search_groups"
+
+type SearchGroupsArgs struct {
+	Query string `json:"query" jsonschema:"group search query; currently matches bare group JIDs from local readonly message logs"`
+	Limit int    `json:"limit,omitempty" jsonschema:"maximum number of groups to return; zero or negative returns all matches"`
+}
+
+func RegisterISphereGroupTools(server *mcp.Server, source ReceiveMessagesSource) {
+	if source == nil {
+		source = isphere.EncryptedPacketLogSource{}
+	}
+
+	mcp.AddTool[SearchGroupsArgs, map[string]any](server, &mcp.Tool{
+		Name:        ToolNameSearchGroups,
+		Description: "Search iSphere group candidates from the configured read-only message source.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, input SearchGroupsArgs) (*mcp.CallToolResult, map[string]any, error) {
+		started := time.Now().UTC()
+		messages, err := source.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: 0})
+		if err != nil {
+			return nil, nil, err
+		}
+		groups := isphere.SearchGroupsFromMessages(messages.Messages, isphere.SearchGroupsQuery{Query: input.Query, Limit: input.Limit})
+		return nil, searchGroupsResultToMap(groups, started, time.Now().UTC()), nil
+	})
+}
+
+func searchGroupsResultToMap(result isphere.SearchGroupsResult, started time.Time, finished time.Time) map[string]any {
+	groups := make([]map[string]any, 0, len(result.Groups))
+	for _, group := range result.Groups {
+		groups = append(groups, map[string]any{
+			"group_id":     group.GroupID,
+			"display_name": group.DisplayName,
+			"member_count": nil,
+			"owner_ref":    nil,
+			"source":       group.Source,
+			"confidence":   group.Confidence,
+			"raw_ref":      group.RawRef,
+		})
+	}
+	return map[string]any{
+		"ok":          true,
+		"groups":      groups,
+		"next_cursor": nil,
+		"audit": map[string]any{
+			"tool":           ToolNameSearchGroups,
+			"source":         "local_readonly",
+			"execution_mode": "read",
+			"started_at":     started.Format(time.RFC3339Nano),
+			"finished_at":    finished.Format(time.RFC3339Nano),
+			"result":         "ok",
+		},
+	}
+}

internal/tools/isphere_groups_test.go

@@ -0,0 +1,81 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+func TestISphereSearchGroupsToolReturnsJIDGroups(t *testing.T) {
+	fake := &fakeReceiveMessagesSource{
+		result: isphere.ReceiveMessagesResult{Messages: []isphere.Message{{
+			ID:               "msg-group-1",
+			ConversationType: "groupchat",
+			SenderID:         "project-room@conference.imopenfire1-lanzhou",
+			ReceiverID:       "user@imopenfire1-lanzhou",
+		}}},
+	}
+	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
+		RegisterISphereGroupTools(server, fake)
+	})
+	defer cleanup()
+
+	callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      ToolNameSearchGroups,
+		Arguments: map[string]any{"query": "project", "limit": 10},
+	})
+	if err != nil {
+		t.Fatalf("call %s: %v", ToolNameSearchGroups, err)
+	}
+	if callResult.IsError {
+		t.Fatalf("call result is error: %+v", callResult)
+	}
+
+	var decoded struct {
+		OK     bool `json:"ok"`
+		Groups []struct {
+			GroupID     string  `json:"group_id"`
+			DisplayName string  `json:"display_name"`
+			MemberCount *int    `json:"member_count"`
+			OwnerRef    *string `json:"owner_ref"`
+			Source      string  `json:"source"`
+			Confidence  float64 `json:"confidence"`
+			RawRef      string  `json:"raw_ref"`
+		} `json:"groups"`
+		NextCursor any            `json:"next_cursor"`
+		Audit      map[string]any `json:"audit"`
+	}
+	payload, err := json.Marshal(callResult.StructuredContent)
+	if err != nil {
+		t.Fatalf("marshal structured content: %v", err)
+	}
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("decode structured content %s: %v", payload, err)
+	}
+	if !decoded.OK {
+		t.Fatalf("ok = false in %s", payload)
+	}
+	if len(decoded.Groups) != 1 {
+		t.Fatalf("groups = %+v, want one", decoded.Groups)
+	}
+	group := decoded.Groups[0]
+	if group.GroupID != "project-room@conference.imopenfire1-lanzhou" || group.DisplayName != "project-room@conference.imopenfire1-lanzhou" {
+		t.Fatalf("unexpected group identity: %+v", group)
+	}
+	if group.MemberCount != nil || group.OwnerRef != nil {
+		t.Fatalf("member/owner should be unknown: %+v", group)
+	}
+	if group.Source != "local_readonly" || group.Confidence != 0.6 || group.RawRef != "groupchat_jid" {
+		t.Fatalf("unexpected group metadata: %+v", group)
+	}
+	if decoded.Audit["tool"] != ToolNameSearchGroups || decoded.Audit["result"] != "ok" {
+		t.Fatalf("audit = %+v", decoded.Audit)
+	}
+	if len(fake.queries) != 1 || fake.queries[0].Limit != 0 {
+		t.Fatalf("source queries = %+v, want one unbounded receive query", fake.queries)
+	}
+}