|
| 1 | +# AI & MCP Integration with tinystruct |
| 2 | + |
| 3 | +The Model Context Protocol (MCP) module for tinystruct provides comprehensive integration for AI model interactions, tool discovery, resource management, and prompt handling. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The MCP module enables tinystruct applications to act as both MCP servers and clients. It supports the standard MCP specification including JSON-RPC communication, Server-Sent Events (SSE), and a unified resource model. |
| 8 | + |
| 9 | +## Key Concepts |
| 10 | + |
| 11 | +- **MCPApplication**: The base class for applications that want to handle MCP requests. |
| 12 | +- **MCPServer**: A complete server implementation that manages tools, resources, and prompts. |
| 13 | +- **MCPClient**: A client used to connect to and interact with MCP servers. |
| 14 | +- **MCPTool**: Executable functions that can be discovered and called by AI models. |
| 15 | +- **MCPResource**: Data sources that can be read by AI models. |
| 16 | +- **MCPPrompt**: Template-based text generation for AI prompts. |
| 17 | + |
| 18 | +## Implementation |
| 19 | + |
| 20 | +### Creating an MCP Server |
| 21 | + |
| 22 | +To create an MCP server, extend the `MCPServer` class and register your tools, resources, or prompts in the `init()` method: |
| 23 | + |
| 24 | +```java |
| 25 | +import org.tinystruct.mcp.MCPServer; |
| 26 | +import org.tinystruct.mcp.tools.CalculatorTool; |
| 27 | + |
| 28 | +public class MyMCPServer extends MCPServer { |
| 29 | + |
| 30 | + @Override |
| 31 | + public void init() { |
| 32 | + super.init(); |
| 33 | + |
| 34 | + // Register built-in tools |
| 35 | + CalculatorTool calculator = new CalculatorTool(); |
| 36 | + this.registerTool(calculator); |
| 37 | + |
| 38 | + // Register custom tools |
| 39 | + this.registerTool(new MyCustomTool()); |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +### Creating a Custom Tool |
| 45 | + |
| 46 | +Custom tools can be created by extending `MCPTool` and using the `@Action` annotation to define executable methods: |
| 47 | + |
| 48 | +```java |
| 49 | +import org.tinystruct.mcp.MCPTool; |
| 50 | +import org.tinystruct.system.annotation.Action; |
| 51 | +import org.tinystruct.system.annotation.Argument; |
| 52 | + |
| 53 | +public class MyCustomTool extends MCPTool { |
| 54 | + |
| 55 | + public MyCustomTool() { |
| 56 | + super("my-tool", "A custom tool for data processing", null, null, true); |
| 57 | + } |
| 58 | + |
| 59 | + @Action(value = "my-tool/process", |
| 60 | + description = "Process input data", |
| 61 | + arguments = { |
| 62 | + @Argument(key = "input", description = "The data to process", type = "string") |
| 63 | + }) |
| 64 | + public String processData(String input) { |
| 65 | + return "Processed: " + input.toUpperCase(); |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +### Using the MCP Client |
| 71 | + |
| 72 | +You can connect to an MCP server programmatically using the `MCPClient`: |
| 73 | + |
| 74 | +```java |
| 75 | +import org.tinystruct.mcp.MCPClient; |
| 76 | +import java.util.HashMap; |
| 77 | +import java.util.Map; |
| 78 | + |
| 79 | +public class ClientExample { |
| 80 | + public static void main(String[] args) { |
| 81 | + MCPClient client = new MCPClient("http://localhost:8080", "your-auth-token"); |
| 82 | + |
| 83 | + try { |
| 84 | + client.connect(); |
| 85 | + |
| 86 | + // Execute a tool |
| 87 | + Map<String, Object> params = new HashMap<>(); |
| 88 | + params.put("a", 10); |
| 89 | + params.put("b", 20); |
| 90 | + Object result = client.executeResource("calculator/add", params); |
| 91 | + |
| 92 | + System.out.println("Result: " + result); |
| 93 | + } catch (Exception e) { |
| 94 | + e.printStackTrace(); |
| 95 | + } finally { |
| 96 | + client.disconnect(); |
| 97 | + } |
| 98 | + } |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +## Running the Server |
| 103 | + |
| 104 | +Start your MCP server using the tinystruct dispatcher: |
| 105 | + |
| 106 | +```bash |
| 107 | +bin/dispatcher start --import com.example.MyMCPServer |
| 108 | +``` |
| 109 | + |
| 110 | +## CLI Interaction |
| 111 | + |
| 112 | +The tinystruct CLI also provides commands to interact with MCP servers: |
| 113 | + |
| 114 | +```bash |
| 115 | +# Connect to a server |
| 116 | +bin/dispatcher mcp/connect --url http://localhost:8080 |
| 117 | + |
| 118 | +# List available tools |
| 119 | +bin/dispatcher mcp/list/tools |
| 120 | + |
| 121 | +# Call a tool |
| 122 | +bin/dispatcher mcp/call --name calculator/add --arguments "a:10,b:20" |
| 123 | + |
| 124 | +# Disconnect |
| 125 | +bin/dispatcher mcp/disconnect |
| 126 | +``` |
| 127 | + |
| 128 | +## Real-time Updates with SSE |
| 129 | + |
| 130 | +The MCP module uses Server-Sent Events (SSE) for real-time notifications. When a tool or resource is updated on the server, connected clients receive immediate notifications via the `MCPPushManager`. |
0 commit comments