Skip to content

Commit 0185f03

Browse files
codeboyzhoucodeboyzhou
committed
feat(docs): add initial documentation setup for mcp-annotated-java-sdk
- Add mkdocs configuration with material theme - Create getting started guide and core components documentation - Set up GitHub Pages deployment workflow - Add project metadata and dependencies in pyproject.toml - Update LICENSE year and add .gitignore
1 parent 0af7e0e commit 0185f03

File tree

9 files changed

+1006
-1
lines changed

9 files changed

+1006
-1
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Deploy docs to GitHub Pages
2+
on:
3+
push:
4+
branches:
5+
- main
6+
7+
permissions:
8+
contents: write
9+
10+
jobs:
11+
deploy:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- name: Configure Git Credentials
16+
run: |
17+
git config user.name github-actions[bot]
18+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
19+
- uses: actions/setup-python@v5
20+
with:
21+
python-version: 3.x
22+
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
23+
- uses: actions/cache@v4
24+
with:
25+
key: mkdocs-material-${{ env.cache_id }}
26+
path: .cache
27+
restore-keys: |
28+
mkdocs-material-
29+
- run: pip install mkdocs-material
30+
- run: mkdocs gh-deploy --force --config-file mkdocs.yml

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Python virtual environment
2+
.venv/
3+
4+
# PyCharm project files
5+
.idea/

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2026 thought → code
3+
Copyright (c) 2025 thought → code
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎docs/components.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
hide:
3+
- navigation
4+
- toc
5+
---
6+
7+
# Core Components
8+
9+
MCP (Model Context Protocol) defines three core component types, and this SDK simplifies the creation process of these components through annotations.
10+
11+
## Resources
12+
13+
Resource components are used to expose data to LLMs, similar to GET requests in Web APIs.
14+
15+
### Basic Usage
16+
17+
```java
18+
import com.github.thought2code.mcp.annotated.annotation.McpResource;
19+
20+
public class MyResources {
21+
@McpResource(uri = "system://info", description = "System information")
22+
public Map<String, String> getSystemInfo() {
23+
Map<String, String> info = new HashMap<>();
24+
info.put("os", System.getProperty("os.name"));
25+
info.put("java", System.getProperty("java.version"));
26+
info.put("cores", String.valueOf(Runtime.getRuntime().availableProcessors()));
27+
return info;
28+
}
29+
}
30+
```
31+
32+
### Annotation Explanation
33+
34+
- `@McpResource`: Marks a method as an MCP resource
35+
- `uri`: Unique identifier of the resource, following URI format
36+
- `description`: Resource description for LLM to understand the resource's purpose
37+
38+
## Tools
39+
40+
Tool components are used to execute operations or calculations, similar to POST requests in Web APIs.
41+
42+
### Basic Usage
43+
44+
```java
45+
import com.github.thought2code.mcp.annotated.annotation.McpTool;
46+
import com.github.thought2code.mcp.annotated.annotation.McpToolParam;
47+
48+
public class MyTools {
49+
@McpTool(description = "Calculate the sum of two numbers")
50+
public int add(
51+
@McpToolParam(name = "a", description = "First number", required = true) int a,
52+
@McpToolParam(name = "b", description = "Second number", required = true) int b
53+
) {
54+
return a + b;
55+
}
56+
57+
@McpTool(description = "Read complete file contents with UTF-8 encoding")
58+
public String readFile(@McpToolParam(name = "path", description = "File path", required = true) String path) {
59+
try {
60+
return Files.readString(Path.of(path));
61+
} catch (IOException e) {
62+
return "Error reading file: " + e.getMessage();
63+
}
64+
}
65+
}
66+
```
67+
68+
### Annotation Explanation
69+
70+
- `@McpTool`: Marks a method as an MCP tool
71+
- `@McpToolParam`: Marks method parameters as tool parameters
72+
- `name`: Parameter name
73+
- `description`: Parameter description
74+
- `required`: Whether the parameter is required
75+
76+
## Prompts
77+
78+
Prompt components are used to define reusable prompt templates.
79+
80+
### Basic Usage
81+
82+
```java
83+
import com.github.thought2code.mcp.annotated.annotation.McpPrompt;
84+
import com.github.thought2code.mcp.annotated.annotation.McpPromptParam;
85+
86+
public class MyPrompts {
87+
@McpPrompt(description = "Generate code for a given task")
88+
public String generateCode(
89+
@McpPromptParam(name = "language", description = "Programming language", required = true) String language,
90+
@McpPromptParam(name = "task", description = "Task description", required = true) String task
91+
) {
92+
return String.format("Write %s code to: %s", language, task);
93+
}
94+
95+
@McpPrompt(description = "Format text as specified style")
96+
public String formatText(
97+
@McpPromptParam(name = "text", description = "Text to format", required = true) String text,
98+
@McpPromptParam(name = "style", description = "Format style (e.g., formal, casual, technical)", required = true) String style
99+
) {
100+
return String.format("Rewrite the following text in a %s style: %s", style, text);
101+
}
102+
}
103+
```
104+
105+
### Annotation Explanation
106+
107+
- `@McpPrompt`: Marks a method as an MCP prompt
108+
- `@McpPromptParam`: Marks method parameters as prompt parameters
109+
- `name`: Parameter name
110+
- `description`: Parameter description
111+
- `required`: Whether the parameter is required
112+
113+
## Multilingual Support
114+
115+
This SDK has built-in multilingual support, which can be enabled through the `@McpI18nEnabled` annotation.
116+
117+
### Configure Multilingual
118+
119+
```java
120+
@McpServerApplication
121+
@McpI18nEnabled(resourceBundleBaseName = "messages")
122+
public class I18nMcpServer {
123+
public static void main(String[] args) {
124+
McpServers.run(I18nMcpServer.class, args)
125+
.startStdioServer(McpServerInfo.builder()
126+
.name("i18n-server")
127+
.version("1.0.0")
128+
.build());
129+
}
130+
}
131+
```
132+
133+
### Internationalization Resource Files
134+
135+
Create `messages.properties` file:
136+
137+
```properties
138+
# messages.properties
139+
tool.add.description=Calculate the sum of two numbers
140+
tool.add.param.a.description=First number
141+
tool.add.param.b.description=Second number
142+
resource.system.info.description=System information
143+
prompt.generate.code.description=Generate code for a given task
144+
prompt.generate.code.param.language.description=Programming language
145+
prompt.generate.code.param.task.description=Task description
146+
```
147+
148+
Create `messages_zh_CN.properties` file:
149+
150+
```properties
151+
# messages_zh_CN.properties
152+
tool.add.description=Calculate the sum of two numbers
153+
tool.add.param.a.description=First number
154+
tool.add.param.b.description=Second number
155+
resource.system.info.description=System information
156+
prompt.generate.code.description=Generate code for a given task
157+
prompt.generate.code.param.language.description=Programming language
158+
prompt.generate.code.param.task.description=Task description
159+
```
160+
161+
Using internationalized messages in components:
162+
163+
```java
164+
@McpTool(description = "tool.add.description")
165+
public int add(
166+
@McpToolParam(name = "a", description = "tool.add.param.a.description") int a,
167+
@McpToolParam(name = "b", description = "tool.add.param.b.description") int b
168+
) {
169+
return a + b;
170+
}
171+
```
172+
173+
## Automatic Registration
174+
175+
After defining MCP components, they will be automatically registered to the server. You just need to ensure that the component classes are in the package scanning path of the server application.
176+
177+
If you need to specify a specific package path, you can use the following methods:
178+
179+
```java
180+
@McpServerApplication(basePackageClass = MyMcpServer.class)
181+
// or
182+
@McpServerApplication(basePackage = "com.example.mcp.components")
183+
```
184+
185+
If no package path is specified, the package containing the main method will be scanned.

