feat: register isphere file receive list tool

internal/mcpserver/server.go

@@ -46,5 +46,6 @@ func NewServerWithReceiveSource(source tools.ReceiveMessagesSource) *mcp.Server
 	tools.RegisterISphereReadTools(server, source)
 	tools.RegisterISphereContactTools(server, source)
 	tools.RegisterISphereGroupTools(server, source)
+	tools.RegisterISphereFileTools(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", "isphere_search_groups", "win_helper_dump_uia", "win_helper_scan_windows", "win_helper_self_check", "win_helper_version"}
+	wantNames := []string{"isphere_receive_files", "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_files.go

@@ -0,0 +1,96 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+const ToolNameReceiveFiles = "isphere_receive_files"
+
+type ReceiveFilesArgs struct {
+	ConversationID string `json:"conversation_id,omitempty" jsonschema:"conversation id filter for file listing"`
+	MessageID      string `json:"message_id,omitempty" jsonschema:"message id filter for file listing"`
+	FileID         string `json:"file_id,omitempty" jsonschema:"file id filter for file listing"`
+	NameContains   string `json:"name_contains,omitempty" jsonschema:"case-insensitive filename substring filter"`
+	Mode           string `json:"mode,omitempty" jsonschema:"file receive mode; C14 supports list only"`
+	Limit          int    `json:"limit,omitempty" jsonschema:"maximum number of files to return; zero or negative returns all matches"`
+}
+
+func RegisterISphereFileTools(server *mcp.Server, source ReceiveMessagesSource) {
+	if source == nil {
+		source = isphere.EncryptedPacketLogSource{}
+	}
+
+	mcp.AddTool[ReceiveFilesArgs, map[string]any](server, &mcp.Tool{
+		Name:        ToolNameReceiveFiles,
+		Description: "List iSphere file metadata candidates from the configured read-only message source; download is deferred until cache mapping is validated.",
+	}, func(ctx context.Context, _ *mcp.CallToolRequest, input ReceiveFilesArgs) (*mcp.CallToolResult, map[string]any, error) {
+		started := time.Now().UTC()
+		mode := strings.ToLower(strings.TrimSpace(input.Mode))
+		if mode == "" {
+			mode = "list"
+		}
+		if mode != "list" {
+			return nil, nil, fmt.Errorf("isphere_receive_files mode %q is not available; only list is supported", input.Mode)
+		}
+		messages, err := source.ReceiveMessages(ctx, isphere.ReceiveMessagesQuery{Limit: 0})
+		if err != nil {
+			return nil, nil, err
+		}
+		files := isphere.ListFilesFromMessages(messages.Messages, isphere.ListFilesQuery{
+			ConversationID: input.ConversationID,
+			MessageID:      input.MessageID,
+			FileID:         input.FileID,
+			NameContains:   input.NameContains,
+			Limit:          input.Limit,
+		})
+		return nil, receiveFilesResultToMap(files, started, time.Now().UTC()), nil
+	})
+}
+
+func receiveFilesResultToMap(result isphere.ListFilesResult, started time.Time, finished time.Time) map[string]any {
+	files := make([]map[string]any, 0, len(result.Files))
+	for _, file := range result.Files {
+		files = append(files, map[string]any{
+			"file_id":         file.FileID,
+			"message_id":      nullableString(file.MessageID),
+			"conversation_id": nullableString(file.ConversationID),
+			"file_name":       file.FileName,
+			"size_bytes":      file.SizeBytes,
+			"mime_type":       file.MimeType,
+			"created_at":      nullableString(file.CreatedAt),
+			"download_ref":    nullableString(file.DownloadRef),
+			"saved_path":      nullableString(file.SavedPath),
+			"sha256":          nullableString(file.SHA256),
+			"source":          file.Source,
+			"raw_ref":         file.RawRef,
+		})
+	}
+	return map[string]any{
+		"ok":          true,
+		"mode":        "list",
+		"files":       files,
+		"next_cursor": nil,
+		"audit": map[string]any{
+			"tool":           ToolNameReceiveFiles,
+			"source":         "local_readonly",
+			"execution_mode": "read",
+			"started_at":     started.Format(time.RFC3339Nano),
+			"finished_at":    finished.Format(time.RFC3339Nano),
+			"result":         "ok",
+		},
+	}
+}
+
+func nullableString(value string) any {
+	if strings.TrimSpace(value) == "" {
+		return nil
+	}
+	return value
+}

internal/tools/isphere_files_test.go

@@ -0,0 +1,90 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"isphere-ai-bridge/internal/isphere"
+)
+
+func TestISphereReceiveFilesToolReturnsLogBackedFiles(t *testing.T) {
+	fake := &fakeReceiveMessagesSource{
+		result: isphere.ReceiveMessagesResult{Messages: []isphere.Message{{
+			ID:             "msg-file-1",
+			ConversationID: "alice@imopenfire1-lanzhou|bob@imopenfire1-lanzhou",
+			Text:           "redacted-report.docx",
+			Timestamp:      "1783423807000",
+			Subject:        "FILE_TRANSFER_CANCEL",
+		}}},
+	}
+	session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
+		RegisterISphereFileTools(server, fake)
+	})
+	defer cleanup()
+
+	callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+		Name:      ToolNameReceiveFiles,
+		Arguments: map[string]any{"mode": "list", "name_contains": "report", "limit": 5},
+	})
+	if err != nil {
+		t.Fatalf("call %s: %v", ToolNameReceiveFiles, err)
+	}
+	if callResult.IsError {
+		t.Fatalf("call result is error: %+v", callResult)
+	}
+
+	var decoded struct {
+		OK    bool   `json:"ok"`
+		Mode  string `json:"mode"`
+		Files []struct {
+			FileID         string  `json:"file_id"`
+			MessageID      string  `json:"message_id"`
+			ConversationID string  `json:"conversation_id"`
+			FileName       string  `json:"file_name"`
+			SizeBytes      *int64  `json:"size_bytes"`
+			MimeType       string  `json:"mime_type"`
+			CreatedAt      string  `json:"created_at"`
+			DownloadRef    *string `json:"download_ref"`
+			SavedPath      *string `json:"saved_path"`
+			SHA256         *string `json:"sha256"`
+			Source         string  `json:"source"`
+		} `json:"files"`
+		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 || decoded.Mode != "list" {
+		t.Fatalf("ok/mode = %v/%q in %s", decoded.OK, decoded.Mode, payload)
+	}
+	if len(decoded.Files) != 1 {
+		t.Fatalf("files = %+v, want one", decoded.Files)
+	}
+	file := decoded.Files[0]
+	if file.FileID != "msg-file-1:redacted-report.docx" || file.MessageID != "msg-file-1" || file.ConversationID != "alice@imopenfire1-lanzhou|bob@imopenfire1-lanzhou" {
+		t.Fatalf("unexpected file identity: %+v", file)
+	}
+	if file.FileName != "redacted-report.docx" || file.MimeType != "application/vnd.openxmlformats-officedocument.wordprocessingml.document" || file.CreatedAt != "1783423807000" {
+		t.Fatalf("unexpected file metadata: %+v", file)
+	}
+	if file.SizeBytes != nil || file.DownloadRef != nil || file.SavedPath != nil || file.SHA256 != nil {
+		t.Fatalf("download/cache fields should be unknown: %+v", file)
+	}
+	if file.Source != "local_readonly" {
+		t.Fatalf("source = %q", file.Source)
+	}
+	if decoded.Audit["tool"] != ToolNameReceiveFiles || decoded.Audit["result"] != "ok" || decoded.Audit["execution_mode"] != "read" {
+		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)
+	}
+}