Skip to content
This repository was archived by the owner on Feb 14, 2025. It is now read-only.

Commit b378ab7

Browse files
tzolovtzolov
committed
generate some README
1 parent c248642 commit b378ab7

File tree

2 files changed

+166
-13
lines changed

2 files changed

+166
-13
lines changed

‎mcp/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Model Context Protocol (MCP) Java SDK
2+
3+
A Java implementation of the [Model Context Protocol](https://modelcontextprotocol.io/docs/concepts/architecture) specification, providing both synchronous and asynchronous clients for MCP server interactions.
4+
5+
## Overview
6+
7+
This SDK implements the Model Context Protocol, enabling seamless integration with AI models and tools through a standardized interface. It supports both synchronous and asynchronous communication patterns, making it suitable for various use cases and integration scenarios.
8+
9+
## Features
10+
11+
- Synchronous and Asynchronous client implementations
12+
- Standard MCP operations support:
13+
- Tool discovery and execution
14+
- Resource management
15+
- Message creation
16+
- Server initialization
17+
- Stdio-based server transport
18+
- Reactive programming support using Project Reactor
19+
20+
## Installation
21+
22+
Add the following dependency to your Maven project:
23+
24+
```xml
25+
<dependency>
26+
<groupId>spring.ai.experimental</groupId>
27+
<artifactId>mcp</artifactId>
28+
<version>1.0.0</version>
29+
</dependency>
30+
```
31+
32+
## Usage
33+
34+
### Async Client Example
35+
36+
```java
37+
// Create server parameters
38+
ServerParameters params = ServerParameters.builder("npx")
39+
.args("-y", "@modelcontextprotocol/server-everything", "dir")
40+
.build();
41+
42+
// Initialize the async client
43+
Duration timeout = Duration.ofSeconds(10);
44+
McpAsyncClient client = McpClient.async(
45+
new StdioServerTransport(params),
46+
timeout,
47+
new ObjectMapper()
48+
);
49+
50+
// Initialize the connection
51+
client.initialize();
52+
53+
// List available tools
54+
client.listTools(null).subscribe(result -> {
55+
List<Tool> tools = result.tools();
56+
// Process tools...
57+
});
58+
59+
// Call a tool
60+
CallToolRequest request = new CallToolRequest(
61+
"echo",
62+
Map.of("message", "Hello MCP!")
63+
);
64+
client.callTool(request).subscribe(result -> {
65+
// Handle tool execution result...
66+
});
67+
68+
// Cleanup
69+
client.close();
70+
```
71+
72+
### Sync Client Example
73+
74+
```java
75+
// Create and initialize sync client
76+
McpClient syncClient = McpClient.sync(
77+
new StdioServerTransport(params),
78+
timeout,
79+
new ObjectMapper()
80+
);
81+
82+
// Initialize connection
83+
syncClient.initialize();
84+
85+
// List tools synchronously
86+
ListToolsResult tools = syncClient.listTools(null);
87+
88+
// Call tool synchronously
89+
CallToolResult result = syncClient.callTool("echo", Map.of("message", "Hello!"));
90+
91+
// Cleanup
92+
syncClient.close();
93+
```
94+
95+
## Architecture
96+
97+
The SDK follows a layered architecture:
98+
99+
### Core Components
100+
101+
- **McpClient**: Main interface defining the synchronous operations
102+
- **McpAsyncClient**: Async implementation using Project Reactor
103+
- **McpSyncClient**: Synchronous wrapper around the async client
104+
- **McpAsyncTransport**: Transport layer interface
105+
- **DefaultMcpTransport**: Base transport implementation
106+
- **StdioServerTransport**: Stdio-based server communication
107+
108+
### Key Interactions
109+
110+
1. Client initialization
111+
- Transport setup
112+
- Server connection establishment
113+
- Protocol handshake
114+
115+
2. Message Flow
116+
- Request creation
117+
- Transport layer handling
118+
- Response processing
119+
120+
3. Tool Execution
121+
- Tool discovery
122+
- Parameter validation
123+
- Execution handling
124+
- Result processing
125+
126+
## Error Handling
127+
128+
The SDK provides comprehensive error handling:
129+
130+
- Transport-level errors
131+
- Protocol violations
132+
- Tool execution failures
133+
- Timeout handling
134+
- Resource management errors
135+
136+
## Contributing
137+
138+
Contributions are welcome! Please feel free to submit a Pull Request.
139+
140+
## License
141+
142+
Copyright 2024 - 2024 the original author or authors.
143+
144+
Licensed under the Apache License, Version 2.0 (the "License");
145+
you may not use this file except in compliance with the License.
146+
You may obtain a copy of the License at
147+
148+
https://www.apache.org/licenses/LICENSE-2.0
149+
150+
Unless required by applicable law or agreed to in writing, software
151+
distributed under the License is distributed on an "AS IS" BASIS,
152+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
153+
See the License for the specific language governing permissions and
154+
limitations under the License.

‎spring/src/main/java/spring/ai/mcp/McpApplication.java‎

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,16 @@ public CommandLineRunner test(ChatClient.Builder chatClientBuilder, List<McpFunc
2828
return args -> {
2929

3030
var chatClient = chatClientBuilder.defaultFunctions(functionCallbacks.toArray(new McpFunctionCallback[0]))
31-
.build();
31+
.build();
3232

3333
var response = chatClient.prompt("What is the content of the test.txt file?").call().content();
3434

3535
System.out.println(response);
3636

3737
response = chatClient.prompt(
3838
"Please summarize the content of the test.txt file, covert the result in markdown format and store it into test.md")
39-
.call()
40-
.content();
39+
.call()
40+
.content();
4141
System.out.println("Summary:" + response);
4242
};
4343
}
@@ -46,22 +46,22 @@ public CommandLineRunner test(ChatClient.Builder chatClientBuilder, List<McpFunc
4646
public List<McpFunctionCallback> functionCallbacks(McpSyncClient mcpClient) {
4747

4848
return mcpClient.listTools(null)
49-
.tools()
50-
.stream()
51-
.map(tool -> new McpFunctionCallback(mcpClient, tool))
52-
.toList();
49+
.tools()
50+
.stream()
51+
.map(tool -> new McpFunctionCallback(mcpClient, tool))
52+
.toList();
5353
}
5454

5555
@Bean(destroyMethod = "close")
5656
public McpSyncClient clientSession() {
5757

5858
var stdioParams = ServerParameters.builder("npx")
59-
.args("-y", "@modelcontextprotocol/server-filesystem",
60-
"/Users/christiantzolov/Dev/projects/demo/mcp-server/dir")
61-
.build();
59+
.args("-y", "@modelcontextprotocol/server-filesystem",
60+
"/Users/christiantzolov/Dev/projects/demo/mcp-server/dir")
61+
.build();
6262

6363
McpSyncClient mcpClient = null;
64-
try {
64+
try {
6565
mcpClient = McpClient.sync(new StdioServerTransport(stdioParams),
6666
Duration.ofSeconds(10), new ObjectMapper());
6767

@@ -70,8 +70,7 @@ public McpSyncClient clientSession() {
7070
System.out.println("MCP Initialized: " + init);
7171

7272
return mcpClient;
73-
}
74-
catch (Exception e) {
73+
} catch (Exception e) {
7574
throw new RuntimeException(e);
7675
}
7776
}

0 commit comments

Comments
 (0)