workspace-architect 1.3.0

package/assets/instructions/java-mcp-server.instructions.md

@@ -0,0 +1,553 @@
+---
+description: 'Best practices and patterns for building Model Context Protocol (MCP) servers in Java using the official MCP Java SDK with reactive streams and Spring integration.'
+applyTo: "**/*.java, **/pom.xml, **/build.gradle, **/build.gradle.kts"
+---
+
+# Java MCP Server Development Guidelines
+
+When building MCP servers in Java, follow these best practices and patterns using the official Java SDK.
+
+## Dependencies
+
+Add the MCP Java SDK to your Maven project:
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>io.modelcontextprotocol.sdk</groupId>
+        <artifactId>mcp</artifactId>
+        <version>0.14.1</version>
+    </dependency>
+</dependencies>
+```
+
+Or for Gradle:
+
+```kotlin
+dependencies {
+    implementation("io.modelcontextprotocol.sdk:mcp:0.14.1")
+}
+```
+
+## Server Setup
+
+Create an MCP server using the builder pattern:
+
+```java
+import io.mcp.server.McpServer;
+import io.mcp.server.McpServerBuilder;
+import io.mcp.server.transport.StdioServerTransport;
+
+McpServer server = McpServerBuilder.builder()
+    .serverInfo("my-server", "1.0.0")
+    .capabilities(capabilities -> capabilities
+        .tools(true)
+        .resources(true)
+        .prompts(true))
+    .build();
+
+// Start with stdio transport
+StdioServerTransport transport = new StdioServerTransport();
+server.start(transport).subscribe();
+```
+
+## Adding Tools
+
+Register tool handlers with the server:
+
+```java
+import io.mcp.server.tool.Tool;
+import io.mcp.server.tool.ToolHandler;
+import reactor.core.publisher.Mono;
+
+// Define a tool
+Tool searchTool = Tool.builder()
+    .name("search")
+    .description("Search for information")
+    .inputSchema(JsonSchema.object()
+        .property("query", JsonSchema.string()
+            .description("Search query")
+            .required(true))
+        .property("limit", JsonSchema.integer()
+            .description("Maximum results")
+            .defaultValue(10)))
+    .build();
+
+// Register tool handler
+server.addToolHandler("search", (arguments) -> {
+    String query = arguments.get("query").asText();
+    int limit = arguments.has("limit") 
+        ? arguments.get("limit").asInt() 
+        : 10;
+    
+    // Perform search
+    List<String> results = performSearch(query, limit);
+    
+    return Mono.just(ToolResponse.success()
+        .addTextContent("Found " + results.size() + " results")
+        .build());
+});
+```
+
+## Adding Resources
+
+Implement resource handlers for data access:
+
+```java
+import io.mcp.server.resource.Resource;
+import io.mcp.server.resource.ResourceHandler;
+
+// Register resource list handler
+server.addResourceListHandler(() -> {
+    List<Resource> resources = List.of(
+        Resource.builder()
+            .name("Data File")
+            .uri("resource://data/example.txt")
+            .description("Example data file")
+            .mimeType("text/plain")
+            .build()
+    );
+    return Mono.just(resources);
+});
+
+// Register resource read handler
+server.addResourceReadHandler((uri) -> {
+    if (uri.equals("resource://data/example.txt")) {
+        String content = loadResourceContent(uri);
+        return Mono.just(ResourceContent.text(content, uri));
+    }
+    throw new ResourceNotFoundException(uri);
+});
+
+// Register resource subscribe handler
+server.addResourceSubscribeHandler((uri) -> {
+    subscriptions.add(uri);
+    log.info("Client subscribed to {}", uri);
+    return Mono.empty();
+});
+```
+
+## Adding Prompts
+
+Implement prompt handlers for templated conversations:
+
+```java
+import io.mcp.server.prompt.Prompt;
+import io.mcp.server.prompt.PromptMessage;
+import io.mcp.server.prompt.PromptArgument;
+
+// Register prompt list handler
+server.addPromptListHandler(() -> {
+    List<Prompt> prompts = List.of(
+        Prompt.builder()
+            .name("analyze")
+            .description("Analyze a topic")
+            .argument(PromptArgument.builder()
+                .name("topic")
+                .description("Topic to analyze")
+                .required(true)
+                .build())
+            .argument(PromptArgument.builder()
+                .name("depth")
+                .description("Analysis depth")
+                .required(false)
+                .build())
+            .build()
+    );
+    return Mono.just(prompts);
+});
+
+// Register prompt get handler
+server.addPromptGetHandler((name, arguments) -> {
+    if (name.equals("analyze")) {
+        String topic = arguments.getOrDefault("topic", "general");
+        String depth = arguments.getOrDefault("depth", "basic");
+        
+        List<PromptMessage> messages = List.of(
+            PromptMessage.user("Please analyze this topic: " + topic),
+            PromptMessage.assistant("I'll provide a " + depth + " analysis of " + topic)
+        );
+        
+        return Mono.just(PromptResult.builder()
+            .description("Analysis of " + topic + " at " + depth + " level")
+            .messages(messages)
+            .build());
+    }
+    throw new PromptNotFoundException(name);
+});
+```
+
+## Reactive Streams Pattern
+
+The Java SDK uses Reactive Streams (Project Reactor) for asynchronous processing:
+
+```java
+// Return Mono for single results
+server.addToolHandler("process", (args) -> {
+    return Mono.fromCallable(() -> {
+        String result = expensiveOperation(args);
+        return ToolResponse.success()
+            .addTextContent(result)
+            .build();
+    }).subscribeOn(Schedulers.boundedElastic());
+});
+
+// Return Flux for streaming results
+server.addResourceListHandler(() -> {
+    return Flux.fromIterable(getResources())
+        .map(r -> Resource.builder()
+            .uri(r.getUri())
+            .name(r.getName())
+            .build())
+        .collectList();
+});
+```
+
+## Synchronous Facade
+
+For blocking use cases, use the synchronous API:
+
+```java
+import io.mcp.server.McpSyncServer;
+
+McpSyncServer syncServer = server.toSyncServer();
+
+// Blocking tool handler
+syncServer.addToolHandler("greet", (args) -> {
+    String name = args.get("name").asText();
+    return ToolResponse.success()
+        .addTextContent("Hello, " + name + "!")
+        .build();
+});
+```
+
+## Transport Configuration
+
+### Stdio Transport
+
+For local subprocess communication:
+
+```java
+import io.mcp.server.transport.StdioServerTransport;
+
+StdioServerTransport transport = new StdioServerTransport();
+server.start(transport).block();
+```
+
+### HTTP Transport (Servlet)
+
+For HTTP-based servers:
+
+```java
+import io.mcp.server.transport.ServletServerTransport;
+import jakarta.servlet.http.HttpServlet;
+
+public class McpServlet extends HttpServlet {
+    private final McpServer server;
+    private final ServletServerTransport transport;
+    
+    public McpServlet() {
+        this.server = createMcpServer();
+        this.transport = new ServletServerTransport();
+    }
+    
+    @Override
+    protected void doPost(HttpServletRequest req, HttpServletResponse resp) {
+        transport.handleRequest(server, req, resp).block();
+    }
+}
+```
+
+## Spring Boot Integration
+
+Use the Spring Boot starter for seamless integration:
+
+```xml
+<dependency>
+    <groupId>io.modelcontextprotocol.sdk</groupId>
+    <artifactId>mcp-spring-boot-starter</artifactId>
+    <version>0.14.1</version>
+</dependency>
+```
+
+Configure the server with Spring:
+
+```java
+import org.springframework.context.annotation.Configuration;
+import io.mcp.spring.McpServerConfigurer;
+
+@Configuration
+public class McpConfiguration {
+    
+    @Bean
+    public McpServerConfigurer mcpServerConfigurer() {
+        return server -> server
+            .serverInfo("spring-server", "1.0.0")
+            .capabilities(cap -> cap
+                .tools(true)
+                .resources(true)
+                .prompts(true));
+    }
+}
+```
+
+Register handlers as Spring beans:
+
+```java
+import org.springframework.stereotype.Component;
+import io.mcp.spring.ToolHandler;
+
+@Component
+public class SearchToolHandler implements ToolHandler {
+    
+    @Override
+    public String getName() {
+        return "search";
+    }
+    
+    @Override
+    public Tool getTool() {
+        return Tool.builder()
+            .name("search")
+            .description("Search for information")
+            .inputSchema(JsonSchema.object()
+                .property("query", JsonSchema.string().required(true)))
+            .build();
+    }
+    
+    @Override
+    public Mono<ToolResponse> handle(JsonNode arguments) {
+        String query = arguments.get("query").asText();
+        return Mono.just(ToolResponse.success()
+            .addTextContent("Search results for: " + query)
+            .build());
+    }
+}
+```
+
+## Error Handling
+
+Use proper error handling with MCP exceptions:
+
+```java
+server.addToolHandler("risky", (args) -> {
+    return Mono.fromCallable(() -> {
+        try {
+            String result = riskyOperation(args);
+            return ToolResponse.success()
+                .addTextContent(result)
+                .build();
+        } catch (ValidationException e) {
+            return ToolResponse.error()
+                .message("Invalid input: " + e.getMessage())
+                .build();
+        } catch (Exception e) {
+            log.error("Unexpected error", e);
+            return ToolResponse.error()
+                .message("Internal error occurred")
+                .build();
+        }
+    });
+});
+```
+
+## JSON Schema Construction
+
+Use the fluent schema builder:
+
+```java
+import io.mcp.json.JsonSchema;
+
+JsonSchema schema = JsonSchema.object()
+    .property("name", JsonSchema.string()
+        .description("User's name")
+        .minLength(1)
+        .maxLength(100)
+        .required(true))
+    .property("age", JsonSchema.integer()
+        .description("User's age")
+        .minimum(0)
+        .maximum(150))
+    .property("email", JsonSchema.string()
+        .description("Email address")
+        .format("email")
+        .required(true))
+    .property("tags", JsonSchema.array()
+        .items(JsonSchema.string())
+        .uniqueItems(true))
+    .additionalProperties(false)
+    .build();
+```
+
+## Logging and Observability
+
+Use SLF4J for logging:
+
+```java
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+private static final Logger log = LoggerFactory.getLogger(MyMcpServer.class);
+
+server.addToolHandler("process", (args) -> {
+    log.info("Tool called: process, args: {}", args);
+    
+    return Mono.fromCallable(() -> {
+        String result = process(args);
+        log.debug("Processing completed successfully");
+        return ToolResponse.success()
+            .addTextContent(result)
+            .build();
+    }).doOnError(error -> {
+        log.error("Processing failed", error);
+    });
+});
+```
+
+Propagate context with Reactor:
+
+```java
+import reactor.util.context.Context;
+
+server.addToolHandler("traced", (args) -> {
+    return Mono.deferContextual(ctx -> {
+        String traceId = ctx.get("traceId");
+        log.info("Processing with traceId: {}", traceId);
+        
+        return Mono.just(ToolResponse.success()
+            .addTextContent("Processed")
+            .build());
+    });
+});
+```
+
+## Testing
+
+Write tests using the synchronous API:
+
+```java
+import org.junit.jupiter.api.Test;
+import static org.assertj.core.Assertions.assertThat;
+
+class McpServerTest {
+    
+    @Test
+    void testToolHandler() {
+        McpServer server = createTestServer();
+        McpSyncServer syncServer = server.toSyncServer();
+        
+        JsonNode args = objectMapper.createObjectNode()
+            .put("query", "test");
+        
+        ToolResponse response = syncServer.callTool("search", args);
+        
+        assertThat(response.isError()).isFalse();
+        assertThat(response.getContent()).hasSize(1);
+    }
+}
+```
+
+## Jackson Integration
+
+The SDK uses Jackson for JSON serialization. Customize as needed:
+
+```java
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+
+ObjectMapper mapper = new ObjectMapper();
+mapper.registerModule(new JavaTimeModule());
+
+// Use custom mapper with server
+McpServer server = McpServerBuilder.builder()
+    .objectMapper(mapper)
+    .build();
+```
+
+## Content Types
+
+Support multiple content types in responses:
+
+```java
+import io.mcp.server.content.Content;
+
+server.addToolHandler("multi", (args) -> {
+    return Mono.just(ToolResponse.success()
+        .addTextContent("Plain text response")
+        .addImageContent(imageBytes, "image/png")
+        .addResourceContent("resource://data", "application/json", jsonData)
+        .build());
+});
+```
+
+## Server Lifecycle
+
+Properly manage server lifecycle:
+
+```java
+import reactor.core.Disposable;
+
+Disposable serverDisposable = server.start(transport).subscribe();
+
+// Graceful shutdown
+Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+    log.info("Shutting down MCP server");
+    serverDisposable.dispose();
+    server.stop().block();
+}));
+```
+
+## Common Patterns
+
+### Request Validation
+
+```java
+server.addToolHandler("validate", (args) -> {
+    if (!args.has("required_field")) {
+        return Mono.just(ToolResponse.error()
+            .message("Missing required_field")
+            .build());
+    }
+    
+    return processRequest(args);
+});
+```
+
+### Async Operations
+
+```java
+server.addToolHandler("async", (args) -> {
+    return Mono.fromCallable(() -> callExternalApi(args))
+        .timeout(Duration.ofSeconds(30))
+        .onErrorResume(TimeoutException.class, e -> 
+            Mono.just(ToolResponse.error()
+                .message("Operation timed out")
+                .build()))
+        .subscribeOn(Schedulers.boundedElastic());
+});
+```
+
+### Resource Caching
+
+```java
+private final Map<String, String> cache = new ConcurrentHashMap<>();
+
+server.addResourceReadHandler((uri) -> {
+    return Mono.fromCallable(() -> 
+        cache.computeIfAbsent(uri, this::loadResource))
+        .map(content -> ResourceContent.text(content, uri));
+});
+```
+
+## Best Practices
+
+1. **Use Reactive Streams** for async operations and backpressure
+2. **Leverage Spring Boot** starter for enterprise applications
+3. **Implement proper error handling** with specific error messages
+4. **Use SLF4J** for logging, not System.out
+5. **Validate inputs** in tool and prompt handlers
+6. **Support graceful shutdown** with proper resource cleanup
+7. **Use bounded elastic scheduler** for blocking operations
+8. **Propagate context** for observability in reactive chains
+9. **Test with synchronous API** for simplicity
+10. **Follow Java naming conventions** (camelCase for methods, PascalCase for classes)

package/assets/instructions/java.instructions.md

@@ -0,0 +1,81 @@
+---
+description: 'Guidelines for building Java base applications'
+applyTo: '**/*.java'
+---
+
+# Java Development
+
+## General Instructions
+
+- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup.
+  - If yes, document a recommended static-analysis setup. 
+    - Prefer SonarQube/SonarCloud (SonarLint in IDE + `sonar-scanner` in CI).
+    - Create a Sonar project key.
+    - Store the scanner token in CI secrets.
+    - Provide a sample CI job that runs the scanner.
+    - If the team declines Sonar, note this in the project README and continue.
+  - If Sonar is bound to the project:
+    - Use Sonar as the primary source of actionable issues.
+    - Reference Sonar rule keys in remediation guidance.
+  - If Sonar is unavailable:
+    - Perform up to 3 troubleshooting checks:
+      1. Verify project binding and token.
+      2. Ensure SonarScanner runs in CI.
+      3. Confirm SonarLint is installed and configured.
+    - If still failing after 3 attempts:
+      - Enable SpotBugs, PMD, or Checkstyle as CI fallbacks.
+      - Open a short tracker issue documenting the blocker and next steps.
+- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
+- Address code smells proactively during development rather than accumulating technical debt.
+- Focus on readability, maintainability, and performance when refactoring identified issues.
+- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.
+
+## Best practices
+
+- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**.
+- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting.
+- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
+- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists.
+- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`).
+- **Null Handling**: Avoid returning or accepting `null`. Use `Optional<T>` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`.
+
+### Naming Conventions
+
+- Follow Google's Java style guide:
+  - `UpperCamelCase` for class and interface names.
+  - `lowerCamelCase` for method and variable names.
+  - `UPPER_SNAKE_CASE` for constants.
+  - `lowercase` for package names.
+- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
+- Avoid abbreviations and Hungarian notation.
+
+### Common Bug Patterns
+
+Below are concise, human-readable rules you can apply regardless of which static analysis tool you use. If you run Sonar/SonarLint, the IDE will show the matching rule and location — direct Sonar connections are preferred and should override this ruleset.
+
+- Resource management — Always close resources (files, sockets, streams). Use try-with-resources where possible so resources are closed automatically.
+- Equality checks — Compare object equality with `.equals()` or `Objects.equals(...)` rather than `==` for non-primitives; this avoids reference-equality bugs.
+- Redundant casts — Remove unnecessary casts; prefer correct generic typing and let the compiler infer types where possible.
+- Reachable conditions — Avoid conditional expressions that are always true or false; they indicate bugs or dead code and should be corrected.
+
+For contributors who *do* use Sonar or SonarLint: the IDE/scan will show the specific rule key (for example, S2095 for resource leaks) and the affected file/line. Use that information to navigate to the exact location, then apply the recommended remediation.
+
+### Common Code Smells
+
+These patterns are phrased for humans; they map cleanly to checks in Sonar, SpotBugs, PMD, or Checkstyle but do not require those tools to be useful.
+
+- Parameter count — Keep method parameter lists short. If a method needs many params, consider grouping into a value object or using the builder pattern.
+- Method size — Keep methods focused and small. Extract helper methods to improve readability and testability.
+- Cognitive complexity — Reduce nested conditionals and heavy branching by extracting methods, using polymorphism, or applying the Strategy pattern.
+- Duplicated literals — Extract repeated strings and numbers into named constants or enums to reduce errors and ease changes.
+- Dead code — Remove unused variables and assignments. They confuse readers and can hide bugs.
+- Magic numbers — Replace numeric literals with named constants that explain intent (e.g., MAX_RETRIES).
+
+If you run a static analyzer like Sonar or SonarLint — direct Sonar connections are preferred and should override this ruleset. Sonar rule keys are useful for automation and suppression, but they are not required in day-to-day developer guidance.
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.