Tinysa MCP

🚀 tinysa-mcp

An MCP server for operating TinySA devices via serial port

⚠️ Important Note

I'm currently conducting experiments, so I can't guarantee the normal operation of all functions.

📋 Overview

This project is an MCP server designed to operate TinySA devices via the serial port. It leverages Python libraries such as pyserial, httpx, numpy, Pillow, and FastMCP, offering a tool-based interface for connecting to the device, executing commands, and retrieving device version information.

🧐 Architecture and Thread Model

This project uses both a Tkinter graphical interface and an MCP server. Since Tkinter must run in the main thread, the following design is adopted:

flowchart TD
    subgraph MainThread
        A[main()] --> B[tk.Tk() & TinySALogMonitor]
        B --> C[root.mainloop()]
    end
    subgraph MCPThread
        D[run_mcp_server(mcp_server)]
        D --> E[mcp_server.run()]
    end
    E -- log_callback --> F[log_monitor.log_queue]
    F -- root.afterで定期ポーリング --> B
    D -- サーバー終了時 --> G[root.after(0, root.destroy)]

• Tkinter GUI runs in the main thread: The main thread initializes the Tkinter root window and starts the main event loop. All GUI operations are executed in this thread.

• MCP server runs in a background thread: The MCP server is launched in a separate thread using Python's threading.Thread. This allows the server to handle requests concurrently with the GUI.

• Inter-thread communication via a queue: Log messages and other data are sent from the MCP server (or other background threads) to the GUI through a queue.Queue. The GUI uses root.after to periodically poll this queue to safely update the display.

• Graceful shutdown: When the MCP server stops, it schedules the GUI to close using root.after(0, root.destroy), ensuring that all Tkinter operations remain in the main thread.

Example (main function):

def main():
    root = tk.Tk()
    log_monitor = TinySALogMonitor(root)
    mcp_server = create_mcp_server(log_monitor.add_log)
    mcp_thread = threading.Thread(target=run_mcp_server, args=(mcp_server,), daemon=True)
    mcp_thread.start()
    root.mainloop()

Notes

• Never access Tkinter objects from background threads. Always use the provided queue and root.after for thread-safe communication.
• This design ensures that the MCP server and GUI can run concurrently while adhering to Tkinter's threading requirements.

✨ Features

• Send commands and receive responses from the device.
• Retrieve firmware and hardware version information.
• Provide MCP tools for integration with other systems.
• Support capturing images from the device screen and optionally saving files with timestamps.

🛠️ MCP Tools

The following MCP tools are available:

• get_version: Retrieve version information from the TinySA device.
• execute_command: Send a command to the TinySA device and receive a response.
• connect: Connect to the TinySA device on the specified port.
• disconnect: Disconnect from the TinySA device.
• get_device_info: Retrieve detailed information about the connected device.
• capture_image: Capture an image of the TinySA screen and optionally save the file with a timestamp.

💻 Usage Examples

# Example code:
print("Device version: ", get_version())
print("Command execution result: ", execute_command("command"))
connect(port)
get_device_info()
captured_image = capture_image()

🐞 Troubleshooting

1. Connection issues: Ensure that the device is properly connected and the port configuration is correct.
2. Permission issues: Run the script with administrative privileges or check the device permission settings.
3. Logging: Use log_monitor to view detailed log information for error troubleshooting.

📚 References

• pyserial documentation
• FastMCP project page

📄 License

[License content]

This project aims to provide an efficient tool for operating TinySA devices. Although it's currently in the experimental stage, the functions will be continuously improved and optimized in the future.