admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add send file preview tool

Browse Source
This commit is contained in:
zhaoyilun
2026-07-10 21:22:39 +08:00
parent 6781c75f84
commit 1fd10b5df7
9 changed files with 673 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
internal/mcpserver/server.go
View File

@@ -112,5 +112,6 @@ func NewServerWithSourcesAndMsgLibReceive(source tools.ReceiveMessagesSource, di
tools.RegisterISphereGroupToolsWithDisplayEntities(server, source, displaySource)
tools.RegisterISphereFileTools(server, source)
tools.RegisterISphereSendMessageTool(server, nil)
tools.RegisterISphereSendFileTool(server)
return server
}

4
internal/mcpserver/server_test.go
View File

@@ -25,7 +25,7 @@ func TestNewServerConstructsMCPServer(t *testing.T) {
}
}
func TestNewServerRegistersNineToolsWithoutCallingHelper(t *testing.T) {
func TestNewServerRegistersTenToolsWithoutCallingHelper(t *testing.T) {
ctx, cancel := context.WithCancel(context.Background())
serverTransport, clientTransport := mcp.NewInMemoryTransports()
server := NewServer()
@@ -60,7 +60,7 @@ func TestNewServerRegistersNineToolsWithoutCallingHelper(t *testing.T) {
gotNames = append(gotNames, tool.Name)
}
sort.Strings(gotNames)
wantNames := []string{"isphere_receive_files", "isphere_receive_messages", "isphere_search_contacts", "isphere_search_groups", "isphere_send_message", "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", "isphere_send_file", "isphere_send_message", "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)
}

257
internal/tools/isphere_send_file.go Normal file
View File

@@ -0,0 +1,257 @@
package tools
import (
"context"
"crypto/sha256"
"encoding/hex"
"fmt"
"io"
"os"
"path/filepath"
"strings"
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
const (
ToolNameSendFile = "isphere_send_file"
EnvSendFileAllowedDir = "ISPHERE_SEND_FILE_ALLOWED_DIR"
sendFileConnector = "implatform-file-transfer"
sendFileConnectorMode = "preview-only"
sendFilePreviewStage = "preview"
sendFileBlockedStage = "blocked"
sendFileProductionMode = "production"
)
type SendFileArgs struct {
TargetType string `json:"target_type" jsonschema:"target type; direct/contact or group/groupchat"`
TargetID string `json:"target_id" jsonschema:"contact or group id returned by iSphere search tools"`
FilePath string `json:"file_path" jsonschema:"local file path under ISPHERE_SEND_FILE_ALLOWED_DIR to hash and preview"`
FileSHA256 string `json:"file_sha256,omitempty" jsonschema:"optional lowercase SHA256 hex of file contents; checked when supplied"`
IdempotencyKey string `json:"idempotency_key" jsonschema:"required idempotency key; returned only as SHA256"`
ExecutionMode string `json:"execution_mode,omitempty" jsonschema:"preview/dry_run or production; production is blocked until file-send evidence passes"`
Preview bool `json:"preview,omitempty" jsonschema:"accepted for contract compatibility; current implementation is preview-only"`
}
type normalizedSendFileArgs struct {
TargetType string
TargetID string
TargetRef string
FileName string
FileSHA256 string
FileSizeBytes int64
IdempotencyKeySHA256 string
ExecutionMode string
}
func RegisterISphereSendFileTool(server *mcp.Server) {
mcp.AddTool[SendFileArgs, map[string]any](server, &mcp.Tool{
Name: ToolNameSendFile,
Description: "Preview iSphere file sends with target/file hash/idempotency metadata; production file upload is blocked until sandbox evidence passes.",
}, func(ctx context.Context, _ *mcp.CallToolRequest, input SendFileArgs) (*mcp.CallToolResult, map[string]any, error) {
_ = ctx
started := time.Now().UTC()
normalized, blockedReason, err := normalizeSendFileArgs(input)
if err != nil {
return nil, nil, err
}
if blockedReason != "" {
return nil, sendFileResponse(normalized, started, time.Now().UTC(), false, blockedReason), nil
}
if normalized.ExecutionMode == sendFileProductionMode {
return nil, sendFileResponse(normalized, started, time.Now().UTC(), false, "production file upload is blocked until send-file sandbox evidence passes"), nil
}
return nil, sendFileResponse(normalized, started, time.Now().UTC(), true, ""), nil
})
}
func normalizeSendFileArgs(input SendFileArgs) (normalizedSendFileArgs, string, error) {
targetType, targetRefPrefix, err := normalizeSendFileTargetType(input.TargetType)
if err != nil {
return normalizedSendFileArgs{}, "", err
}
targetID := strings.TrimSpace(input.TargetID)
if targetID == "" {
return normalizedSendFileArgs{}, "", fmt.Errorf("%s target_id is required", ToolNameSendFile)
}
idempotencyKey := strings.TrimSpace(input.IdempotencyKey)
if idempotencyKey == "" {
return normalizedSendFileArgs{}, "", fmt.Errorf("%s idempotency_key is required", ToolNameSendFile)
}
mode, err := normalizeSendFileExecutionMode(input.ExecutionMode)
if err != nil {
return normalizedSendFileArgs{}, "", err
}
normalized := normalizedSendFileArgs{
TargetType: targetType,
TargetID: targetID,
TargetRef: targetRefPrefix + ":" + targetID,
FileName: filepath.Base(strings.TrimSpace(input.FilePath)),
IdempotencyKeySHA256: sha256Hex(idempotencyKey),
ExecutionMode: mode,
}
fileSHA256, fileSize, blockedReason, err := inspectSendFilePath(input.FilePath, input.FileSHA256)
if err != nil {
return normalizedSendFileArgs{}, "", err
}
normalized.FileSHA256 = fileSHA256
normalized.FileSizeBytes = fileSize
return normalized, blockedReason, nil
}
func normalizeSendFileTargetType(value string) (string, string, error) {
switch strings.ToLower(strings.TrimSpace(value)) {
case "direct", "contact":
return "direct", "contact", nil
case "group", "groupchat":
return "group", "group", nil
default:
return "", "", fmt.Errorf("%s target_type %q is not available; use direct or group", ToolNameSendFile, value)
}
}
func normalizeSendFileExecutionMode(value string) (string, error) {
switch strings.ToLower(strings.TrimSpace(value)) {
case "", "preview", "dry_run", "dry-run":
return "preview", nil
case sendFileProductionMode:
return sendFileProductionMode, nil
default:
return "", fmt.Errorf("%s execution_mode %q is not available; use preview or production", ToolNameSendFile, value)
}
}
func inspectSendFilePath(filePath string, providedSHA256 string) (string, int64, string, error) {
trimmedPath := strings.TrimSpace(filePath)
if trimmedPath == "" {
return "", 0, "", fmt.Errorf("%s file_path is required", ToolNameSendFile)
}
allowedDir := strings.TrimSpace(os.Getenv(EnvSendFileAllowedDir))
if allowedDir == "" {
return "", 0, fmt.Sprintf("%s is required before previewing local file paths", EnvSendFileAllowedDir), nil
}
allowedAbs, err := filepath.Abs(allowedDir)
if err != nil {
return "", 0, "", fmt.Errorf("%s allowed dir: %w", ToolNameSendFile, err)
}
fileAbs, err := filepath.Abs(trimmedPath)
if err != nil {
return "", 0, "", fmt.Errorf("%s file_path: %w", ToolNameSendFile, err)
}
if !sendFilePathInsideDir(fileAbs, allowedAbs) {
return "", 0, fmt.Sprintf("file_path must stay inside %s", EnvSendFileAllowedDir), nil
}
info, err := os.Stat(fileAbs)
if err != nil {
if os.IsNotExist(err) {
return "", 0, "file_path does not exist under allowed directory", nil
}
return "", 0, "", fmt.Errorf("%s stat file_path: %w", ToolNameSendFile, err)
}
if info.IsDir() {
return "", 0, "file_path points to a directory; choose one file", nil
}
fileHash, err := sha256FileHex(fileAbs)
if err != nil {
return "", 0, "", fmt.Errorf("%s hash file_path: %w", ToolNameSendFile, err)
}
normalizedProvided := strings.ToLower(strings.TrimSpace(providedSHA256))
if normalizedProvided != "" {
if len(normalizedProvided) != 64 || !isLowerHex(normalizedProvided) {
return "", 0, "", fmt.Errorf("%s file_sha256 must be a lowercase SHA256 hex value", ToolNameSendFile)
}
if normalizedProvided != fileHash {
return "", 0, "", fmt.Errorf("%s file_sha256 does not match file contents", ToolNameSendFile)
}
}
return fileHash, info.Size(), "", nil
}
func sendFilePathInsideDir(fileAbs string, allowedAbs string) bool {
rel, err := filepath.Rel(filepath.Clean(allowedAbs), filepath.Clean(fileAbs))
if err != nil {
return false
}
if rel == "." {
return true
}
return rel != ".." && !strings.HasPrefix(rel, ".."+string(os.PathSeparator)) && !filepath.IsAbs(rel)
}
func sha256FileHex(path string) (string, error) {
file, err := os.Open(path)
if err != nil {
return "", err
}
defer file.Close()
hash := sha256.New()
if _, err := io.Copy(hash, file); err != nil {
return "", err
}
return hex.EncodeToString(hash.Sum(nil)), nil
}
func sendFileResponse(input normalizedSendFileArgs, started time.Time, finished time.Time, planned bool, blockedReason string) map[string]any {
sideEffects := sendMessageNoSideEffects()
status := "planned"
stage := sendFilePreviewStage
ok := true
blocked := any(nil)
if !planned {
status = "blocked"
stage = sendFileBlockedStage
ok = false
blocked = blockedReason
}
auditRef := "send-file:" + shortHash(input.FileSHA256) + ":" + shortHash(input.IdempotencyKeySHA256)
return map[string]any{
"ok": ok,
"send_status": status,
"blocked_reason": blocked,
"execution_mode": input.ExecutionMode,
"connector": sendFileConnector,
"connector_mode": sendFileConnectorMode,
"connector_stage": stage,
"production_send_enabled": false,
"real_send_attempted": false,
"target_ref": input.TargetRef,
"file_sha256": input.FileSHA256,
"file_size_bytes": input.FileSizeBytes,
"target": map[string]any{
"target_type": input.TargetType,
"target_id": input.TargetID,
"target_ref": input.TargetRef,
},
"file": map[string]any{
"file_name": input.FileName,
"file_sha256": input.FileSHA256,
"file_size_bytes": input.FileSizeBytes,
"allowed_dir_enforced": true,
"file_content_returned": false,
},
"idempotency": map[string]any{
"idempotency_key_sha256": input.IdempotencyKeySHA256,
},
"side_effect_flags": sideEffects,
"side_effects": sideEffects,
"audit": map[string]any{
"tool": ToolNameSendFile,
"source": sendFileConnector,
"execution_mode": input.ExecutionMode,
"connector": sendFileConnector,
"connector_mode": sendFileConnectorMode,
"connector_stage": stage,
"file_sha256": input.FileSHA256,
"file_size_bytes": input.FileSizeBytes,
"target_ref": input.TargetRef,
"audit_ref": auditRef,
"started_at": started.Format(time.RFC3339Nano),
"finished_at": finished.Format(time.RFC3339Nano),
"result": status,
"real_send_attempted": false,
},
}
}

187
internal/tools/isphere_send_file_test.go Normal file
View File

@@ -0,0 +1,187 @@
package tools
import (
"context"
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
func TestISphereSendFilePreviewComputesHashAndSize(t *testing.T) {
allowedDir := t.TempDir()
filePath := filepath.Join(allowedDir, "hello.txt")
if err := os.WriteFile(filePath, []byte("hello"), 0o600); err != nil {
t.Fatalf("write fixture file: %v", err)
}
t.Setenv(EnvSendFileAllowedDir, allowedDir)
session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
RegisterISphereSendFileTool(server)
})
defer cleanup()
callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
Name: ToolNameSendFile,
Arguments: map[string]any{
"target_type": "direct",
"target_id": "alice@imopenfire1-lanzhou",
"file_path": filePath,
"file_sha256": sha256HexForSendMessageTest("hello"),
"idempotency_key": "file-preview-idem-1",
"execution_mode": "preview",
"preview": true,
},
})
if err != nil {
t.Fatalf("call %s: %v", ToolNameSendFile, err)
}
if callResult.IsError {
t.Fatalf("preview should be structured success, got error: %+v", callResult)
}
var decoded struct {
OK bool `json:"ok"`
SendStatus string `json:"send_status"`
FileSHA256 string `json:"file_sha256"`
FileSizeBytes int64 `json:"file_size_bytes"`
TargetRef string `json:"target_ref"`
ProductionSendEnabled bool `json:"production_send_enabled"`
RealSendAttempted bool `json:"real_send_attempted"`
SideEffectFlags map[string]any `json:"side_effect_flags"`
}
payload, _ := json.Marshal(callResult.StructuredContent)
if err := json.Unmarshal(payload, &decoded); err != nil {
t.Fatalf("decode send-file preview payload %s: %v", payload, err)
}
if !decoded.OK || decoded.SendStatus != "planned" {
t.Fatalf("preview status mismatch: %s", payload)
}
if decoded.FileSHA256 != sha256HexForSendMessageTest("hello") || decoded.FileSizeBytes != 5 {
t.Fatalf("file metadata mismatch: %s", payload)
}
if decoded.TargetRef != "contact:alice@imopenfire1-lanzhou" {
t.Fatalf("target_ref = %q, want contact ref", decoded.TargetRef)
}
if decoded.ProductionSendEnabled || decoded.RealSendAttempted {
t.Fatalf("preview must not enable or attempt real send: %s", payload)
}
if decoded.SideEffectFlags["sent_file"] != false || decoded.SideEffectFlags["uploaded_file"] != false || decoded.SideEffectFlags["clicked_ui"] != false {
t.Fatalf("side-effect flags mismatch: %#v", decoded.SideEffectFlags)
}
}
func TestISphereSendFileRejectsPathOutsideAllowedDir(t *testing.T) {
allowedDir := t.TempDir()
outsideDir := t.TempDir()
filePath := filepath.Join(outsideDir, "outside.txt")
if err := os.WriteFile(filePath, []byte("outside"), 0o600); err != nil {
t.Fatalf("write outside fixture file: %v", err)
}
t.Setenv(EnvSendFileAllowedDir, allowedDir)
session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
RegisterISphereSendFileTool(server)
})
defer cleanup()
callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
Name: ToolNameSendFile,
Arguments: map[string]any{
"target_type": "group",
"target_id": "project-room@conference.imopenfire1-lanzhou",
"file_path": filePath,
"file_sha256": sha256HexForSendMessageTest("outside"),
"idempotency_key": "file-outside-idem-1",
"execution_mode": "preview",
"preview": true,
},
})
if err != nil {
t.Fatalf("call %s: %v", ToolNameSendFile, err)
}
if callResult.IsError {
t.Fatalf("outside path should be structured blocked metadata, got error: %+v", callResult)
}
var decoded struct {
OK bool `json:"ok"`
SendStatus string `json:"send_status"`
BlockedReason string `json:"blocked_reason"`
TargetRef string `json:"target_ref"`
SideEffectFlags map[string]any `json:"side_effect_flags"`
}
payload, _ := json.Marshal(callResult.StructuredContent)
if err := json.Unmarshal(payload, &decoded); err != nil {
t.Fatalf("decode outside-path payload %s: %v", payload, err)
}
if decoded.OK || decoded.SendStatus != "blocked" {
t.Fatalf("outside path should be blocked: %s", payload)
}
if !strings.Contains(decoded.BlockedReason, EnvSendFileAllowedDir) {
t.Fatalf("blocked reason should mention allowed-dir env: %q", decoded.BlockedReason)
}
if decoded.TargetRef != "group:project-room@conference.imopenfire1-lanzhou" {
t.Fatalf("target_ref = %q, want group ref", decoded.TargetRef)
}
if decoded.SideEffectFlags["sent_file"] != false || decoded.SideEffectFlags["uploaded_file"] != false || decoded.SideEffectFlags["typed_text"] != false {
t.Fatalf("blocked path should have no side effects: %#v", decoded.SideEffectFlags)
}
}
func TestISphereSendFileProductionBlockedWithoutSideEffects(t *testing.T) {
allowedDir := t.TempDir()
filePath := filepath.Join(allowedDir, "blocked.txt")
if err := os.WriteFile(filePath, []byte("blocked"), 0o600); err != nil {
t.Fatalf("write blocked fixture file: %v", err)
}
t.Setenv(EnvSendFileAllowedDir, allowedDir)
session, cleanup := connectToolsTestSession(t, func(server *mcp.Server) {
RegisterISphereSendFileTool(server)
})
defer cleanup()
callResult, err := session.CallTool(context.Background(), &mcp.CallToolParams{
Name: ToolNameSendFile,
Arguments: map[string]any{
"target_type": "direct",
"target_id": "alice@imopenfire1-lanzhou",
"file_path": filePath,
"file_sha256": sha256HexForSendMessageTest("blocked"),
"idempotency_key": "file-production-idem-1",
"execution_mode": "production",
},
})
if err != nil {
t.Fatalf("call %s production: %v", ToolNameSendFile, err)
}
if callResult.IsError {
t.Fatalf("production should be structured blocked metadata, got error: %+v", callResult)
}
var decoded struct {
OK bool `json:"ok"`
SendStatus string `json:"send_status"`
BlockedReason string `json:"blocked_reason"`
ProductionSendEnabled bool `json:"production_send_enabled"`
RealSendAttempted bool `json:"real_send_attempted"`
SideEffectFlags map[string]any `json:"side_effect_flags"`
}
payload, _ := json.Marshal(callResult.StructuredContent)
if err := json.Unmarshal(payload, &decoded); err != nil {
t.Fatalf("decode production-blocked payload %s: %v", payload, err)
}
if decoded.OK || decoded.SendStatus != "blocked" || decoded.BlockedReason == "" {
t.Fatalf("production should be blocked with reason: %s", payload)
}
if decoded.ProductionSendEnabled || decoded.RealSendAttempted {
t.Fatalf("production must not be enabled or attempted: %s", payload)
}
if decoded.SideEffectFlags["sent_file"] != false || decoded.SideEffectFlags["uploaded_file"] != false || decoded.SideEffectFlags["captured_network"] != false {
t.Fatalf("production blocked should have no side effects: %#v", decoded.SideEffectFlags)
}
}