‎docs/getting-started.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
hide:
3+
- navigation
4+
---
5+
6+
# Getting Started Guide
7+
8+
This guide will help you build your first MCP server in 5 minutes.
9+
10+
## Requirements
11+
12+
- **Java 17 or later** (restricted by official MCP Java SDK)
13+
- **Maven 3.6+** or **Gradle 7+**
14+
15+
## Installation
16+
17+
### Maven Dependency
18+
19+
```xml
20+
<dependency>
21+
<groupId>io.github.thought2code</groupId>
22+
<artifactId>mcp-annotated-java-sdk</artifactId>
23+
<version>0.10.0</version>
24+
</dependency>
25+
```
26+
27+
### Gradle Dependency
28+
29+
```gradle
30+
implementation 'io.github.thought2code:mcp-annotated-java-sdk:0.10.0'
31+
```
32+
33+
## 5-Minute Tutorial
34+
35+
### Step 1: Create MCP Server Main Class
36+
37+
```java
38+
@McpServerApplication
39+
// If your MCP server components don't need multilingual support, you can remove this annotation
40+
@McpI18nEnabled(resourceBundleBaseName = "i18n/mcp_server_components_info")
41+
public class MyFirstMcpServer {
42+
public static void main(String[] args) {
43+
McpServers.run(MyFirstMcpServer.class, args)
44+
.startStdioServer(McpServerInfo.builder()
45+
.name("my-first-mcp-server")
46+
.version("1.0.0")
47+
.build());
48+
}
49+
}
50+
```
51+
52+
### Step 2: Define MCP Resources (Optional)
53+
54+
```java
55+
public class MyResources {
56+
@McpResource(uri = "system://info", description = "System information")
57+
public Map<String, String> getSystemInfo() {
58+
Map<String, String> info = new HashMap<>();
59+
info.put("os", System.getProperty("os.name"));
60+
info.put("java", System.getProperty("java.version"));
61+
info.put("cores", String.valueOf(Runtime.getRuntime().availableProcessors()));
62+
return info;
63+
}
64+
}
65+
```
66+
67+
### Step 3: Define MCP Tools
68+
69+
```java
70+
public class MyTools {
71+
@McpTool(description = "Calculate the sum of two numbers")
72+
public int add(
73+
@McpToolParam(name = "a", description = "First number", required = true) int a,
74+
@McpToolParam(name = "b", description = "Second number", required = true) int b
75+
) {
76+
return a + b;
77+
}
78+
}
79+
```
80+
81+
### Step 4: Define MCP Prompts (Optional)
82+
83+
```java
84+
public class MyPrompts {
85+
@McpPrompt(description = "Generate code for a given task")
86+
public String generateCode(
87+
@McpPromptParam(name = "language", description = "Programming language", required = true) String language,
88+
@McpPromptParam(name = "task", description = "Task description", required = true) String task
89+
) {
90+
return String.format("Write %s code to: %s", language, task);
91+
}
92+
}
93+
```
94+
95+
### Step 5: Run the Server
96+
97+
```bash
98+
# Compile and run
99+
mvn clean package
100+
java -jar target/your-app.jar
101+
```
102+
103+
## Server Modes
104+
105+
This SDK supports three MCP server modes:
106+
107+
### 1. STDIO Mode (Default)
108+
Based on standard input/output communication, suitable for CLI tools.
109+
110+
```java
111+
// Start STDIO server
112+
McpServers.run(MyMcpServer.class, args).startStdioServer(serverInfo);
113+
```
114+
115+
### 2. SSE (Server-Sent Events) Mode
116+
HTTP-based real-time communication (deprecated).
117+
118+
### 3. Streamable HTTP Mode
119+
HTTP streaming for web applications.
120+
121+
```java
122+
// Start Streamable HTTP server
123+
McpServers.run(MyMcpServer.class, args).startStreamableServer(serverInfo);
124+
```
125+
126+
## Project Structure
127+
128+
The typical project structure is as follows:
129+
130+
```
131+
your-mcp-project/
132+
├── pom.xml
133+
├── src/
134+
│ ├── main/
135+
│ │ ├── java/
136+
│ │ │ └── com/
137+
│ │ │ └── example/
138+
│ │ │ ├── MyMcpServer.java # Main entry point
139+
│ │ │ ├── components/
140+
│ │ │ │ ├── MyResources.java # MCP Resources
141+
│ │ │ │ ├── MyTools.java # MCP Tools
142+
│ │ │ │ └── MyPrompts.java # MCP Prompts
143+
│ │ │ └── service/
144+
│ │ │ └── BusinessLogic.java # Business logic
145+
│ │ └── resources/
146+
│ │ ├── mcp-server.yml # MCP configuration
147+
│ │ └── messages.properties # Internationalization messages
148+
└── target/
149+
└── your-app.jar # Executable JAR
150+
```
151+
152+
## Next Steps
153+
154+
- Want to learn more about MCP components? Check [Core Components](./components.md)

0 commit comments

Comments
 (0)