pty-mcp-server 0.0.5.0 → 0.0.6.0
raw patch · 4 files changed
+77/−27 lines, 4 filesdep +pms-infra-serialdep ~base
Dependencies added: pms-infra-serial
Dependency ranges changed: base
Files
- CHANGELOG.md +4/−0
- README.md +60/−15
- app/Main.hs +6/−7
- pty-mcp-server.cabal +7/−5
CHANGELOG.md view
@@ -1,5 +1,9 @@ # Revision history for pty-mcp-server +## 0.0.6.0 -- 2025-07-13++* Added serial tool.+ ## 0.0.5.0 -- 2025-07-06 * Added resources interface.
README.md view
@@ -117,6 +117,23 @@ - **`socket-telnet`** A simple Telnet-like communication tool over raw TCP sockets. This tool connects to a specified host and port, sends and receives data, and removes any Telnet IAC (Interpret As Command) sequences from the communication stream. Note: This is a simplified Telnet implementation and does not support full Telnet protocol features. ++- **`serial-open`** + Opens a serial port connection to a specified device with a given baud rate. Commonly used to access on-premises hardware or network devices via console.++- **`serial-close`** + This tool close active serial connection that was previously established using the 'serial-open' tool.++- **`serial-read`** + Reads the specified number of bytes from the serial. The 'size' parameter indicates how many bytes to read.++- **`serial-write`** + Write a sequence of bytes to the serial.++- **`serial-message`** + This tool sends a specified string to the active socket connection, then waits for a recognizable prompt from the remote side. Upon detecting the prompt, it captures and returns all output received prior to it.++ - **`Scriptable CLI Integration`** The `pty-mcp-server` supports execution of shell scripts associated with registered tools defined in `tools-list.json`. Each tool must be registered by name, and a corresponding shell script (`.sh`) should exist in the configured `tools/` directory. @@ -190,7 +207,7 @@ ### Binary Installation If you prefer to build it yourself, make sure the following requirements are met: -- GHC >= 9.12 +- GHC >= 9.6 You can install `pty-mcp-server` using `cabal`: @@ -262,38 +279,63 @@ This video demonstrates a Telnet login sequence powered by the MCP prompt defined in [socket-telnet-prompt.md](https://github.com/phoityne/pty-mcp-server/blob/main/assets/prompts/socket-telnet-prompt.md). Using tools like `socket-open`, `socket-read`, `socket-write`, and `socket-message`, the AI performs Telnet negotiation, handles prompts, and submits credentials. Binary responses are parsed and displayed in human-readable form. +### Network Device Version Check via Serial Connection — powered by pty-mcp-server.+ +Ref : [serial-nw-check-prompt](https://github.com/phoityne/pty-mcp-server/blob/main/assets/prompts/serial-nw-check-prompt.md) +This video demonstrates how `pty-mcp-server` enables AI-assisted automation over a serial connection to a network device.++1. Device Setup+The user specifies the communication port and baud rate. +**Example:** `COM3`, 9600 baud on Windows.++2. Login Interaction+The AI prompts for a username and password, +and uses them to log in to the network device.++3. Device Version Retrieval+After logging in, the AI sends a command +to retrieve the installed OS or firmware version.++4. Online Version Check+The AI accesses the official website to check the latest available version, +and compares it with the installed version.++5. Session Termination+Once the check is complete, the AI logs out and cleanly closes the serial connection.++ ### Demo: Watch AI Create and Launch a Web App from Scratch  Ref : [Web Service Construction Agent Prompt](https://github.com/phoityne/pty-mcp-server/blob/main/assets/prompts/web-service-prompt.md) -1. 📌 [Scene 1: Overview & MCP Configuration] +1. [Scene 1: Overview & MCP Configuration] In this demo, we’ll show how an AI agent builds and runs a web service inside a Docker container using the `pty-mcp-server`. First, we configure `mcp.json` to launch the MCP server using a shell script. This script starts the Docker container where our PTY-based interaction will take place.-2. 🐳 [Scene 2: Docker Launch Configuration] +2. [Scene 2: Docker Launch Configuration] The `run.sh` script includes volume mounts, hostname settings, and opens **port 8080**. This allows the container to expose a web service to the host system. -3. 🚀 [Scene 3: Starting the MCP Server] +3. [Scene 3: Starting the MCP Server] Now, the container is launched, and the `pty-mcp-server` is running inside it, ready to handle AI-driven requests through a pseudo-terminal. -4. 🤖 [Scene 4: Connecting the AI Agent] +4. [Scene 4: Connecting the AI Agent] We open the chat interface and send a prompt designed for a web service builder agent. The AI connects to the container’s Bash session via PTY and begins its preparation. -5. 🛠️ [Scene 5: Initial Setup Commands] +5. [Scene 5: Initial Setup Commands] Following the prompt, the AI starts by: - Creating a project folder - Moving into the working directory -6. 📥 [Scene 6: AI Ready to Receive Instructions] +6. [Scene 6: AI Ready to Receive Instructions] Once the environment is ready, we instruct the AI to build a “Hello, world” web service. From here, the AI begins its autonomous construction process. -7. ⚙️ [Scene 7: AI Executes Web Setup Commands] +7. [Scene 7: AI Executes Web Setup Commands] The AI proposes a series of terminal commands. As the user, we review and approve them one by one. Steps include:@@ -303,18 +345,17 @@ - Running the Flask server - Testing via `curl http://localhost:8080` inside the container -8. 🌐 [Scene 8: Verifying from Outside the Container] -To confirm external accessibility, we access the service from the host via **port 8080**. -✅ As expected, the response is: **“Hello, world”**+8. [Scene 8: Verifying from Outside the Container] +To confirm external accessibility, we access the service from the host via **port 8080**. As expected, the response is: **“Hello, world”** -9. 🧾 [Scene 9: Reviewing the Execution History] +9. [Scene 9: Reviewing the Execution History] Finally, we review the AI's actions step by step: - Initialized the Bash session and created the working directory - Set up the Python environment - Generated the Flask-based `app.py` - Launched the web server and validated its operation -10. 🏁 [Scene 10: Conclusion] +10. [Scene 10: Conclusion] This demonstrates how AI, combined with the **PTY-MCP-Server** and **Docker**, can automate real development tasks — **interactively**, **intelligently**, and **reproducibly**. @@ -467,9 +508,13 @@ ### Deployment Diagram-+ ### Package Structure-+++### Thread Structure++ ----
app/Main.hs view
@@ -1,5 +1,6 @@-{-# LANGUAGE MultilineStrings #-} {-# LANGUAGE CPP #-}+--{-# LANGUAGE MultilineStrings #-}+ module Main where import System.IO@@ -16,6 +17,7 @@ import qualified PMS.UI.Notification.App.Control as UNO import qualified PMS.Infra.CmdRun.App.Control as ICR import qualified PMS.Infra.ProcSpawn.App.Control as IPS+import qualified PMS.Infra.Serial.App.Control as SER import qualified PMS.Infra.Socket.App.Control as SCK import qualified PMS.Infra.Watch.App.Control as IWA import qualified PMS.Domain.Service.App.Control as DSR@@ -30,9 +32,9 @@ main :: IO () main = getArgs >>= \args -> do #ifdef mingw32_HOST_OS- let apps = [URQ.run, URS.run, UNO.run, ICR.run, IPS.run, IWA.run, DSR.run, SCK.run]+ let apps = [URQ.run, URS.run, UNO.run, ICR.run, IPS.run, IWA.run, DSR.run, SCK.run, SER.run] #else- let apps = [URQ.run, URS.run, UNO.run, ICR.run, IPS.run, IWA.run, DSR.run, SCK.run, INF.run]+ let apps = [URQ.run, URS.run, UNO.run, ICR.run, IPS.run, IWA.run, DSR.run, SCK.run, SER.run, INF.run] #endif flip E.catchAny exception $ flip E.finally finalize@@ -65,10 +67,7 @@ [ fullDesc , header "pty-mcp-server - Pseudo-terminal MCP Server" , footer "Copyright (c) 2025 phoityne. All rights reserved."- , progDesc """- A minimal PTY-based server for running shell commands in MCP style. - Designed for AI to control interactive programs like GHCi or bash.- """+ , progDesc "A minimal PTY-based server for running shell commands in MCP style.\n Designed for AI to control interactive programs like GHCi or bash." ] -- |
pty-mcp-server.cabal view
@@ -1,4 +1,4 @@-cabal-version: 3.12+cabal-version: 2.4 -- The cabal-version field refers to the version of the .cabal specification, -- and can be different from the cabal-install (the tool) version and the -- Cabal (the library) version you are using. As such, the Cabal (the library)@@ -20,7 +20,7 @@ -- PVP summary: +-+------- breaking API changes -- | | +----- non-breaking API additions -- | | | +--- code changes with no API change-version: 0.0.5.0+version: 0.0.6.0 -- A short (one-line) description of the package. synopsis: pty-mcp-server@@ -70,7 +70,7 @@ -- Other library packages from which modules are imported. if os(windows) build-depends:- base ^>=4.21.0.0,+ base >= 4.18 && < 5, safe-exceptions, optparse-applicative, pms-ui-request,@@ -78,6 +78,7 @@ pms-ui-notification, pms-infra-cmdrun, pms-infra-procspawn,+ pms-infra-serial, pms-infra-socket, pms-infra-watch, pms-application-service,@@ -85,7 +86,7 @@ pms-domain-model else build-depends:- base ^>=4.21.0.0,+ base >= 4.18 && < 5, safe-exceptions, optparse-applicative, pms-ui-request,@@ -94,6 +95,7 @@ pms-infrastructure, pms-infra-cmdrun, pms-infra-procspawn,+ pms-infra-serial, pms-infra-socket, pms-infra-watch, pms-application-service,@@ -104,4 +106,4 @@ hs-source-dirs: app -- Base language which the package is written in.- default-language: GHC2021+ default-language: Haskell2010