Skip to content

Commit 3e38bfa

Browse files
codeboyzhoucodeboyzhou
committed
docs(site): Add initial documentation
1 parent c5ee41f commit 3e38bfa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+10170
-0
lines changed

‎docs/docs/getting_started.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
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.0-SNAPSHOT -->
18+
<dependency>
19+
<groupId>io.github.codeboyzhou</groupId>
20+
<artifactId>mcp-declarative-java-sdk</artifactId>
21+
<version>0.6.0-SNAPSHOT</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.

‎docs/docs/index.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
7+
# Welcome to mcp-declarative-java-sdk
8+
9+
`mcp-declarative-java-sdk` is an annotation-driven MCP (Model Context Protocol) Java SDK, which is based on the native
10+
[MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) from official team. It provides an easier way to define
11+
MCP resources, prompts, and tools using Java annotations if you don't want to use the heavyweight Spring AI Framework.
12+
13+
# Why was it born?
14+
15+
MCP helps you build agents and complex workflows on top of LLMs. However, the official Java SDK is harder to use because
16+
its underlying implementation is more focused on the protocol's core layer. Creating your MCP server requires writing more
17+
repetitive low-level code unless you use the Spring AI Framework. But sometimes, we may simply need a lightweight development
18+
solution, that's why this project was born.
19+
20+
# What it can bring?
21+
22+
🚫 No Spring Framework Required.
23+
24+
⚡ Instant MCP Java server in 1 LOC.
25+
26+
🎉 No need to write more SDK low-level code.
27+
28+
👏 Get rid of complex and lengthy JSON schema definitions.
29+
30+
🎯 Just focus on your core logic (resources/prompts/tools).
31+
32+
🔌 Configuration file compatible with the Spring AI Framework.
33+
34+
🌍 Built-in multi-languages support for MCP server (resources/prompts/tools).

‎docs/mkdocs.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
site_name: mcp-declarative-java-sdk documentation
2+
site_url: https://codeboyzhou.github.io/mcp-declarative-java-sdk
3+
theme:
4+
name: material
5+
icon:
6+
repo: fontawesome/brands/github
7+
features:
8+
- navigation.instant
9+
- navigation.tracking
10+
- navigation.tabs
11+
- navigation.expand
12+
- navigation.path
13+
- navigation.top
14+
- navigation.footer
15+
- content.code.copy
16+
- announce.dismiss
17+
- search.suggest
18+
- content.tabs.link
19+
20+
palette:
21+
# Palette toggle for automatic mode
22+
- media: "(prefers-color-scheme)"
23+
toggle:
24+
icon: material/brightness-auto
25+
name: Switch to light mode
26+
27+
# Palette toggle for light mode
28+
- media: "(prefers-color-scheme: light)"
29+
scheme: default
30+
toggle:
31+
icon: material/brightness-7
32+
name: Switch to dark mode
33+
34+
# Palette toggle for dark mode
35+
- media: "(prefers-color-scheme: dark)"
36+
scheme: slate
37+
toggle:
38+
icon: material/brightness-4
39+
name: Switch to system preference
40+
41+
repo_url: https://github.com/codeboyzhou/mcp-declarative-java-sdk
42+
repo_name: mcp-declarative-java-sdk
43+
44+
markdown_extensions:
45+
- attr_list
46+
- admonition
47+
- md_in_html
48+
- pymdownx.snippets
49+
- pymdownx.superfences
50+
- pymdownx.inlinehilite
51+
- pymdownx.highlight:
52+
line_spans: __span
53+
anchor_linenums: true
54+
pygments_lang_class: true
55+
- pymdownx.emoji:
56+
emoji_index: !!python/name:material.extensions.emoji.twemoji
57+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
58+
- pymdownx.tabbed:
59+
alternate_style: true
60+
61+
copyright: © 2025 <a href="https://github.com/codeboyzhou">codeboyzhou</a>
62+
63+
extra:
64+
social:
65+
- icon: fontawesome/brands/github
66+
link: https://github.com/codeboyzhou
67+
68+
nav:
69+
- Overview: index.md
70+
- Getting Started: getting_started.md

‎docs/pyproject.toml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
[project]
2+
name = "mcp-declarative-java-sdk-docs"
3+
version = "0.6.0"
4+
description = "Documentation site for project https://github.com/codeboyzhou/mcp-declarative-java-sdk"
5+
authors = [
6+
{ name = "codeboyzhou", email = "imzhouchen@gmail.com" },
7+
]
8+
requires-python = ">=3.12"
9+
dependencies = [
10+
"mkdocs-material>=9.6.15"
11+
]

0 commit comments

Comments
 (0)