Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

22.4 KB
Raw Blame
package httpapi

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"slices"
	"strings"
	"time"

	"agentflow/internal/domain"
	"agentflow/internal/engine"
	"agentflow/internal/mcpserver"

	"github.com/gin-gonic/gin"
)

type agentToolGateway struct {
	*deps
}

type agentToolTokenKey struct{}

func withAgentToolToken(ctx context.Context, token string) context.Context {
	return context.WithValue(ctx, agentToolTokenKey{}, token)
}

// Resolve the capability again under the mode fence. A request may have
// obtained its session pointer immediately before a mode rotation revoked it.
func validAgentToolToken(ctx context.Context, session *AgentToolSession) bool {
	token, _ := ctx.Value(agentToolTokenKey{}).(string)
	return (token == "" || token == session.Token) && !session.closed.Load() && !session.expired(time.Now())
}

type agentToolRPCRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      any             `json:"id,omitempty"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

type agentToolRPCResponse struct {
	JSONRPC string             `json:"jsonrpc"`
	ID      any                `json:"id"`
	Result  any                `json:"result,omitempty"`
	Error   *agentToolRPCError `json:"error,omitempty"`
}

type agentToolRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

func (s *Server) handleAgentToolMCP(c *gin.Context) {
	(&agentToolGateway{deps: s.deps}).ServeHTTP(c)
}

func (h *agentToolGateway) ServeHTTP(c *gin.Context) {
	token := strings.TrimSpace(c.Param("token"))
	session, ok := agentToolSessions.get(token)
	if !ok {
		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid agent tool session"})
		return
	}
	if c.Request.Method == http.MethodDelete {
		agentToolSessions.delete(token)
		c.Status(http.StatusNoContent)
		return
	}
	if c.Request.Method != http.MethodPost {
		c.Header("Allow", "POST, DELETE")
		c.JSON(http.StatusMethodNotAllowed, gin.H{"error": "stateless Streamable HTTP accepts JSON-RPC POST requests"})
		return
	}
	var request agentToolRPCRequest
	decoder := json.NewDecoder(io.LimitReader(c.Request.Body, 4<<20))
	decoder.UseNumber()
	if err := decoder.Decode(&request); err != nil {
		c.JSON(http.StatusBadRequest, agentToolRPCResponse{JSONRPC: "2.0", Error: &agentToolRPCError{Code: -32700, Message: "parse error", Data: err.Error()}})
		return
	}
	response := h.handleRPC(withAgentToolToken(c.Request.Context(), token), session, request)
	if response == nil {
		c.Status(http.StatusAccepted)
		return
	}
	c.JSON(http.StatusOK, response)
}

func (h *agentToolGateway) handleRPC(ctx context.Context, session *AgentToolSession, request agentToolRPCRequest) *agentToolRPCResponse {
	if request.Method != "tools/call" {
		session.toolsMu.RLock()
		defer session.toolsMu.RUnlock()
	}
	if request.Method != "tools/call" && !validAgentToolToken(ctx, session) {
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Error: &agentToolRPCError{Code: -32602, Message: errAgentToolInvalidSession.Error()}}
	}
	if request.Method == "notifications/cancelled" {
		// Streamable HTTP does not treat a dropped stream as cancellation;
		// the CLI gives up on a call (e.g. its own tool timeout) with this
		// notification. A call waiting for approval then ends and its card
		// expires, so a late approval cannot write anymore.
		session.cancelToolCall(cancelledRequestID(request.Params))
		return nil
	}
	if strings.HasPrefix(request.Method, "notifications/") {
		return nil
	}
	switch request.Method {
	case "initialize":
		session.diagnostics().platform("mcp.gateway_initialized", "CLI 已连接平台会话 MCP 网关", session.User)
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: map[string]any{
			"protocolVersion": agentToolProtocolVersion(request.Params),
			"capabilities":    map[string]any{"tools": map[string]any{"listChanged": false}},
			"serverInfo":      map[string]string{"name": agentToolSessionMCPName, "version": "1.0.0"},
			"instructions":    agentToolSessionInstructions(session),
		}}
	case "ping":
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: map[string]any{}}
	case "tools/list":
		started := time.Now()
		tools := h.toolList(ctx, session)
		session.diagnostics().platform("mcp.tools_listed", fmt.Sprintf("平台网关返回 %d 个工具(耗时 %dms)", len(tools), time.Since(started).Milliseconds()), session.User)
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: map[string]any{"tools": tools}}
	case "agentflow/nativeApproval":
		result := h.approveNativeTool(ctx, session, request.Params)
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: result}
	case agentGitCredentialMethod:
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: h.gitCredential(ctx, session, request.Params)}
	case "tools/call":
		ctx, done := session.trackToolCall(ctx, request.ID)
		defer done()
		result, err := h.callTool(ctx, session, request.Params)
		if err != nil {
			return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Error: &agentToolRPCError{Code: -32602, Message: err.Error()}}
		}
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Result: result}
	default:
		return &agentToolRPCResponse{JSONRPC: "2.0", ID: request.ID, Error: &agentToolRPCError{Code: -32601, Message: "method not found", Data: request.Method}}
	}
}

func agentToolProtocolVersion(params json.RawMessage) string {
	var payload struct {
		ProtocolVersion string `json:"protocolVersion"`
	}
	_ = json.Unmarshal(params, &payload)
	switch payload.ProtocolVersion {
	case "2024-11-05", "2025-03-26", "2025-06-18":
		return payload.ProtocolVersion
	default:
		return "2025-06-18"
	}
}

func agentToolInstructions(mode AgentToolMode) string {
	switch mode {
	case AgentToolReport:
		return "只能基于提供的资料汇总本次 SOP,完成后调用 submit_notification_report。普通文本不算提交。"
	case AgentToolClarify:
		return "只读查询 LoopForge 及当前项目已安装的外部 MCP。本轮结束时调用 submit_clarification。"
	case AgentToolAssistant:
		return "查询平台和当前项目已安装的外部 MCP。平台写入可通过 submit_assistant_reply 提交草稿。外部 MCP 写入直接调用,由网关按本轮审批模式处理。普通问答和只读查询直接用自然语言回复,无需调用提交工具。"
	case AgentToolScheduled:
		return "使用当前项目和个人已安装的 MCP 以及 agentflow__* 直接读写,写入立即生效。完成后用自然语言汇报。"
	default:
		return "LoopForge session MCP"
	}
}

func (h *agentToolGateway) toolList(ctx context.Context, session *AgentToolSession) []map[string]any {
	catalog := h.buildCatalog(ctx, session)
	out := make([]map[string]any, 0, len(catalog))
	for _, tool := range catalog {
		item := map[string]any{
			"name":        tool.Name,
			"description": tool.Description,
			"inputSchema": json.RawMessage(defaultToolSchema(tool.InputSchema)),
		}
		if len(tool.OutputSchema) > 0 && string(tool.OutputSchema) != "null" {
			item["outputSchema"] = json.RawMessage(tool.OutputSchema)
		}
		if len(tool.Annotations) > 0 && string(tool.Annotations) != "null" {
			item["annotations"] = json.RawMessage(tool.Annotations)
		}
		out = append(out, item)
	}
	return out
}

func (h *agentToolGateway) callTool(ctx context.Context, session *AgentToolSession, raw json.RawMessage) (res map[string]any, retErr error) {
	session.toolsMu.RLock()
	defer session.toolsMu.RUnlock()
	if session.finished() {
		return nil, errAgentToolTerminalCommitted
	}
	if !validAgentToolToken(ctx, session) {
		return nil, errAgentToolInvalidSession
	}
	if session.ctx != nil {
		// Tool calls arrive on independent HTTP requests. Stopping the model
		// turn must also stop any in-flight work using its gateway.
		callCtx, cancel := context.WithCancel(ctx)
		stop := context.AfterFunc(session.ctx, cancel)
		defer stop()
		defer cancel()
		ctx = callCtx
	}
	var params struct {
		Name      string          `json:"name"`
		Arguments json.RawMessage `json:"arguments"`
	}
	if err := json.Unmarshal(raw, &params); err != nil {
		return nil, err
	}
	name := stripAgentToolServerPrefix(params.Name)
	diag := session.diagnostics()
	attemptID := diag.currentAttemptID()
	diagToolID := diag.toolStart("gateway", "", name, "", attemptID, session.User)
	defer func() {
		if diagToolID == "" {
			return
		}
		failed := retErr != nil || (res != nil && res["isError"] == true)
		errMsg := ""
		if retErr != nil {
			errMsg = retErr.Error()
		} else if failed {
			if data, err := json.Marshal(res["content"]); err == nil {
				errMsg = diagnosticErrorText(data)
			}
		}
		diag.toolEnd("gateway", diagToolID, attemptID, errMsg, failed, nil, session.User)
	}()
	if session.requestedMode() != "" {
		return mcpToolTextResult(assistantHandoffNotice, true), nil
	}
	if session.RuntimeMode == domain.AssistantModeWorkspace {
		if _, ok := lookupAgentTool(h.buildCatalog(ctx, session), name); !ok {
			return nil, fmt.Errorf("%w: %s", errAgentToolForbidden, name)
		}
	}
	// Some CLI/provider combinations encode function arguments as a JSON
	// string before forwarding them to MCP. Accept one encoded object, while
	// retaining the same token, mode, catalog and write checks.
	if rawArgs := bytes.TrimSpace(params.Arguments); len(rawArgs) > 0 && rawArgs[0] == '"' {
		var encoded string
		if err := json.Unmarshal(rawArgs, &encoded); err != nil {
			return nil, err
		}
		object := bytes.TrimSpace([]byte(encoded))
		if len(object) == 0 || object[0] != '{' || !json.Valid(object) {
			return nil, fmt.Errorf("tool arguments must be a JSON object")
		}
		params.Arguments = object
	}
	logAgentToolEvent("call-start", "mode="+string(session.Mode), "tool="+name)
	if name == submitClarificationTool || name == submitAssistantReplyTool || name == submitNotificationReportTool {
		return h.callTerminal(session, name, params.Arguments)
	}
	if session.terminalToolsOnly() {
		return nil, errAgentToolForbidden
	}
	if name == "workbench_tool_schema" && session.Mode == AgentToolAssistant {
		var input struct {
			Name string `json:"name"`
		}
		if err := json.Unmarshal(params.Arguments, &input); err != nil {
			return nil, err
		}
		op, ok := assistantPublicOperations[strings.TrimPrefix(input.Name, "agentflow__")]
		if !ok {
			return nil, errAgentToolUnknown
		}
		body, _ := json.Marshal(map[string]any{"name": op.Name, "description": op.Description, "inputSchema": mcpserver.ToolInputSchema(op)})
		return map[string]any{"content": []map[string]any{{"type": "text", "text": string(body)}}}, nil
	}
	if name == "workbench_publish_artifact" {
		return h.publishArtifact(ctx, session, params.Arguments)
	}
	catalog := h.buildCatalog(ctx, session)
	tool, ok := lookupAgentTool(catalog, name)
	if !ok {
		kind, upstream, parsed := parseNamespacedAgentTool(name)
		if !parsed || !agentToolNameAllowed(session.Mode, kind, upstream) {
			return nil, fmt.Errorf("%w: %s", errAgentToolUnknown, name)
		}
		tool = agentToolDescriptor{Name: name, Kind: kind, UpstreamName: upstream, ServerID: h.serverIDForKind(session, kind)}
	}
	args := map[string]any{}
	if len(params.Arguments) > 0 && string(params.Arguments) != "null" {
		dec := json.NewDecoder(bytes.NewReader(params.Arguments))
		dec.UseNumber()
		if err := dec.Decode(&args); err != nil {
			return nil, err
		}
	}
	if tool.Kind == "browser" {
		result, err := h.callMainBotBrowser(ctx, session, tool.Name, args)
		logAgentToolEvent("call", "mode="+string(session.Mode), "tool="+tool.Name, fmt.Sprintf("ok=%t", err == nil && result["isError"] != true))
		return result, err
	}
	text, err := h.dispatch(ctx, session, tool, args)
	if err != nil {
		logAgentToolEvent("call-error", "mode="+string(session.Mode), "tool="+tool.Name, "err="+truncateRunes(err.Error(), 160))
		return mcpToolTextResult(err.Error(), true), nil
	}
	logAgentToolEvent("call", "mode="+string(session.Mode), "tool="+tool.Name, "ok=1")
	return mcpToolTextResult(text, false), nil
}

func (h *agentToolGateway) callTerminal(session *AgentToolSession, name string, raw json.RawMessage) (map[string]any, error) {
	switch {
	case name == submitNotificationReportTool && session.Mode == AgentToolReport:
		report, err := parseSubmitNotificationReportArgs(raw)
		if err != nil {
			return mcpToolTextResult(err.Error(), true), nil
		}
		if err := session.commitFinal(AgentTerminalResult{Kind: AgentTerminalReport, Report: &report}); err != nil {
			return nil, err
		}
		return mcpToolTextResult("报告提交成功,本轮结束。", false), nil
	case name == submitClarificationTool && session.Mode == AgentToolClarify:
		result, err := parseSubmitClarificationArgs(raw)
		if err != nil {
			logAgentToolEvent("terminal-invalid", "mode="+string(session.Mode), "tool="+name, "err="+truncateRunes(err.Error(), 160))
			return mcpToolTextResult(err.Error(), true), nil
		}
		if err := session.commitFinal(AgentTerminalResult{Kind: AgentTerminalClarification, Clarification: &result}); err != nil {
			return nil, err
		}
		return mcpToolTextResult("提交成功,本轮结束。", false), nil
	case name == submitAssistantReplyTool && session.Mode == AgentToolAssistant:
		reply, err := parseSubmitAssistantReplyArgs(raw, session.ProjectID)
		if err != nil {
			logAgentToolEvent("terminal-invalid", "mode="+string(session.Mode), "tool="+name, "err="+truncateRunes(err.Error(), 160))
			return mcpToolTextResult("草稿参数校验失败,本轮继续;请按以下错误修正后重新提交,不代表工具不可用:"+err.Error(), true), nil
		}
		if h.deps != nil && h.repo != nil {
			if err := h.assistant().vetProposalDrafts(session, &reply); err != nil {
				logAgentToolEvent("terminal-invalid", "mode="+string(session.Mode), "tool="+name, "err="+truncateRunes(err.Error(), 160))
				return mcpToolTextResult("派发建议未提交,本轮继续:"+err.Error(), true), nil
			}
		}
		if len(reply.Drafts) == 0 {
			// This tool ends the model process. Accepting a progress message here
			// used to kill sibling read calls before a requested SOP was prepared.
			return mcpToolTextResult("未提交草稿,本轮继续。submit_assistant_reply 仅用于提交待确认写入草稿;进度说明请用普通文本并继续执行工具查询。请完成用户请求或说明具体阻塞原因后,以自然语言结束;不要提交占位回复。", true), nil
		}
		if err := session.commitFinal(AgentTerminalResult{Kind: AgentTerminalAssistant, Assistant: &reply}); err != nil {
			return nil, err
		}
		return mcpToolTextResult("提交成功,本轮结束。", false), nil
	default:
		return nil, errAgentToolForbidden
	}
}

func (h *agentToolGateway) dispatch(ctx context.Context, session *AgentToolSession, tool agentToolDescriptor, args map[string]any) (string, error) {
	if session.Mode == AgentToolAssistant && session.ExecMode.ReviewWrites {
		ctx = withAssistantApprovalReviewer(ctx, session.approvalReviewer)
	}
	if tool.Kind == "workspace" {
		return h.callMainBotWorkspace(ctx, session, tool.Name, args)
	}
	if tool.Kind == "agentflow" {
		if session.Mode == AgentToolClarify && !agentToolNameAllowed(AgentToolClarify, "agentflow", tool.UpstreamName) {
			return "", errAgentToolForbidden
		}
		if session.Mode == AgentToolAssistant {
			// 审批模式决定写工具放行范围;目录里能看到的才允许调用。
			// 拦截时给出引导性错误,让模型改走 drafts(CLI resume 的会话
			// 可能还带着旧模式的系统提示词,不能指望它自己记得)。
			if !assistantPlatformToolAllowed(session.ExecMode, tool.UpstreamName) {
				return "", fmt.Errorf("%s 不可在当前审批模式下直接调用:请把该操作连同完整参数放入 drafts(每轮 1 个,删除类需先自查引用并携带目标 id)供用户确认后执行", tool.UpstreamName)
			}
			ctx = withAssistantExecMode(ctx, session.ExecMode)
		} else if !agentToolNameAllowed(session.Mode, "agentflow", tool.UpstreamName) {
			return "", errAgentToolForbidden
		}
		if session.Mode == AgentToolScheduled {
			ctx = withAssistantExecMode(ctx, session.ExecMode)
		}
		call := assistantMCPCall{Server: "agentflow", Tool: tool.UpstreamName, Arguments: args}
		if session.canOpenConversationWorkspace() {
			ctx = withConversationSession(ctx, session.ChatSessionID)
		}
		ctx = context.WithValue(ctx, assistantControlScopeKey{}, session.ControlScope)
		ctx = context.WithValue(ctx, assistantAssetObserverKey{}, func(asset domain.AssistantAssetRef) {
			session.mu.Lock()
			defer session.mu.Unlock()
			for i, old := range session.assets {
				if old.Kind == asset.Kind && old.ID == asset.ID {
					session.assets[i] = asset
					return
				}
			}
			session.assets = append(session.assets, asset)
			if asset.Kind == "run" {
				session.runIDs = append(session.runIDs, asset.ID)
			}
		})
		// A native CLI tool call is a fresh HTTP request, so it does not inherit
		// the generation's lease context. Reattach only the authenticated
		// session's own Run lease; a different task must acquire its own lease.
		if session.WorkspaceToken != "" && session.RunID != "" && strings.HasPrefix(tool.UpstreamName, "runs_") && assistantToolInput(call).Path["id"] == session.RunID {
			ctx = engine.WithConversationWorkspaceToken(ctx, session.WorkspaceToken, session.RunID)
		}
		if session.workspaceTurn != nil && strings.HasPrefix(tool.UpstreamName, "runs_") {
			releaseTurn := session.workspaceTurn.lockOperation()
			defer releaseTurn()
			ctx = session.workspaceTurn.withLease(ctx, assistantToolInput(call).Path["id"])
		}
		asst := h.assistant()
		text, err := asst.callAssistantPlatform(ctx, session.User, session.ProjectID, call)
		if err != nil {
			return "", err
		}
		return assistantPlatformResultForModel(tool.UpstreamName, redactAgentToolResult(text, session.User)), nil
	}
	call := assistantMCPCall{Server: tool.ServerID, Tool: tool.UpstreamName, Arguments: stringifyTAPDIDs(args)}
	if call.Server == "" {
		call.Server = h.serverIDForKind(session, tool.Kind)
	}
	kind := tool.Kind
	if kind == "" {
		if server, ok := h.lookupServer(session, call.Server); ok {
			kind = classifyClarifyMCP(server)
		}
	}
	if kind == "tapd" {
		call = wrapClarifyTAPDCall(call)
		inner := strings.TrimSpace(fmt.Sprint(assistantMCPCallArguments(call)["tool_name"]))
		if call.Tool == "proxy_execute_tool" && inner != "" && !tapdInnerToolAllowed(session.Mode, inner) {
			return "", fmt.Errorf("%w: %s", errAgentToolForbidden, inner)
		}
	}
	if !agentToolNameAllowed(session.Mode, kind, tool.UpstreamName) && !(kind == "tapd" && tool.UpstreamName == "proxy_execute_tool") {
		return "", errAgentToolForbidden
	}
	if session.Mode == AgentToolAssistant && mcpCallMayWrite(kind, call) {
		name := mcpCallName(kind, call)
		if !session.ExecMode.AutoWrite {
			if err := h.waitForMCPWriteApproval(ctx, session, name, call); err != nil {
				return "", err
			}
			if !h.nativeToolTurnActive(ctx, session) {
				return "", errMCPApprovalExpired
			}
		} else if session.ExecMode.ReviewWrites {
			review := reviewAssistantAction(ctx, name, mcpServerName(h, session, call.Server)+" MCP 写入外部系统", map[string]any{"server": call.Server, "tool": call.Tool, "arguments": call.Arguments})
			if !review.allows() {
				return "", assistantReviewRefusal(name, review)
			}
		}
	} else if session.Mode != AgentToolScheduled && clarifyMCPCallWrite(kind, call) {
		name := strings.TrimSpace(call.Tool)
		if kind == "tapd" {
			if inner := strings.TrimSpace(fmt.Sprint(assistantMCPCallArguments(call)["tool_name"])); inner != "" {
				name = inner
			}
		}
		return "", fmt.Errorf("只允许只读 MCP,拒绝 %s", name)
	}
	asst := h.assistant()
	if session.Mode == AgentToolClarify {
		stream := &streamHandlers{deps: h.deps}
		text, err := stream.dispatchClarifyMCPCall(asst, session.User, session.ProjectID, call, nil)
		if err != nil {
			return "", err
		}
		return redactAgentToolResult(text, session.User), nil
	}
	text, err := asst.callAssistantMCPContext(ctx, session.User, session.ProjectID, call)
	if err != nil {
		return "", err
	}
	return redactAgentToolResult(text, session.User), nil
}

func (h *agentToolGateway) serverIDForKind(session *AgentToolSession, kind string) string {
	for _, server := range session.MCPServers {
		if classifyClarifyMCP(server) == kind {
			return server.ID
		}
	}
	return ""
}

func (h *agentToolGateway) lookupServer(session *AgentToolSession, ref string) (domain.MCPServerDefinition, bool) {
	ref = strings.TrimSpace(ref)
	for _, server := range session.MCPServers {
		if server.ID == ref || strings.EqualFold(server.Name, ref) || strings.EqualFold(server.MarketID, ref) {
			return server, true
		}
	}
	return domain.MCPServerDefinition{}, false
}

func (h *agentToolGateway) assistant() *assistantHandlers {
	return &assistantHandlers{deps: h.deps, api: h.api}
}

func (h *agentToolGateway) clarifyMCPUser(issue domain.Issue, user domain.User) domain.User {
	return (&streamHandlers{deps: h.deps}).clarifyMCPUser(issue, user)
}

func mcpServerName(h *agentToolGateway, session *AgentToolSession, ref string) string {
	if item, ok := h.lookupServer(session, ref); ok && strings.TrimSpace(item.Name) != "" {
		return item.Name
	}
	return ref
}

// mcpCallName is the tool a call runs; for TAPD it is the inner tool.
func mcpCallName(kind string, call assistantMCPCall) string {
	if kind == "tapd" {
		if inner := strings.TrimSpace(fmt.Sprint(assistantMCPCallArguments(call)["tool_name"])); inner != "" && inner != "<nil>" {
			return inner
		}
	}
	return strings.TrimSpace(call.Tool)
}

// mcpWriteVerbs mark a write when one is a whole _/-/. separated segment of
// the tool name.
var mcpWriteVerbs = []string{"add", "merge", "upload", "transition", "close", "reopen", "approve", "assign", "set", "remove", "publish", "send", "post", "submit", "comment"}

// mcpReadWords mark a read when one appears anywhere in the tool name.
var mcpReadWords = []string{"get", "list", "search", "query", "count", "lookup", "read", "fetch", "describe", "show", "info", "detail", "tree", "blame", "compare", "schema", "reference", "find", "view"}

// mcpCallMayWrite treats a call as a write unless its name reads as a read.
// The approval review is the safety net, so an unknown name such as
// merge_merge_request is reviewed instead of passing as a read.
func mcpCallMayWrite(kind string, call assistantMCPCall) bool {
	name := strings.ToLower(mcpCallName(kind, call))
	if name == "" || clarifyMCPWriteName(name) {
		return name != ""
	}
	parts := strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' || r == '.' })
	if slices.ContainsFunc(parts, func(part string) bool { return slices.Contains(mcpWriteVerbs, part) }) {
		return true
	}
	return !slices.ContainsFunc(mcpReadWords, func(word string) bool { return strings.Contains(name, word) })
}