From 21d2278b0b41953a30a7ae3bc91a116c45f0a4cc Mon Sep 17 00:00:00 2001 From: "@James" Date: Sun, 26 Apr 2026 23:51:17 +0800 Subject: [PATCH] Update the docs --- en/README.md | 33 ++++++++--- en/cli-applications.md | 12 ++++ en/getting-started.md | 12 +++- en/mcp-integration.md | 130 +++++++++++++++++++++++++++++++++++++++++ en/web-applications.md | 48 ++++++++++++++- index.html | 8 +-- zh/README.md | 33 +++++++---- zh/cli-applications.md | 12 ++++ zh/getting-started.md | 11 +++- zh/mcp-integration.md | 130 +++++++++++++++++++++++++++++++++++++++++ zh/web-applications.md | 48 ++++++++++++++- 11 files changed, 447 insertions(+), 30 deletions(-) create mode 100644 en/mcp-integration.md create mode 100644 zh/mcp-integration.md diff --git a/en/README.md b/en/README.md index 8192c25..a6f64e4 100644 --- a/en/README.md +++ b/en/README.md @@ -9,13 +9,14 @@ tinystruct is a simple yet powerful framework for Java development. It embraces ## Key Features -- **Lightweight Architecture**: Minimal overhead with maximum flexibility -- **Dual-Mode Support**: Build both web applications and CLI tools -- **Simple Configuration**: Easy to set up and customize -- **High Performance**: Optimized for efficient execution -- **Database Integration**: Built-in support for multiple databases -- **RESTful Support**: Easy API development -- **Command Line Tools**: Powerful CLI capabilities +- **Modern Architecture**: No `main()` method required, applications start directly via CLI +- **Dual-Mode Support**: CLI and Web are treated as equal citizens +- **Built-in Servers**: Native support for Netty, Tomcat, and Undertow +- **AI-Ready**: Designed for AI integration and Model Context Protocol (MCP) +- **SSE Support**: Native Server-Sent Events for real-time applications +- **High Performance**: Optimized to handle 86,000+ requests per second +- **Minimal Configuration**: Zero-boilerplate philosophy +- **Annotation-Based Routing**: Clean and intuitive routing with `@Action` ## Quick Start @@ -27,7 +28,7 @@ Add the dependency to your pom.xml: org.tinystruct tinystruct - 1.7.19 + 1.7.21 jar-with-dependencies ``` @@ -57,9 +58,24 @@ public class Example extends AbstractApplication { public String say(String words) { return words; } + + @Action(value = "hello", mode = Mode.HTTP_GET) + public String helloGet() { + return "GET"; + } } ``` +## What makes tinystruct modern? + +1. **No `main()` method required**: Applications can be started directly using CLI commands like `bin/dispatcher`, with no boilerplate code needed. +2. **Unified design for CLI and Web**: Unlike many frameworks, tinystruct treats CLI and Web as equal citizens. This makes it perfect for AI tasks, script automation, and hybrid applications. +3. **Built-in lightweight HTTP server**: Whether it’s Netty or Tomcat, tinystruct integrates the server lifecycle inside the framework. +4. **Minimal configuration philosophy**: Configuration is minimized to the essentials. No need to wire up hundreds of beans or complex XML/YAML files. +5. **Annotation-based routing**: Clean and intuitive routing using `@Action`, eliminating complex controller hierarchies. +6. **Performance-first architecture**: Almost zero overhead. No reflection-based bean scanning or unnecessary interceptors. +7. **AI & MCP Integration**: Built-in support for Model Context Protocol (MCP) and AI-driven workflows. + ## Documentation Contents - [Getting Started](getting-started.md) @@ -70,6 +86,7 @@ public class Example extends AbstractApplication { - [Database Integration](database.md) - [Advanced Features](advanced-features.md) - [Best Practices](best-practices.md) +- [AI & MCP Integration](mcp-integration.md) - [API Reference](api/README.md) ## Community and Support diff --git a/en/cli-applications.md b/en/cli-applications.md index b6be336..88d53f5 100644 --- a/en/cli-applications.md +++ b/en/cli-applications.md @@ -6,6 +6,18 @@ This guide explains how to build command-line interface (CLI) applications using tinystruct's CLI capabilities are powered by the same action mechanism used for web applications, making it easy to create both CLI tools and web interfaces with shared code. +## Unified Design for CLI and Web + +Unlike many other frameworks that treat CLI as an afterthought, tinystruct treats CLI and Web as equal citizens. This means: +- You can use the same `@Action` annotations for both modes. +- Business logic is naturally shared without extra layers. +- You can test your web actions via CLI easily. +- It's perfect for AI-driven tasks and automation. + +## No main() Method Required + +One of the modern features of tinystruct is that it doesn't require a `main()` method in your application classes. Applications are started directly using the `bin/dispatcher` tool. This reduces boilerplate and focuses your code on the logic itself. + ## Creating CLI Commands ### Basic Command diff --git a/en/getting-started.md b/en/getting-started.md index 763bd54..6bcac6d 100644 --- a/en/getting-started.md +++ b/en/getting-started.md @@ -29,7 +29,7 @@ Add the tinystruct dependency to your project's `pom.xml` file: org.tinystruct tinystruct - 1.7.19 + 1.7.21 jar-with-dependencies ``` @@ -84,6 +84,14 @@ public class HelloWorldApp extends AbstractApplication { public String greetPost() { return "POST: Hello!"; } + + @Action("say") + public String say() throws ApplicationException { + if (null != getContext().getAttribute("--words")) + return getContext().getAttribute("--words").toString(); + + throw new ApplicationException("Could not find the parameter words."); + } } ``` @@ -231,6 +239,7 @@ tinystruct is designed for high performance: - **Zero overhead** - no reflection-based scanning - **Direct method invocation** - no proxy layers - **Minimal memory footprint** +- **AI & MCP Ready** - built-in support for AI workflows ## Next Steps @@ -241,6 +250,7 @@ tinystruct is designed for high performance: - Dive into [Database Integration](database.md) - Review [Advanced Features](advanced-features.md) - Follow [Best Practices](best-practices.md) +- Learn about [AI & MCP Integration](mcp-integration.md) ## Examples and Resources diff --git a/en/mcp-integration.md b/en/mcp-integration.md new file mode 100644 index 0000000..1e4a08d --- /dev/null +++ b/en/mcp-integration.md @@ -0,0 +1,130 @@ +# AI & MCP Integration with tinystruct + +The Model Context Protocol (MCP) module for tinystruct provides comprehensive integration for AI model interactions, tool discovery, resource management, and prompt handling. + +## Overview + +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. + +## Key Concepts + +- **MCPApplication**: The base class for applications that want to handle MCP requests. +- **MCPServer**: A complete server implementation that manages tools, resources, and prompts. +- **MCPClient**: A client used to connect to and interact with MCP servers. +- **MCPTool**: Executable functions that can be discovered and called by AI models. +- **MCPResource**: Data sources that can be read by AI models. +- **MCPPrompt**: Template-based text generation for AI prompts. + +## Implementation + +### Creating an MCP Server + +To create an MCP server, extend the `MCPServer` class and register your tools, resources, or prompts in the `init()` method: + +```java +import org.tinystruct.mcp.MCPServer; +import org.tinystruct.mcp.tools.CalculatorTool; + +public class MyMCPServer extends MCPServer { + + @Override + public void init() { + super.init(); + + // Register built-in tools + CalculatorTool calculator = new CalculatorTool(); + this.registerTool(calculator); + + // Register custom tools + this.registerTool(new MyCustomTool()); + } +} +``` + +### Creating a Custom Tool + +Custom tools can be created by extending `MCPTool` and using the `@Action` annotation to define executable methods: + +```java +import org.tinystruct.mcp.MCPTool; +import org.tinystruct.system.annotation.Action; +import org.tinystruct.system.annotation.Argument; + +public class MyCustomTool extends MCPTool { + + public MyCustomTool() { + super("my-tool", "A custom tool for data processing", null, null, true); + } + + @Action(value = "my-tool/process", + description = "Process input data", + arguments = { + @Argument(key = "input", description = "The data to process", type = "string") + }) + public String processData(String input) { + return "Processed: " + input.toUpperCase(); + } +} +``` + +### Using the MCP Client + +You can connect to an MCP server programmatically using the `MCPClient`: + +```java +import org.tinystruct.mcp.MCPClient; +import java.util.HashMap; +import java.util.Map; + +public class ClientExample { + public static void main(String[] args) { + MCPClient client = new MCPClient("http://localhost:8080", "your-auth-token"); + + try { + client.connect(); + + // Execute a tool + Map params = new HashMap<>(); + params.put("a", 10); + params.put("b", 20); + Object result = client.executeResource("calculator/add", params); + + System.out.println("Result: " + result); + } catch (Exception e) { + e.printStackTrace(); + } finally { + client.disconnect(); + } + } +} +``` + +## Running the Server + +Start your MCP server using the tinystruct dispatcher: + +```bash +bin/dispatcher start --import com.example.MyMCPServer +``` + +## CLI Interaction + +The tinystruct CLI also provides commands to interact with MCP servers: + +```bash +# Connect to a server +bin/dispatcher mcp/connect --url http://localhost:8080 + +# List available tools +bin/dispatcher mcp/list/tools + +# Call a tool +bin/dispatcher mcp/call --name calculator/add --arguments "a:10,b:20" + +# Disconnect +bin/dispatcher mcp/disconnect +``` + +## Real-time Updates with SSE + +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`. diff --git a/en/web-applications.md b/en/web-applications.md index 8b8c4d7..5550586 100644 --- a/en/web-applications.md +++ b/en/web-applications.md @@ -12,10 +12,16 @@ tinystruct supports multiple web servers: bin/dispatcher start --import org.tinystruct.system.NettyHttpServer ``` -### Tomcat Server +### Undertow Server ```bash -bin/dispatcher start --import org.tinystruct.system.TomcatServer +bin/dispatcher start --import org.tinystruct.system.UndertowServer +``` + +### Built-in HTTP Server (Minimal) + +```bash +bin/dispatcher start --import org.tinystruct.system.HttpServer ``` ## Request Handling @@ -32,7 +38,7 @@ The framework automatically routes requests to the appropriate method based on t ### HTTP Method-Specific Actions -New in version 1.7.17, you can specify which HTTP methods an action responds to using the `mode` parameter: +New in version 1.7.21, you can specify which HTTP methods an action responds to using the `mode` parameter: ```java import org.tinystruct.system.annotation.Action.Mode; @@ -479,6 +485,42 @@ public Object adminUsers(Request request, Response response) { } ``` +## Server-Sent Events (SSE) + +tinystruct provides native support for Server-Sent Events (SSE), which allows servers to push real-time updates to web pages over HTTP. + +### Creating an SSE Endpoint + +To create an SSE endpoint, you can use the `SSEPushManager`: + +```java +@Action("events") +public void handleEvents(Request request, Response response) { + String sessionId = request.getSession().getId(); + + // Register the client for SSE + SSEPushManager.getInstance().register(sessionId, response); + + // The connection will be kept open automatically +} + +@Action("notify") +public String notifyClient(String message, Request request) { + String sessionId = request.getSession().getId(); + + // Push data to a specific client + SSEPushManager.getInstance().push(sessionId, message); + + return "Notification sent"; +} +``` + +## Model Context Protocol (MCP) & AI + +tinystruct is now AI-ready with built-in support for the Model Context Protocol (MCP). This allows your application to act as an MCP server or client, enabling seamless integration with AI models. + +For more details, see the [AI & MCP Integration](mcp-integration.md) guide. + ## Best Practices 1. **Separation of Concerns**: Keep your action methods focused on handling the request/response cycle, and delegate business logic to service classes. diff --git a/index.html b/index.html index 92129d0..7ceb17b 100644 --- a/index.html +++ b/index.html @@ -9,7 +9,7 @@ - tinystruct framework - v1.7.18 + tinystruct framework - v1.7.21 @@ -82,7 +82,7 @@ -
v1.7.18
+
v1.7.21