feat: register isphere receive messages tool

internal/mcpserver/server.go

@@ -4,6 +4,7 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 
 	"isphere-ai-bridge/internal/helperclient"
+	"isphere-ai-bridge/internal/isphere"
 	"isphere-ai-bridge/internal/tools"
 )
 
@@ -20,5 +21,6 @@ func NewServer() *mcp.Server {
 		Version: ServerVersion,
 	}, nil)
 	tools.RegisterWinHelperTools(server, helperclient.Client{})
+	tools.RegisterISphereReadTools(server, isphere.EncryptedPacketLogSource{})
 	return server
 }

internal/mcpserver/server_test.go

@@ -52,7 +52,7 @@ func TestNewServerRegistersN8WinHelperToolsWithoutCallingHelper(t *testing.T) {
 		gotNames = append(gotNames, tool.Name)
 	}
 	sort.Strings(gotNames)
-	wantNames := []string{"win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"}
+	wantNames := []string{"isphere_receive_messages", "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_read.go

@@ -0,0 +1,55 @@
+package tools
+
+import (
+	"context"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+const ToolNameReceiveMessages = "isphere_receive_messages"
+
+type ReceiveMessagesSource interface {
+	ReceiveMessages(ctx context.Context, query isphere.ReceiveMessagesQuery) (isphere.ReceiveMessagesResult, error)
+}
+
+type ReceiveMessagesArgs struct {
+	Limit int `json:"limit,omitempty" jsonschema:"maximum number of messages to return; zero or negative returns all available messages"`
+}
+
+func RegisterISphereReadTools(server *mcp.Server, source ReceiveMessagesSource) {
+	if source == nil {
+		source = isphere.EncryptedPacketLogSource{}
+	}
+
+	mcp.AddTool[ReceiveMessagesArgs, map[string]any](server, &mcp.Tool{
+		Name:        ToolNameReceiveMessages,
+		Description: "Return iSphere messages from the configured read-only log-backed source.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, input ReceiveMessagesArgs) (*mcp.CallToolResult, map[string]any, error) {
+		result, err := source.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: input.Limit})
+		if err != nil {
+			return nil, nil, err
+		}
+		return nil, receiveMessagesResultToMap(result), nil
+	})
+}
+
+func receiveMessagesResultToMap(result isphere.ReceiveMessagesResult) map[string]any {
+	messages := make([]map[string]any, 0, len(result.Messages))
+	for _, message := range result.Messages {
+		messages = append(messages, map[string]any{
+			"id":                message.ID,
+			"conversation_id":   message.ConversationID,
+			"conversation_type": message.ConversationType,
+			"sender_id":         message.SenderID,
+			"receiver_id":       message.ReceiverID,
+			"text":              message.Text,
+			"timestamp":         message.Timestamp,
+			"subject":           message.Subject,
+			"receipt_id":        message.ReceiptID,
+			"read":              message.Read,
+		})
+	}
+	return map[string]any{"messages": messages}
+}

internal/tools/isphere_read_test.go

