435 lines
9.9 KiB
Markdown
435 lines
9.9 KiB
Markdown
# LangChain4j MCP Server API Reference
|
|
|
|
This document provides comprehensive API documentation for implementing MCP servers with LangChain4j.
|
|
|
|
## Core MCP Classes
|
|
|
|
### McpClient Interface
|
|
|
|
Primary interface for communicating with MCP servers.
|
|
|
|
**Key Methods:**
|
|
```java
|
|
// Tool Management
|
|
List<ToolSpecification> listTools();
|
|
String executeTool(ToolExecutionRequest request);
|
|
|
|
// Resource Management
|
|
List<McpResource> listResources();
|
|
String getResource(String uri);
|
|
List<McpResourceTemplate> listResourceTemplates();
|
|
|
|
// Prompt Management
|
|
List<Prompt> listPrompts();
|
|
String getPrompt(String name);
|
|
|
|
// Lifecycle Management
|
|
void close();
|
|
```
|
|
|
|
### DefaultMcpClient.Builder
|
|
|
|
Builder for creating MCP clients with configuration options.
|
|
|
|
**Configuration Methods:**
|
|
```java
|
|
McpClient client = new DefaultMcpClient.Builder()
|
|
.key("unique-client-id") // Unique identifier
|
|
.transport(transport) // Transport mechanism
|
|
.cacheToolList(true) // Enable tool caching
|
|
.logMessageHandler(handler) // Custom logging
|
|
.build();
|
|
```
|
|
|
|
### McpToolProvider.Builder
|
|
|
|
Builder for creating tool providers that bridge MCP servers to LangChain4j AI services.
|
|
|
|
**Configuration Methods:**
|
|
```java
|
|
McpToolProvider provider = McpToolProvider.builder()
|
|
.mcpClients(client1, client2) // Add MCP clients
|
|
.failIfOneServerFails(false) // Configure failure handling
|
|
.filterToolNames("tool1", "tool2") // Filter by names
|
|
.filter((client, tool) -> logic) // Custom filtering
|
|
.build();
|
|
```
|
|
|
|
## Transport Configuration
|
|
|
|
### StdioMcpTransport.Builder
|
|
|
|
For local process communication with npm packages or Docker containers.
|
|
|
|
```java
|
|
McpTransport transport = new StdioMcpTransport.Builder()
|
|
.command(List.of("npm", "exec", "@modelcontextprotocol/server-everything@0.6.2"))
|
|
.logEvents(true)
|
|
.build();
|
|
```
|
|
|
|
### HttpMcpTransport.Builder
|
|
|
|
For HTTP-based communication with remote MCP servers.
|
|
|
|
```java
|
|
McpTransport transport = new HttpMcpTransport.Builder()
|
|
.sseUrl("http://localhost:3001/sse")
|
|
.logRequests(true)
|
|
.logResponses(true)
|
|
.build();
|
|
```
|
|
|
|
### StreamableHttpMcpTransport.Builder
|
|
|
|
For streamable HTTP transport with enhanced performance.
|
|
|
|
```java
|
|
McpTransport transport = new StreamableHttpMcpTransport.Builder()
|
|
.url("http://localhost:3001/mcp")
|
|
.logRequests(true)
|
|
.logResponses(true)
|
|
.build();
|
|
```
|
|
|
|
## AI Service Integration
|
|
|
|
### AiServices.builder()
|
|
|
|
Create AI services integrated with MCP tool providers.
|
|
|
|
**Integration Methods:**
|
|
```java
|
|
AIAssistant assistant = AiServices.builder(AIAssistant.class)
|
|
.chatModel(chatModel)
|
|
.toolProvider(toolProvider)
|
|
.chatMemoryProvider(memoryProvider)
|
|
.build();
|
|
```
|
|
|
|
## Error Handling and Management
|
|
|
|
### Exception Handling
|
|
|
|
Handle MCP-specific exceptions gracefully:
|
|
|
|
```java
|
|
try {
|
|
String result = mcpClient.executeTool(request);
|
|
} catch (McpException e) {
|
|
log.error("MCP execution failed: {}", e.getMessage());
|
|
// Implement fallback logic
|
|
}
|
|
```
|
|
|
|
### Retry and Resilience
|
|
|
|
Implement retry logic for unreliable MCP servers:
|
|
|
|
```java
|
|
RetryTemplate retryTemplate = RetryTemplate.builder()
|
|
.maxAttempts(3)
|
|
.exponentialBackoff(1000, 2, 10000)
|
|
.build();
|
|
|
|
String result = retryTemplate.execute(context ->
|
|
mcpClient.executeTool(request));
|
|
```
|
|
|
|
## Configuration Properties
|
|
|
|
### Application Configuration
|
|
|
|
```yaml
|
|
mcp:
|
|
fail-if-one-server-fails: false
|
|
cache-tools: true
|
|
servers:
|
|
github:
|
|
type: docker
|
|
command: ["/usr/local/bin/docker", "run", "-e", "GITHUB_TOKEN", "-i", "mcp/github"]
|
|
log-events: true
|
|
database:
|
|
type: stdio
|
|
command: ["/usr/bin/npm", "exec", "@modelcontextprotocol/server-sqlite"]
|
|
log-events: false
|
|
```
|
|
|
|
### Spring Boot Configuration
|
|
|
|
```java
|
|
@Configuration
|
|
@EnableConfigurationProperties(McpProperties.class)
|
|
public class McpConfiguration {
|
|
|
|
@Bean
|
|
public List<McpClient> mcpClients(McpProperties properties) {
|
|
return properties.getServers().entrySet().stream()
|
|
.map(entry -> createMcpClient(entry.getKey(), entry.getValue()))
|
|
.collect(Collectors.toList());
|
|
}
|
|
|
|
@Bean
|
|
public McpToolProvider mcpToolProvider(List<McpClient> mcpClients, McpProperties properties) {
|
|
return McpToolProvider.builder()
|
|
.mcpClients(mcpClients)
|
|
.failIfOneServerFails(properties.isFailIfOneServerFails())
|
|
.build();
|
|
}
|
|
}
|
|
```
|
|
|
|
## Tool Specification and Execution
|
|
|
|
### Tool Specification
|
|
|
|
Define tools with proper schema:
|
|
|
|
```java
|
|
ToolSpecification toolSpec = ToolSpecification.builder()
|
|
.name("database_query")
|
|
.description("Execute SQL queries against the database")
|
|
.inputSchema(Map.of(
|
|
"type", "object",
|
|
"properties", Map.of(
|
|
"sql", Map.of(
|
|
"type", "string",
|
|
"description", "SQL query to execute"
|
|
)
|
|
)
|
|
))
|
|
.build();
|
|
```
|
|
|
|
### Tool Execution
|
|
|
|
Execute tools with structured requests:
|
|
|
|
```java
|
|
ToolExecutionRequest request = ToolExecutionRequest.builder()
|
|
.name("database_query")
|
|
.arguments("{\"sql\": \"SELECT * FROM users LIMIT 10\"}")
|
|
.build();
|
|
|
|
String result = mcpClient.executeTool(request);
|
|
```
|
|
|
|
## Resource Handling
|
|
|
|
### Resource Access
|
|
|
|
Access and utilize MCP resources:
|
|
|
|
```java
|
|
// List available resources
|
|
List<McpResource> resources = mcpClient.listResources();
|
|
|
|
// Get specific resource content
|
|
String content = mcpClient.getResource("resource://schema/database");
|
|
|
|
// Work with resource templates
|
|
List<McpResourceTemplate> templates = mcpClient.listResourceTemplates();
|
|
```
|
|
|
|
### Resource as Tools
|
|
|
|
Convert MCP resources to tools automatically:
|
|
|
|
```java
|
|
DefaultMcpResourcesAsToolsPresenter presenter =
|
|
new DefaultMcpResourcesAsToolsPresenter();
|
|
mcpToolProvider.provideTools(presenter);
|
|
|
|
// Adds 'list_resources' and 'get_resource' tools automatically
|
|
```
|
|
|
|
## Security and Filtering
|
|
|
|
### Tool Filtering
|
|
|
|
Implement security-conscious tool filtering:
|
|
|
|
```java
|
|
McpToolProvider secureProvider = McpToolProvider.builder()
|
|
.mcpClients(mcpClient)
|
|
.filter((client, tool) -> {
|
|
// Check user permissions
|
|
if (tool.name().startsWith("admin_") && !currentUser.hasRole("ADMIN")) {
|
|
return false;
|
|
}
|
|
return true;
|
|
})
|
|
.build();
|
|
```
|
|
|
|
### Resource Security
|
|
|
|
Apply security controls to resource access:
|
|
|
|
```java
|
|
public boolean canAccessResource(String uri, User user) {
|
|
if (uri.contains("sensitive/") && !user.hasRole("ADMIN")) {
|
|
return false;
|
|
}
|
|
return true;
|
|
}
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### Caching Strategy
|
|
|
|
Implement intelligent caching:
|
|
|
|
```java
|
|
// Enable tool caching for performance
|
|
McpClient client = new DefaultMcpClient.Builder()
|
|
.transport(transport)
|
|
.cacheToolList(true)
|
|
.build();
|
|
|
|
// Periodic cache refresh
|
|
@Scheduled(fixedRate = 300000) // 5 minutes
|
|
public void refreshToolCache() {
|
|
mcpClients.forEach(client -> {
|
|
try {
|
|
client.invalidateCache();
|
|
client.listTools(); // Preload cache
|
|
} catch (Exception e) {
|
|
log.warn("Cache refresh failed: {}", e.getMessage());
|
|
}
|
|
});
|
|
}
|
|
```
|
|
|
|
### Connection Pooling
|
|
|
|
Optimize connection management:
|
|
|
|
```java
|
|
@Bean
|
|
public Executor mcpExecutor() {
|
|
return Executors.newFixedThreadPool(10); // Dedicated thread pool
|
|
}
|
|
```
|
|
|
|
## Testing and Validation
|
|
|
|
### Mock Configuration
|
|
|
|
Setup for testing:
|
|
|
|
```java
|
|
@TestConfiguration
|
|
public class MockMcpConfiguration {
|
|
|
|
@Bean
|
|
@Primary
|
|
public McpClient mockMcpClient() {
|
|
McpClient mock = Mockito.mock(McpClient.class);
|
|
|
|
when(mock.listTools()).thenReturn(List.of(
|
|
ToolSpecification.builder()
|
|
.name("test_tool")
|
|
.description("Test tool")
|
|
.build()
|
|
));
|
|
|
|
when(mock.executeTool(any(ToolExecutionRequest.class)))
|
|
.thenReturn("Mock result");
|
|
|
|
return mock;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Integration Testing
|
|
|
|
Test MCP integrations:
|
|
|
|
```java
|
|
@SpringBootTest
|
|
class McpIntegrationTest {
|
|
|
|
@Autowired
|
|
private AIAssistant assistant;
|
|
|
|
@Test
|
|
void shouldExecuteToolsSuccessfully() {
|
|
String response = assistant.chat("Execute test tool");
|
|
|
|
assertThat(response).contains("Mock result");
|
|
}
|
|
}
|
|
```
|
|
|
|
## Monitoring and Observability
|
|
|
|
### Health Checks
|
|
|
|
Monitor MCP server health:
|
|
|
|
```java
|
|
@Component
|
|
public class McpHealthChecker {
|
|
|
|
@EventListener
|
|
@Async
|
|
public void checkHealth() {
|
|
mcpClients.forEach(client -> {
|
|
try {
|
|
client.listTools(); // Simple health check
|
|
healthRegistry.markHealthy(client.key());
|
|
} catch (Exception e) {
|
|
healthRegistry.markUnhealthy(client.key(), e.getMessage());
|
|
}
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
### Metrics Collection
|
|
|
|
Collect execution metrics:
|
|
|
|
```java
|
|
@Bean
|
|
public Counter toolExecutionCounter(MeterRegistry meterRegistry) {
|
|
return meterRegistry.counter("mcp.tool.execution", "type", "total");
|
|
}
|
|
|
|
@Bean
|
|
public Timer toolExecutionTimer(MeterRegistry meterRegistry) {
|
|
return meterRegistry.timer("mcp.tool.execution.time");
|
|
}
|
|
```
|
|
|
|
## Migration and Versioning
|
|
|
|
### Version Compatibility
|
|
|
|
Handle version compatibility:
|
|
|
|
```java
|
|
public class VersionedMcpClient {
|
|
|
|
public boolean isCompatible(String serverVersion) {
|
|
return semanticVersionChecker.isCompatible(
|
|
REQUIRED_MCP_VERSION, serverVersion);
|
|
}
|
|
|
|
public McpClient createClient(ServerConfig config) {
|
|
if (!isCompatible(config.getVersion())) {
|
|
throw new IncompatibleVersionException(
|
|
"Server version " + config.getVersion() +
|
|
" is not compatible with required " + REQUIRED_MCP_VERSION);
|
|
}
|
|
|
|
return new DefaultMcpClient.Builder()
|
|
.transport(createTransport(config))
|
|
.build();
|
|
}
|
|
}
|
|
```
|
|
|
|
This API reference provides the complete foundation for implementing MCP servers and clients with LangChain4j, covering all major aspects from basic setup to advanced enterprise patterns. |