tinystruct MCP is a demonstration project that showcases how to develop Model Context Protocol (MCP) tools using the tinystruct framework. It provides a modular Java-based MCP server with built-in tools for file system management and GitHub operations.

This project is designed to bridge the gap between Large Language Models (LLMs) and external systems, enabling AI agents to interact with the physical file system and version control systems securely and efficiently.

• Modular Architecture: Built with Maven, allowing for easy expansion and isolation of tool sets.
• Annotation-Driven: Simplify tool development using @Action and @Argument annotations for automatic schema generation.
• Ready-to-Use Tools: Includes robust implementations for Git, GitHub API, and local FileSystem operations.
• Extensible Design: Inherits the flexibility of the tinystruct framework for building high-performance Java applications.
• Standardized Communication: Uses org.tinystruct.data.component.Builder for consistent JSON-based interaction.

The project is organized into submodules, each representing a specific domain of tools:

• github/: Implements Git operations (clone, pull, push, status) and GitHub API integrations (issues, PRs, actions).
• filesystem/: Provides comprehensive local file system management (read, write, copy, move, delete, list).
• database/: Provides database connectivity and operations (query, insert, update, delete, describe).
• websearch/: Provides web search capabilities using DuckDuckGo Instant Answer API.
• bin/: Contains scripts for server management and dispatching commands.

• Java 17 or higher
• Maven 3.8+

Clone the repository and build the modules using Maven:

git clone https://github.com/tinystruct/tinystruct-mcp.git
cd tinystruct-mcp
mvn clean install

You can start the server programmatically or via the command line.

Use the bin/dispatcher (for Linux/macOS) or bin/dispatcher.cmd (for Windows) script to start the server:

# On Linux / macOS
bin/dispatcher start --import org.tinystruct.system.HttpServer --import org.tinystruct.mcp.GitHub --import org.tinystruct.mcp.FileSystem --import org.tinystruct.mcp.Database --import org.tinystruct.mcp.websearch.WebSearch --server-port 777

# On Windows
bin\dispatcher.cmd start --import org.tinystruct.system.HttpServer --import org.tinystruct.mcp.GitHub --import org.tinystruct.mcp.FileSystem --import org.tinystruct.mcp.Database --import org.tinystruct.mcp.websearch.WebSearch --server-port 777

Include the following in your Main class to boot the server with integrated tools:

import org.tinystruct.ApplicationContext;
import org.tinystruct.application.Context;
import org.tinystruct.system.ApplicationManager;
import org.tinystruct.system.HttpServer;
import org.tinystruct.mcp.GitHub;
import org.tinystruct.mcp.FileSystem;
import org.tinystruct.mcp.Database;
import org.tinystruct.mcp.websearch.WebSearch;

public class Main {
    public static void main(String[] args) {
        Context ctx = new ApplicationContext();
        ctx.setAttribute("--server-port", "777");
        
        ApplicationManager.init();
        ApplicationManager.install(new GitHub());
        ApplicationManager.install(new FileSystem());
        ApplicationManager.install(new Database());
        ApplicationManager.install(new WebSearch());
        ApplicationManager.install(new HttpServer());
        
        ApplicationManager.call("start", ctx);
    }
}

Creating new MCP tools is straightforward. Simply extend the MCPTool class and annotate your methods.

@Action(value = "mytool/greet", description = "Greet a user", arguments = {
    @Argument(key = "name", description = "User's name", type = "string")
})
public String greet(String name) {
    return "Hello, " + name + "!";
}

For a detailed guide on creating custom tools, check out DEVELOPING_TOOLS.md.

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Note: MCP stands for Model Context Protocol.