|
| 1 | +--- |
| 2 | +hide: |
| 3 | + - navigation |
| 4 | +--- |
| 5 | + |
| 6 | +# Getting Started |
| 7 | + |
| 8 | +## Requirements |
| 9 | + |
| 10 | +🔒 Java 17 or later (Restricted by MCP Java SDK) |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +Add the following Maven dependency to your project: |
| 15 | + |
| 16 | +```xml |
| 17 | +<!-- Internally relies on native MCP Java SDK 0.11.1 --> |
| 18 | +<dependency> |
| 19 | + <groupId>io.github.codeboyzhou</groupId> |
| 20 | + <artifactId>mcp-declarative-java-sdk</artifactId> |
| 21 | + <version>0.6.0</version> |
| 22 | +</dependency> |
| 23 | +``` |
| 24 | + |
| 25 | +## MCP Server |
| 26 | + |
| 27 | +Now you can create a simple MCP server with just one line of core code. |
| 28 | + |
| 29 | +### Stdio Server |
| 30 | + |
| 31 | +#### Quick Start |
| 32 | + |
| 33 | +```java |
| 34 | +import com.github.codeboyzhou.mcp.declarative.McpServers; |
| 35 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpServerApplication; |
| 36 | +import com.github.codeboyzhou.mcp.declarative.server.McpServerInfo; |
| 37 | + |
| 38 | +@McpServerApplication |
| 39 | +public class McpStdioServer { |
| 40 | + |
| 41 | + public static void main(String[] args) { |
| 42 | + McpServers.run(McpStdioServer.class, args).startStdioServer(McpServerInfo.builder().build()); |
| 43 | + } |
| 44 | + |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +In the sample code above, we created a simple MCP server, which is based on the stdio transport mode. |
| 49 | +`@McpServerApplication` |
| 50 | +is a convenience annotation that helps to locate the package path of MCP server components, such as resources, prompts, |
| 51 | +and tools. |
| 52 | + |
| 53 | +You can also explicitly specify the package path to scan, either of the two ways below is sufficient: |
| 54 | + |
| 55 | +```java |
| 56 | +@McpServerApplication(basePackageClass = McpStdioServer.class) |
| 57 | +``` |
| 58 | + |
| 59 | +```java |
| 60 | +@McpServerApplication(basePackage = "com.github.codeboyzhou.mcp.server.examples") |
| 61 | +``` |
| 62 | + |
| 63 | +If you don't specify the package path, the annotation will scan the package where the main method is located. |
| 64 | + |
| 65 | +#### Server Info |
| 66 | + |
| 67 | +In addition, for the method `startStdioServer`, you need to provide a `McpServerInfo` object, which contains the basic |
| 68 | +information of the MCP server, such as name, version, and instructions, etc. |
| 69 | + |
| 70 | +The following is all the field information about class `McpServerInfo`: |
| 71 | + |
| 72 | +| Field | Type | Description | Default Value | |
| 73 | +|------------------|----------|---------------------------------------|----------------| |
| 74 | +| `name` | String | The name of the MCP server | `mcp-server` | |
| 75 | +| `version` | String | The version of the MCP server | `1.0.0` | |
| 76 | +| `instructions` | String | The instructions of the MCP server | (empty string) | |
| 77 | +| `requestTimeout` | Duration | The timeout of the MCP server request | `20` seconds | |
| 78 | + |
| 79 | +#### How to run |
| 80 | + |
| 81 | +For a MCP stdio server to run, you need to package your project into an executable jar file. |
| 82 | + |
| 83 | +There is a Maven plugin that can handle this, just place the following configuration into your root `pom.xml`: |
| 84 | + |
| 85 | +```xml |
| 86 | + |
| 87 | +<plugins> |
| 88 | + <!-- Your other plugins ... --> |
| 89 | + <plugin> |
| 90 | + <groupId>org.apache.maven.plugins</groupId> |
| 91 | + <artifactId>maven-shade-plugin</artifactId> |
| 92 | + <version>${maven-shade-plugin.version}</version> |
| 93 | + <executions> |
| 94 | + <execution> |
| 95 | + <goals> |
| 96 | + <goal>shade</goal> |
| 97 | + </goals> |
| 98 | + <phase>package</phase> |
| 99 | + <configuration> |
| 100 | + <transformers> |
| 101 | + <transformer |
| 102 | + implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer"> |
| 103 | + <mainClass>com.github.codeboyzhou.mcp.server.examples.McpStdioServer</mainClass> |
| 104 | + </transformer> |
| 105 | + </transformers> |
| 106 | + </configuration> |
| 107 | + </execution> |
| 108 | + </executions> |
| 109 | + </plugin> |
| 110 | +</plugins> |
| 111 | +``` |
| 112 | + |
| 113 | +### HTTP SSE Server |
| 114 | + |
| 115 | +#### Quick Start |
| 116 | + |
| 117 | +```java |
| 118 | +import com.github.codeboyzhou.mcp.declarative.McpServers; |
| 119 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpServerApplication; |
| 120 | +import com.github.codeboyzhou.mcp.declarative.server.McpSseServerInfo; |
| 121 | + |
| 122 | +@McpServerApplication |
| 123 | +public class McpSseServer { |
| 124 | + |
| 125 | + public static void main(String[] args) { |
| 126 | + McpServers.run(McpSseServer.class, args).startSseServer(McpSseServerInfo.builder().build()); |
| 127 | + } |
| 128 | + |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +#### Server Info |
| 133 | + |
| 134 | +For the method `startSseServer`, you can specify the server information by using `McpSseServerInfo`: |
| 135 | + |
| 136 | +| Field | Type | Description | Default Value | |
| 137 | +|-------------------|----------|----------------------------------------|----------------| |
| 138 | +| `name` | String | The name of the MCP server | `mcp-server` | |
| 139 | +| `version` | String | The version of the MCP server | `1.0.0` | |
| 140 | +| `instructions` | String | The instructions of the MCP server | (empty string) | |
| 141 | +| `requestTimeout` | Duration | The timeout of the MCP server request | `20` seconds | |
| 142 | +| `baseUrl` | String | The base URL of the MCP server | (empty string) | |
| 143 | +| `messageEndpoint` | String | The endpoint of the MCP server message | `/mcp/message` | |
| 144 | +| `sseEndpoint` | String | The endpoint for HTTP SSE mode | `/sse` | |
| 145 | +| `port` | int | The port for HTTP SSE mode | `8080` | |
| 146 | + |
| 147 | +#### How to run |
| 148 | + |
| 149 | +Just run the main class like you would launch a web application, and then it's all set. |
| 150 | + |
| 151 | +## MCP Component |
| 152 | + |
| 153 | +In the previous section, we have learned how to create a MCP server, but the server still has no usable components, like |
| 154 | +MCP resources, prompts, and tools. In this section, we will learn how to create MCP components easily with the support |
| 155 | +of this high-level SDK. Refer to the following sample code, just focus on your core logic, forget about the low-level |
| 156 | +details of native MCP Java SDK. |
| 157 | + |
| 158 | +### Resource |
| 159 | + |
| 160 | +```java |
| 161 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpResource; |
| 162 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpResources; |
| 163 | + |
| 164 | +@McpResources |
| 165 | +public class MyMcpResources { |
| 166 | + |
| 167 | + /** |
| 168 | + * This method defines a MCP resource to expose the OS env variables. |
| 169 | + */ |
| 170 | + @McpResource(uri = "system://env", description = "OS env variables") |
| 171 | + public String getSystemEnv() { |
| 172 | + // Just put your logic code here, forget about the native MCP SDK details. |
| 173 | + return System.getenv().toString(); |
| 174 | + } |
| 175 | + |
| 176 | + // Your other MCP resources here... |
| 177 | +} |
| 178 | +``` |
| 179 | + |
| 180 | +### Prompt |
| 181 | + |
| 182 | +```java |
| 183 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpPrompt; |
| 184 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpPromptParam; |
| 185 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpPrompts; |
| 186 | + |
| 187 | +@McpPrompts |
| 188 | +public class MyMcpPrompts { |
| 189 | + |
| 190 | + /** |
| 191 | + * This method defines a MCP prompt to read a file. |
| 192 | + */ |
| 193 | + @McpPrompt(description = "A simple prompt to read a file") |
| 194 | + public String readFile(@McpPromptParam(name = "path", description = "filepath", required = true) String path) { |
| 195 | + // Just put your logic code here, forget about the native MCP SDK details. |
| 196 | + return String.format("What is the complete contents of the file: %s", path); |
| 197 | + } |
| 198 | + |
| 199 | + // Your other MCP prompts here... |
| 200 | +} |
| 201 | +``` |
| 202 | + |
| 203 | +### Tool |
| 204 | + |
| 205 | +```java |
| 206 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpTool; |
| 207 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpToolParam; |
| 208 | +import com.github.codeboyzhou.mcp.declarative.annotation.McpTools; |
| 209 | + |
| 210 | +@McpTools |
| 211 | +public class MyMcpTools { |
| 212 | + |
| 213 | + /** |
| 214 | + * This method defines a MCP tool to read a file. |
| 215 | + */ |
| 216 | + @McpTool(description = "Read complete file contents with UTF-8 encoding") |
| 217 | + public String readFile(@McpToolParam(name = "path", description = "filepath", required = true) String path) { |
| 218 | + // Just put your logic code here, forget about the native MCP SDK details. |
| 219 | + return Files.readString(Path.of(path)); |
| 220 | + } |
| 221 | + |
| 222 | + // Your other MCP tools here... |
| 223 | +} |
| 224 | +``` |
| 225 | + |
| 226 | +Now it's all set, all you have to do is run your MCP server, and all the resources, prompts, and tools will be registered |
| 227 | +automatically. |
0 commit comments