Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
rename tools with servers
Antonio Ojea534db7ff23f9
diff --git a/cmd/sam-node/mcp.go b/cmd/sam-node/mcp.goindex 36edc45a..6c96727a 100644--- a/cmd/sam-node/mcp.go+++ b/cmd/sam-node/mcp.go@@ -38,9 +38,9 @@ import (const meshInstructions = `This MCP server connects this node to a SAM mesh: a network of remote agents that host their own MCP tools. The tools listed here are infrastructure for reaching tools on other peers when no local tool or capability covers the task.Reach into the mesh only when the needed tool isn't available locally. To do so:- 1. find_remote_tools — discover what tools exist across the mesh (returns peer_id + namespaced tool_name + description). Optionally narrow by service_name or peer_id.- 2. describe_remote_tool — fetch a specific tool's input_schema before calling it. Always do this so you know the argument shape.- 3. call_remote_tool — invoke it. Pass peer_id, the namespaced tool_name, and arguments as a JSON object whose keys match the input_schema from step 2 (not a stringified blob).+ 1. find_remote_servers — discover what tools exist across the mesh (returns peer_id + namespaced tool_name + description). Optionally narrow by service_name or peer_id.+ 2. describe_remote_server — fetch a specific tool's input_schema before calling it. Always do this so you know the argument shape.+ 3. call_remote_server — invoke it. Pass peer_id, the namespaced tool_name, and arguments as a JSON object whose keys match the input_schema from step 2 (not a stringified blob).Other useful tools: discover_remote_services browses services by type, get_mesh_info reports connected peers and mesh state, list_local_services shows what this node hosts.@@ -96,11 +96,11 @@ func NewMCPHandler(node *SamNode) http.Handler {Description: "Get information about the mesh network",}, node.handleGetMeshInfo)- // Add the call_remote_tool tool.+ // Add the call_remote_server tool.mcp.AddTool(mcpServer, &mcp.Tool{- Name: "call_remote_tool",+ Name: "call_remote_server",Description: "Call an MCP tool on a remote agent",- }, node.handleCallRemoteTool)+ }, node.handleCallRemoteServer)// Add the connect_peer tool.mcp.AddTool(mcpServer, &mcp.Tool{@@ -108,17 +108,17 @@ func NewMCPHandler(node *SamNode) http.Handler {Description: "Connect to a peer in the mesh",}, node.handleConnectPeer)- // Add the find_remote_tools tool.+ // Add the find_remote_servers tool.mcp.AddTool(mcpServer, &mcp.Tool{- Name: "find_remote_tools",+ Name: "find_remote_servers",Description: "Discover MCP tools available on hosted services across the mesh. Returns name + description per tool. Optionally narrow by peer_id, service_name, or intent (intent is reserved for future ranking and is accepted-but-ignored).",- }, node.handleFindRemoteTools)+ }, node.handleFindRemoteServers)- // Add the describe_remote_tool tool.+ // Add the describe_remote_server tool.mcp.AddTool(mcpServer, &mcp.Tool{- Name: "describe_remote_tool",- Description: "Return the description, input schema, and output schema for a specific aggregated tool on a specific peer. peer_id and tool_name are both required; tool_name must be a namespaced '<service>.<tool>' name as returned by find_remote_tools.",- }, node.handleDescribeRemoteTool)+ Name: "describe_remote_server",+ Description: "Return the description, input schema, and output schema for a specific aggregated tool on a specific peer. peer_id and tool_name are both required; tool_name must be a namespaced '<service>.<tool>' name as returned by find_remote_servers.",+ }, node.handleDescribeRemoteServer)// Create the SSE handler using the SDKsseHandler := mcp.NewSSEHandler(func(request *http.Request) *mcp.Server {diff --git a/cmd/sam-node/mcp_handlers.go b/cmd/sam-node/mcp_handlers.goindex 2c78381d..5abb4e40 100644--- a/cmd/sam-node/mcp_handlers.go+++ b/cmd/sam-node/mcp_handlers.go@@ -188,20 +188,20 @@ func (n *SamNode) handleGetMeshInfo(ctx context.Context, req *mcp.CallToolReques}, nil, nil}-// CallRemoteToolParams defines the parameters for the call_remote_tool tool.+// CallRemoteServerParams defines the parameters for the call_remote_server tool.//// Arguments is a JSON object whose shape matches the target tool's-// input_schema (use describe_remote_tool to fetch it). Earlier revisions+// input_schema (use describe_remote_server to fetch it). Earlier revisions// took a stringified JSON blob here; that footgun is gone.-type CallRemoteToolParams struct {+type CallRemoteServerParams struct {PeerID string `json:"peer_id" jsonschema:"The Peer ID of the target agent"`ToolName string `json:"tool_name" jsonschema:"The name of the tool to call"`- Arguments map[string]any `json:"arguments,omitempty" jsonschema:"Tool arguments as a JSON object whose keys match the target tool's input_schema. Call describe_remote_tool first to learn the schema."`+ Arguments map[string]any `json:"arguments,omitempty" jsonschema:"Tool arguments as a JSON object whose keys match the target tool's input_schema. Call describe_remote_server first to learn the schema."`}-// handleCallRemoteTool implements the call_remote_tool tool.-func (n *SamNode) handleCallRemoteTool(ctx context.Context, req *mcp.CallToolRequest, params CallRemoteToolParams) (*mcp.CallToolResult, any, error) {- logger.Infof("[MCP] call_remote_tool called for peer %s, tool %s", params.PeerID, params.ToolName)+// handleCallRemoteServer implements the call_remote_server tool.+func (n *SamNode) handleCallRemoteServer(ctx context.Context, req *mcp.CallToolRequest, params CallRemoteServerParams) (*mcp.CallToolResult, any, error) {+ logger.Infof("[MCP] call_remote_server called for peer %s, tool %s", params.PeerID, params.ToolName)targetPeer, err := peer.Decode(params.PeerID)if err != nil {return nil, nil, err@@ -238,22 +238,22 @@ func (n *SamNode) handleConnectPeer(ctx context.Context, req *mcp.CallToolReques}, nil, nil}-// FindRemoteToolsParams defines the parameters for the-// find_remote_tools tool.-type FindRemoteToolsParams struct {+// FindRemoteServersParams defines the parameters for the+// find_remote_servers tool.+type FindRemoteServersParams struct {Intent string `json:"intent,omitempty" jsonschema:"Natural-language description of what the caller is looking for. Reserved for future semantic ranking; currently accepted but ignored."`PeerID string `json:"peer_id,omitempty" jsonschema:"Restrict the search to a single peer. Empty means search the whole mesh."`ServiceName string `json:"service_name,omitempty" jsonschema:"Restrict results to tools whose name starts with this service prefix (e.g. 'code-reviewer'). Empty means no service filter."`}-// remoteToolRow is one entry in the find_remote_tools response.-type remoteToolRow struct {+// remoteServerRow is one entry in the find_remote_servers response.+type remoteServerRow struct {PeerID string `json:"peer_id"`ToolName string `json:"tool_name"`Description string `json:"description"`}-// handleFindRemoteTools implements the find_remote_tools tool.+// handleFindRemoteServers implements the find_remote_servers tool.//// Scope:// - If params.PeerID is set, only that peer is queried.@@ -266,9 +266,9 @@ type remoteToolRow struct {// - params.Intent is accepted and logged at debug level, but does not// filter or rank results in this implementation (placeholder for// future semantic search).-func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRequest, params FindRemoteToolsParams) (*mcp.CallToolResult, any, error) {+func (n *SamNode) handleFindRemoteServers(ctx context.Context, req *mcp.CallToolRequest, params FindRemoteServersParams) (*mcp.CallToolResult, any, error) {if params.Intent != "" {- logger.Debugf("[find_remote_tools] intent (ignored): %q", params.Intent)+ logger.Debugf("[find_remote_servers] intent (ignored): %q", params.Intent)}selfID := n.Host.ID().String()@@ -276,7 +276,7 @@ func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRereturn nil, nil, fmt.Errorf("peer_id %q is this node; cross-mesh discovery cannot target self", params.PeerID)}- var rows []remoteToolRow+ var rows []remoteServerRowif params.PeerID != "" {pid, err := peer.Decode(params.PeerID)@@ -311,7 +311,7 @@ func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRe}if rows == nil {- rows = []remoteToolRow{}+ rows = []remoteServerRow{}}respData, err := json.Marshal(rows)if err != nil {@@ -396,7 +396,7 @@ func (n *SamNode) fetchRemoteToolCatalogue(ctx context.Context, targetPeer peer.// appendFilteredRows appends rows for tools that have a namespaced name// (containing ".") and, if serviceName is non-empty, whose name starts// with "<serviceName>.".-func appendFilteredRows(rows []remoteToolRow, peerID string, tools []*mcp.Tool, serviceName string) []remoteToolRow {+func appendFilteredRows(rows []remoteServerRow, peerID string, tools []*mcp.Tool, serviceName string) []remoteServerRow {for _, tool := range tools {if !strings.Contains(tool.Name, ".") {continue@@ -404,7 +404,7 @@ func appendFilteredRows(rows []remoteToolRow, peerID string, tools []*mcp.Tool,if serviceName != "" && !strings.HasPrefix(tool.Name, serviceName+".") {continue}- rows = append(rows, remoteToolRow{+ rows = append(rows, remoteServerRow{PeerID: peerID,ToolName: tool.Name,Description: tool.Description,@@ -416,13 +416,13 @@ func appendFilteredRows(rows []remoteToolRow, peerID string, tools []*mcp.Tool,// fanOutFetch queries each peer's tool catalogue concurrently with a// small cap and returns the filtered rows. Per-peer failures are// logged at debug level and skipped — best-effort mesh-wide fetch.-func (n *SamNode) fanOutFetch(ctx context.Context, peers []peer.ID, serviceName string) []remoteToolRow {+func (n *SamNode) fanOutFetch(ctx context.Context, peers []peer.ID, serviceName string) []remoteServerRow {const maxConcurrent = 8sem := make(chan struct{}, maxConcurrent)var (mu sync.Mutex- rows []remoteToolRow+ rows []remoteServerRow)var wg sync.WaitGroup@@ -439,7 +439,7 @@ func (n *SamNode) fanOutFetch(ctx context.Context, peers []peer.ID, serviceNametools, err := n.fetchRemoteToolCatalogue(peerCtx, pid)if err != nil {- logger.Debugf("[find_remote_tools] peer %s skipped: %v", pid, err)+ logger.Debugf("[find_remote_servers] peer %s skipped: %v", pid, err)return}@@ -454,7 +454,7 @@ func (n *SamNode) fanOutFetch(ctx context.Context, peers []peer.ID, serviceName}// remoteToolDescription is the JSON payload describe_local_tool emits on the-// peer side and describe_remote_tool re-emits on the caller side. The+// peer side and describe_remote_server re-emits on the caller side. The// caller-side handler fills PeerID; the peer-side handler leaves it empty.//// InputSchema and OutputSchema mirror mcp.Tool's typing (`any`): the SDK@@ -468,15 +468,15 @@ type remoteToolDescription struct {OutputSchema any `json:"output_schema,omitempty"`}-// DescribeRemoteToolParams defines parameters for the describe_remote_tool+// DescribeRemoteToolParams defines parameters for the describe_remote_server// sidecar tool.type DescribeRemoteToolParams struct {PeerID string `json:"peer_id" jsonschema:"Peer ID of the node hosting the tool. Required."`- ToolName string `json:"tool_name" jsonschema:"Namespaced tool name as returned by find_remote_tools (e.g. 'code-reviewer.review_pr'). Required."`+ ToolName string `json:"tool_name" jsonschema:"Namespaced tool name as returned by find_remote_servers (e.g. 'code-reviewer.review_pr'). Required."`}-// handleDescribeRemoteTool implements the describe_remote_tool client-facing tool.-func (n *SamNode) handleDescribeRemoteTool(ctx context.Context, req *mcp.CallToolRequest, params DescribeRemoteToolParams) (*mcp.CallToolResult, any, error) {+// handleDescribeRemoteServer implements the describe_remote_server client-facing tool.+func (n *SamNode) handleDescribeRemoteServer(ctx context.Context, req *mcp.CallToolRequest, params DescribeRemoteToolParams) (*mcp.CallToolResult, any, error) {if params.PeerID == "" {return nil, nil, fmt.Errorf("peer_id is required")}diff --git a/cmd/sam-node/mcp_handlers_test.go b/cmd/sam-node/mcp_handlers_test.goindex 998e0ad1..45d5dd53 100644--- a/cmd/sam-node/mcp_handlers_test.go+++ b/cmd/sam-node/mcp_handlers_test.go@@ -61,9 +61,9 @@ func TestHandleFindRemoteTools_EmptyMesh_ReturnsEmptyArray(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- res, _, err := node.handleFindRemoteTools(ctx, &mcp.CallToolRequest{}, FindRemoteToolsParams{})+ res, _, err := node.handleFindRemoteServers(ctx, &mcp.CallToolRequest{}, FindRemoteServersParams{})if err != nil {- t.Fatalf("handleFindRemoteTools: %v", err)+ t.Fatalf("handleFindRemoteServers: %v", err)}if len(res.Content) == 0 {t.Fatal("expected non-empty result content")@@ -88,7 +88,7 @@ func TestHandleFindRemoteTools_SelfPeerRejected(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleFindRemoteTools(ctx, &mcp.CallToolRequest{}, FindRemoteToolsParams{+ _, _, err := node.handleFindRemoteServers(ctx, &mcp.CallToolRequest{}, FindRemoteServersParams{PeerID: node.Host.ID().String(),})if err == nil {@@ -144,17 +144,17 @@ func TestHandleFindRemoteTools_SinglePeer(t *testing.T) {t.Fatalf("RegisterService: %v", err)}- res, _, err := nodeA.handleFindRemoteTools(ctx, &mcp.CallToolRequest{}, FindRemoteToolsParams{+ res, _, err := nodeA.handleFindRemoteServers(ctx, &mcp.CallToolRequest{}, FindRemoteServersParams{PeerID: nodeB.Host.ID().String(),})if err != nil {- t.Fatalf("handleFindRemoteTools: %v", err)+ t.Fatalf("handleFindRemoteServers: %v", err)}tc, ok := res.Content[0].(*mcp.TextContent)if !ok {t.Fatalf("expected TextContent, got %T", res.Content[0])}- var rows []remoteToolRow+ var rows []remoteServerRowif err := json.Unmarshal([]byte(tc.Text), &rows); err != nil {t.Fatalf("unmarshal: %v (text: %q)", err, tc.Text)}@@ -295,12 +295,12 @@ func TestHandleFindRemoteTools_MeshWideViaHandler(t *testing.T) {// Give the DHT a moment to record the provider.time.Sleep(5 * time.Second)- res, _, err := nodeA.handleFindRemoteTools(ctx, &mcp.CallToolRequest{}, FindRemoteToolsParams{})+ res, _, err := nodeA.handleFindRemoteServers(ctx, &mcp.CallToolRequest{}, FindRemoteServersParams{})if err != nil {t.Fatalf("handler: %v", err)}tc := res.Content[0].(*mcp.TextContent)- var rows []remoteToolRow+ var rows []remoteServerRowif err := json.Unmarshal([]byte(tc.Text), &rows); err != nil {t.Fatal(err)}@@ -452,7 +452,7 @@ func TestNewMCPHandler_RegistersFindRemoteTools(t *testing.T) {}found := falsefor _, tl := range res.Tools {- if tl.Name == "find_remote_tools" {+ if tl.Name == "find_remote_servers" {found = true}}@@ -461,7 +461,7 @@ func TestNewMCPHandler_RegistersFindRemoteTools(t *testing.T) {for _, tl := range res.Tools {names = append(names, tl.Name)}- t.Errorf("find_remote_tools missing from sidecar tools/list; got %v", names)+ t.Errorf("find_remote_servers missing from sidecar tools/list; got %v", names)}}@@ -472,7 +472,7 @@ func TestHandleDescribeRemoteTool_EmptyPeerID(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err := node.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{ToolName: "code-reviewer.review_pr",})if err == nil {@@ -487,7 +487,7 @@ func TestHandleDescribeRemoteTool_EmptyToolName(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err := node.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: "12D3KooWFakePeerID",})if err == nil {@@ -502,7 +502,7 @@ func TestHandleDescribeRemoteTool_NonNamespacedRejected(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err := node.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: node.Host.ID().String(),ToolName: "send_message", // no dot})@@ -521,7 +521,7 @@ func TestHandleDescribeRemoteTool_SelfPeerRejected(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err := node.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: node.Host.ID().String(),ToolName: "code-reviewer.review_pr",})@@ -537,7 +537,7 @@ func TestHandleDescribeRemoteTool_InvalidPeerID(t *testing.T) {node, cleanup := startBareNode(t, ctx)defer cleanup()- _, _, err := node.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err := node.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: "not-a-valid-peer-id",ToolName: "code-reviewer.review_pr",})@@ -601,12 +601,12 @@ func TestHandleDescribeRemoteTool_RoundTrip(t *testing.T) {}defer func() { _ = nodeB.UnregisterService(ctx, "code-reviewer") }()- res, _, err := nodeA.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ res, _, err := nodeA.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: nodeB.Host.ID().String(),ToolName: "code-reviewer.review_pr",})if err != nil {- t.Fatalf("handleDescribeRemoteTool: %v", err)+ t.Fatalf("handleDescribeRemoteServer: %v", err)}tc, ok := res.Content[0].(*mcp.TextContent)if !ok {@@ -679,7 +679,7 @@ func TestHandleDescribeRemoteTool_RoundTrip_UnknownTool(t *testing.T) {}defer func() { _ = nodeB.UnregisterService(ctx, "code-reviewer") }()- _, _, err = nodeA.handleDescribeRemoteTool(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{+ _, _, err = nodeA.handleDescribeRemoteServer(ctx, &mcp.CallToolRequest{}, DescribeRemoteToolParams{PeerID: nodeB.Host.ID().String(),ToolName: "code-reviewer.does-not-exist",})@@ -716,7 +716,7 @@ func TestNewMCPHandler_RegistersDescribeRemoteTool(t *testing.T) {}found := falsefor _, tl := range res.Tools {- if tl.Name == "describe_remote_tool" {+ if tl.Name == "describe_remote_server" {found = true}}@@ -725,7 +725,7 @@ func TestNewMCPHandler_RegistersDescribeRemoteTool(t *testing.T) {for _, tl := range res.Tools {names = append(names, tl.Name)}- t.Errorf("describe_remote_tool missing from sidecar tools/list; got %v", names)+ t.Errorf("describe_remote_server missing from sidecar tools/list; got %v", names)}}diff --git a/cmd/sam-node/middleware.go b/cmd/sam-node/middleware.goindex 1f36f4d5..ead67afd 100644--- a/cmd/sam-node/middleware.go+++ b/cmd/sam-node/middleware.go@@ -319,7 +319,8 @@ func (n *SamNode) Authorize(rawToken []byte, req RequestContext, pubKey ed25519.err = authorizer.Authorize()if err != nil {- logger.Errorf("Authorizer failure: %v\nState: %s", err, authorizer.PrintWorld())+ logger.Errorf("Authorizer failure: %v", err)+ logger.Debugf("Authorizer state: %s", authorizer.PrintWorld())}return err}diff --git a/cmd/sam-node/service_registry.go b/cmd/sam-node/service_registry.goindex fc8c6075..f7685579 100644--- a/cmd/sam-node/service_registry.go+++ b/cmd/sam-node/service_registry.go@@ -66,13 +66,15 @@ func (r *ServiceRegistry) Register(ctx context.Context, svc Service) error {return err}- provideCtx, cancel := context.WithTimeout(ctx, 5*time.Second)- defer cancel()-- if err := r.dht.Provide(provideCtx, srvNameCID, true); err != nil {+ nameCtx, nameCancel := context.WithTimeout(ctx, 5*time.Second)+ defer nameCancel()+ if err := r.dht.Provide(nameCtx, srvNameCID, true); err != nil {logger.Warnf("[ServiceRegistry] DHT Provide (name) for %s: %v", info.Name, err)}- if err := r.dht.Provide(provideCtx, srvTypeCID, true); err != nil {++ typeCtx, typeCancel := context.WithTimeout(ctx, 5*time.Second)+ defer typeCancel()+ if err := r.dht.Provide(typeCtx, srvTypeCID, true); err != nil {logger.Warnf("[ServiceRegistry] DHT Provide (type) for %s: %v", info.Name, err)}@@ -159,11 +161,15 @@ func (r *ServiceRegistry) ReprovideAll(ctx context.Context) {for _, info := range toProvide {srvNameCID, err := serviceNameToCID(info.Type, info.Name)if err == nil {- _ = r.dht.Provide(ctx, srvNameCID, true)+ nameCtx, cancel := context.WithTimeout(ctx, 5*time.Second)+ _ = r.dht.Provide(nameCtx, srvNameCID, true)+ cancel()}srvTypeCID, err := serviceTypeToCID(info.Type)if err == nil {- _ = r.dht.Provide(ctx, srvTypeCID, true)+ typeCtx, cancel := context.WithTimeout(ctx, 5*time.Second)+ _ = r.dht.Provide(typeCtx, srvTypeCID, true)+ cancel()}}}