tinystruct MCP project

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.

---

Key Features

• 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.

---

Project Structure

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.

---

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.8+

1. Build the Project

Clone the repository and build the modules using Maven:

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

2. Start the MCP Server

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

Command Line (CLI)

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

Programmatic Startup (Java)

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);
    }
}

---

Built-in Tools

GitHub Tool (github/)

| Action | Description | | :--- | :--- | | github/clone | Clone a Git repository | | github/pull | Pull changes from a remote repository | | github/push | Push changes to a remote repository | | github/status | Get the current status of a local repository | | github/issues | Fetch GitHub issues for a repository | | github/prs | Fetch GitHub pull requests | | github/actions | List GitHub Actions workflows |

FileSystem Tool (filesystem/)

| Action | Description | | :--- | :--- | | filesystem/info | Get metadata about a file or directory | | filesystem/exists | Check if a path exists | | filesystem/read | Read contents of a file (UTF-8 or Base64) | | filesystem/write | Write content to a file (overwrite or append) | | filesystem/list | List items in a directory | | filesystem/copy | Copy a file or directory | | filesystem/move | Move or rename a file or directory | | filesystem/delete | Delete a file or directory (recursive support) | | filesystem/mkdir | Create a new directory |

Database Tool (database/)

| Action | Description | | :--- | :--- | | db/list-tables | List all tables in the connected database | | db/describe | Describe the columns and types of a specific table | | db/query | SELECT rows from a table with optional WHERE and LIMIT | | db/insert | INSERT a row into a table | | db/update | UPDATE rows in a table matching a WHERE clause | | db/delete | DELETE rows from a table matching a WHERE clause | | db/execute | Execute arbitrary SQL |

WebSearch Tool (websearch/)

| Action | Description | | :--- | :--- | | websearch/search | Perform a web search using DuckDuckGo Instant Answer API |

---

Developing Your Own Tools

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.

---

License

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

Note: MCP stands for Model Context Protocol.