MCP Mesh Annotations (Java/Spring Boot)¶

@MeshAgent(
    name = "my-service",          // Required: unique agent identifier
    version = "1.0.0",            // Semantic version
    description = "Service desc", // Human-readable description
    port = 8080                   // HTTP server port
)
@SpringBootApplication
public class MyAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApplication.class, args);
    }
}

@MeshTool(
    capability = "greeting",              // Capability name for discovery
    description = "Greets users",         // Human-readable description
    version = "1.0.0",                    // Capability version
    tags = {"greeting", "utility"},       // Tags for filtering
    dependencies = @Selector(             // Required capabilities
        capability = "date_service")
)
public GreetingResponse greet(
        @Param(value = "name", description = "The name") String name,
        McpMeshTool<String> dateService) {       // Injected dependency
    if (dateService != null && dateService.isAvailable()) {
        String today = dateService.call();
        return new GreetingResponse("Hello " + name + "! Today is " + today);
    }
    return new GreetingResponse("Hello " + name + "!");
}

@MeshTool(capability = "search", description = "Search documents")
public SearchResult search(
        @Param(value = "query", description = "Search query") String query,
        @Param(value = "limit", description = "Max results") int limit) {
    /* ... */
}

// By capability name
@Selector(capability = "date_service")

// With tag filters
@Selector(capability = "weather_data", tags = {"+fast", "-deprecated"})

// With version constraint
@Selector(capability = "api_client", version = ">=2.0.0")

// Tags only (for LLM tool filtering)
@Selector(tags = {"data", "tools"})

@MeshLlm(
    providerSelector = @Selector(capability = "llm"),  // Find LLM via mesh
    maxIterations = 5,                                  // Max agentic loops
    systemPrompt = "classpath:prompts/analyst.ftl",     // FreeMarker template
    contextParam = "ctx",                               // Parameter for context
    filter = @Selector(tags = {"data", "tools"}),       // Tool filter
    filterMode = FilterMode.ALL,                        // Filter mode
    maxTokens = 4096,                                   // Max output tokens
    temperature = 0.7                                   // Sampling temperature
)
@MeshTool(capability = "analyze",
          description = "AI-powered analysis",
          tags = {"analysis", "llm", "java"})
public AnalysisResult analyze(
        @Param(value = "ctx", description = "Analysis context") AnalysisContext ctx,
        MeshLlmAgent llm) {
    return llm.request()
              .user(ctx.query())
              .maxTokens(4096)
              .temperature(0.7)
              .generate(AnalysisResult.class);
}

@MeshLlm(
    provider = "claude",                    // Direct provider name
    maxIterations = 1,                      // Single generation
    systemPrompt = "You are a helpful assistant.",
    maxTokens = 1024,
    temperature = 0.7
)
@MeshTool(capability = "chat",
          description = "Chat with Claude",
          tags = {"chat", "llm", "java", "direct"})
public ChatResponse chat(
        @Param(value = "message", description = "User message") String message,
        MeshLlmAgent llm) {
    if (llm != null && llm.isAvailable()) {
        String response = llm.generate(message);
        return new ChatResponse(response);
    }
    return new ChatResponse("LLM unavailable");
}

// Simple text generation
String response = llm.generate(message);

// Builder pattern with structured output
AnalysisResult result = llm.request()
    .system("Custom system prompt")
    .user("Analyze this data")
    .maxTokens(4096)
    .temperature(0.7)
    .generate(AnalysisResult.class);

// With message history
String response = llm.request()
    .messages(conversationHistory)
    .user("Follow-up question")
    .generate();

// Check availability
if (llm != null && llm.isAvailable()) { /* ... */ }

// Get generation metadata
llm.request().lastMeta();

@MeshAgent(name = "claude-provider", version = "1.0.0",
           description = "Claude LLM provider for mesh", port = 9110)
@MeshLlmProvider(
    model = "anthropic/claude-sonnet-4-5",            // LiteLLM model string
    capability = "llm",                                // Capability name
    tags = {"llm", "claude", "anthropic", "provider"}, // Discovery tags
    version = "1.0.0"                                  // Provider version
)
@SpringBootApplication
public class ClaudeProviderApplication {
    public static void main(String[] args) {
        SpringApplication.run(ClaudeProviderApplication.class, args);
    }
    // No implementation needed - annotation handles everything
}

@MeshRoute(dependencies = @Selector(capability = "avatar_chat"))
@PostMapping("/chat")
public ResponseEntity<ChatResponse> chat(
        @RequestBody ChatRequest request,
        McpMeshTool<String> avatarChat) {
    if (avatarChat == null || !avatarChat.isAvailable()) {
        return ResponseEntity.status(503)
            .body(new ChatResponse("Service unavailable"));
    }
    String result = avatarChat.call("message", request.message());
    return ResponseEntity.ok(new ChatResponse(result));
}

package com.example.calculator;

import io.mcpmesh.*;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@MeshAgent(name = "calculator", version = "1.0.0",
           description = "Calculator with logging", port = 8080)
@SpringBootApplication
public class CalculatorApplication {

    public static void main(String[] args) {
        SpringApplication.run(CalculatorApplication.class, args);
    }

    // Basic tool - no dependencies
    @MeshTool(capability = "add",
              description = "Add two numbers",
              tags = {"math", "calculator", "java"})
    public int add(@Param(value = "a", description = "First number") int a,
                   @Param(value = "b", description = "Second number") int b) {
        return a + b;
    }

    // Tool with dependency
    @MeshTool(capability = "calculator_logged",
              description = "Calculate with audit logging",
              tags = {"math", "calculator", "audit", "java"},
              dependencies = @Selector(capability = "audit_log"))
    public CalculationResult calculateWithLogging(
            @Param(value = "operation", description = "Operation") String operation,
            @Param(value = "a", description = "First number") int a,
            @Param(value = "b", description = "Second number") int b,
            McpMeshTool<String> auditLog) {

        int result = operation.equals("add") ? a + b : a - b;

        if (auditLog != null && auditLog.isAvailable()) {
            auditLog.call("action", "calculation",
                          "operation", operation, "result", result);
        }

        return new CalculationResult(operation, a, b, result);
    }

    record CalculationResult(String operation, int a, int b, int result) {}
}