@@ -0,0 +1,104 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+func TestISphereReceiveMessagesToolReturnsSourceMessages(t *testing.T) {
+	fake := &fakeReceiveMessagesSource{
+		result: isphere.ReceiveMessagesResult{Messages: []isphere.Message{{
+			ID:               "msg-1",
+			ConversationID:   "sender@imopenfire1-lanzhou|receiver@imopenfire1-lanzhou",
+			ConversationType: "chat",
+			SenderID:         "sender@imopenfire1-lanzhou",
+			ReceiverID:       "receiver@imopenfire1-lanzhou",
+			Text:             "redacted",
+			Timestamp:        "1783423807000",
+			Subject:          "FILE_TRANSFER_CANCEL",
+			ReceiptID:        "receipt-1",
+			Read:             true,
+		}}},
+	}
+	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
+		RegisterISphereReadTools(server, fake)
+	})
+	defer cleanup()
+
+	listResult, err := session.ListTools(context.Background(), &mcp.ListToolsParams{})
+	if err != nil {
+		t.Fatalf("list tools: %v", err)
+	}
+	gotNames := make([]string, 0, len(listResult.Tools))
+	for _, tool := range listResult.Tools {
+		gotNames = append(gotNames, tool.Name)
+	}
+	assertSameStrings(t, gotNames, []string{ToolNameReceiveMessages})
+
+	callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      ToolNameReceiveMessages,
+		Arguments: map[string]any{"limit": 5},
+	})
+	if err != nil {
+		t.Fatalf("call %s: %v", ToolNameReceiveMessages, err)
+	}
+	if callResult.IsError {
+		t.Fatalf("call result is error: %+v", callResult)
+	}
+	if len(fake.queries) != 1 || fake.queries[0].Limit != 5 {
+		t.Fatalf("queries = %+v, want one limit=5", fake.queries)
+	}
+
+	var decoded struct {
+		Messages []struct {
+			ID               string `json:"id"`
+			ConversationID   string `json:"conversation_id"`
+			ConversationType string `json:"conversation_type"`
+			SenderID         string `json:"sender_id"`
+			ReceiverID       string `json:"receiver_id"`
+			Text             string `json:"text"`
+			Timestamp        string `json:"timestamp"`
+			Subject          string `json:"subject"`
+			ReceiptID        string `json:"receipt_id"`
+			Read             bool   `json:"read"`
+		} `json:"messages"`
+	}
+	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 len(decoded.Messages) != 1 {
+		t.Fatalf("messages = %+v, want one", decoded.Messages)
+	}
+	msg := decoded.Messages[0]
+	if msg.ID != "msg-1" || msg.Text != "redacted" || msg.Subject != "FILE_TRANSFER_CANCEL" {
+		t.Fatalf("unexpected message content: %+v", msg)
+	}
+	if msg.ConversationID != "sender@imopenfire1-lanzhou|receiver@imopenfire1-lanzhou" {
+		t.Fatalf("conversation_id = %q", msg.ConversationID)
+	}
+	if msg.SenderID != "sender@imopenfire1-lanzhou" || msg.ReceiverID != "receiver@imopenfire1-lanzhou" {
+		t.Fatalf("sender/receiver = %q/%q", msg.SenderID, msg.ReceiverID)
+	}
+	if msg.Timestamp != "1783423807000" || msg.ReceiptID != "receipt-1" || !msg.Read {
+		t.Fatalf("metadata = %+v", msg)
+	}
+}
+
+type fakeReceiveMessagesSource struct {
+	queries []isphere.ReceiveMessagesQuery
+	result  isphere.ReceiveMessagesResult
+}
+
+func (f *fakeReceiveMessagesSource) ReceiveMessages(_ context.Context, query isphere.ReceiveMessagesQuery) (isphere.ReceiveMessagesResult, error) {
+	f.queries = append(f.queries, query)
+	return f.result, nil
+}

internal/tools/winhelper_test.go

@@ -21,7 +21,7 @@ var expectedWinHelperToolNames = []string{
 	"win_helper_dump_uia",
 }
 
-func TestWinHelperToolsRegisterExactlyFourReadOnlyTools(t *testing.T) {
+func TestWinHelperToolsRegisterOnlyHelperTools(t *testing.T) {
 	fake := &fakeHelperCaller{}
 	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
 		RegisterWinHelperTools(server, fake)
@@ -37,7 +37,7 @@ func TestWinHelperToolsRegisterExactlyFourReadOnlyTools(t *testing.T) {
 	for _, tool := range result.Tools {
 		gotNames = append(gotNames, tool.Name)
 		lower := strings.ToLower(tool.Name)
-		forbidden := []string{"send", "search", "file", "login", "conversation", "upload", "download", "receive"}
+		forbidden := []string{"send", "search", "file", "login", "conversation", "upload", "download"}
 		for _, word := range forbidden {
 			if strings.Contains(lower, word) {
 				t.Fatalf("tool %q contains forbidden action word %q", tool.Name, word)