Improving API

Author: tvallin

integrations/mcp/server/pom.xml

@@ -42,6 +42,10 @@
 			<groupId>io.helidon.http.media</groupId>
 			<artifactId>helidon-http-media-jackson</artifactId>
 		</dependency>
+		<dependency>
+			<groupId>io.helidon.http.media</groupId>
+			<artifactId>helidon-http-media-jsonp</artifactId>
+		</dependency>
 		<dependency>
 			<groupId>io.helidon.webserver.testing.junit5</groupId>
 			<artifactId>helidon-webserver-testing-junit5</artifactId>

integrations/mcp/server/src/main/java/io/helidon/integrations/mcp/server/Capability.java

@@ -1,11 +1,51 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package io.helidon.integrations.mcp.server;
 
+/**
+ * Server capabilities.
+ */
 public enum Capability {
+    /**
+     * Notify clients when list of {@link Tool} changes.
+     */
     TOOL_LIST_CHANGED,
+    /**
+     * Notify clients when list of {@link Resource} changes
+     */
     RESOURCE_LIST_CHANGED,
+    /**
+     * Allow clients to subscribe to a {@link Resource} and be notified when its content changes.
+     */
     RESOURCE_SUBSCRIBE,
+    /**
+     * Notify clients when list of {@link Prompt} changes.
+     */
     PROMPT_LIST_CHANGED,
+    /**
+     * Enable logging capability.
+     */
     LOGGING,
+    /**
+     * Enable completion capability.
+     */
     COMPLETION,
+    /**
+     * Enable pagination capability.
+     */
     PAGINATION
 }

integrations/mcp/server/src/main/java/io/helidon/integrations/mcp/server/InputSchema.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.integrations.mcp.server;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+import jakarta.json.Json;
+import jakarta.json.JsonArrayBuilder;
+import jakarta.json.JsonObjectBuilder;
+
+/**
+ * Tool input schema description.
+ */
+public class JsonSchema {
+
+    private final Map<String, Object> schema = new HashMap<>();
+
+    private JsonSchema(Builder builder) {
+        schema.put("id", builder.id);
+        schema.put("type", builder.type);
+
+        JsonArrayBuilder array = Json.createArrayBuilder();
+        builder.required.forEach(array::add);
+        schema.put("required", array);
+
+        JsonObjectBuilder properties = Json.createObjectBuilder();
+        builder.properties.forEach(properties::add);
+    }
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder {
+
+        private final String type;
+        private final String id;
+        private final List<String> required;
+        private final Map<String, String> properties;
+
+        private Builder() {
+            this.id = "jsonSchema-" + UUID.randomUUID();
+            this.type = "object";
+            this.required = new ArrayList<>();
+            this.properties = new HashMap<>();
+        }
+
+        public Builder object(String key, Class<?> type, boolean required) {
+            this.properties.put(key, type.toString());
+            if (required) {
+                this.required.add(key);
+            }
+            return this;
+        }
+
+        public Builder object(String key, Class<?> type) {
+            this.properties.put(key, type.toString());
+            this.required.add(key);
+            return this;
+        }
+
+        public JsonSchema build() {
+            return new JsonSchema(this);
+        }
+
+    }
+
+}

integrations/mcp/server/src/main/java/io/helidon/integrations/mcp/server/JsonSchema.java

@@ -16,7 +16,7 @@
 
 package io.helidon.integrations.mcp.server;
 
-import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -26,61 +26,125 @@
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
 
 /**
- * This interface contains a set of annotations for defining MCP declarative server.
+ * This interface contains a set of annotations to define an MCP declarative server.
  */
 public final class Mcp {
 
+	/**
+	 * Annotation to define a MCP server.
+	 */
 	@Target(TYPE)
 	@Retention(RUNTIME)
 	public @interface Server {
 		String value() default "Helidon MCP Server";
 	}
 
+	/**
+	 * Annotation to define the {@link Server} capabilities.
+	 */
 	@Target(TYPE)
 	@Retention(RUNTIME)
+	@Repeatable(Capabilities.class)
 	public @interface Capability {
-		io.helidon.integrations.mcp.server.Capability[] value();
+		io.helidon.integrations.mcp.server.Capability value();
 	}
 
+	/**
+	 * Set of {@link Capability}.
+	 */
+	@Target(TYPE)
+	@Retention(RUNTIME)
+	public @interface Capabilities {
+		Capability[] value();
+	}
+
+	/**
+	 * Annotation to describe an MCP component such as {@link Tool}, {@link Prompt} and {@link Resource}.
+	 */
 	@Target({TYPE, METHOD})
 	@Retention(RUNTIME)
 	public @interface Description {
 		String value();
 	}
 
+	/**
+	 * Annotation to define the {@link Server} version.
+	 */
 	@Target(TYPE)
 	@Retention(RUNTIME)
 	public @interface Version {
 		String value();
 	}
 
+	/**
+	 * Annotation to define an MCP Tool.
+	 */
 	@Target(METHOD)
 	@Retention(RUNTIME)
-	public @interface Prompt {
+	public @interface Tool {
 		String value() default "";
 	}
 
+	/**
+	 * Annotation to manually register classes containing {@link Tool}.
+	 */
+	@Target(TYPE)
+	@Retention(RUNTIME)
+	public @interface Tools {
+		Class<?>[] value();
+	}
+
+	/**
+	 * Annotation to define an MCP Prompt.
+	 */
 	@Target(METHOD)
 	@Retention(RUNTIME)
-	public @interface Tool {
+	public @interface Prompt {
 		String value() default "";
 	}
 
-	@Target(PARAMETER)
+	/**
+	 * Annotation to manually register classes containing {@link Prompt}.
+	 */
+	@Target(TYPE)
 	@Retention(RUNTIME)
-	public @interface Param {
-		String value();
+	public @interface Prompts {
+		Class<?>[] value();
 	}
 
+	/**
+	 * Annotation to define an MCP resource.
+	 */
 	@Target(METHOD)
 	@Retention(RUNTIME)
 	public @interface Resource {
 		String value() default "";
 	}
 
+	/**
+	 * Annotation to manually register classes containing {@link Resource}.
+	 */
+	@Target(TYPE)
+	@Retention(RUNTIME)
+	public @interface Resources {
+		Class<?>[] value();
+	}
+
+	/**
+	 * Annotation to define a {@link Resource} URI
+	 */
 	@Target(METHOD)
 	@Retention(RUNTIME)
 	public @interface URI {
 		String value();
 	}
+
+	/**
+	 * Annotation to define a {@link Tool} and {@link Prompt} argument.
+	 */
+	@Target(PARAMETER)
+	@Retention(RUNTIME)
+	public @interface Param {
+		String value();
+	}
 }