DeepSeek MCP-like Server for Terminal

1# DeepSeek MCP-like Server for Terminal
2 
3[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/OthmaneBlial/term_mcp_deepseek)](https://archestra.ai/mcp-catalog/othmaneblial__term_mcp_deepseek)
4This project is an MCP‑like server using the DeepSeek API. It aims to demonstrate the core concepts behind the Model Context Protocol (MCP) by exposing endpoints that allow AI assistants to:
5 
6- List available tools.
7- Invoke commands on an active shell session.
8- Integrate with an AI chat (DeepSeek) that can include special instructions (e.g., `CMD:` lines) to trigger command execution.
9 
10> **Note:** While this implementation captures many of the MCP ideas and includes features like real-time streaming, session management, and basic security, it is not yet a fully compliant MCP server as defined by Anthropic. It is designed as a proof-of-concept, and further enhancements (e.g., complete JSON‑RPC protocol support, advanced authentication, and comprehensive error handling) would be needed for production use.
11 
12## Features
13 
14- **Chat Interface:**
15  A modern web-based chat client (using Flask and Tailwind CSS) where users can interact with the server, now with real-time updates and improved error handling.
16 
17- **AI Integration:**
18  Uses the DeepSeek API to generate responses. The AI can instruct the server to execute terminal commands by including lines beginning with `CMD:`.
19 
20- **Terminal Command Execution:**
21  Executes shell commands via a persistent Bash session using the `pexpect` library and returns output to the client, with added real-time streaming capabilities.
22 
23- **MCP Endpoints:**
24  Provides `/mcp/list_tools` and `/mcp/call_tool` endpoints that mimic MCP tool discovery and invocation, with expanded protocol support including prompts, resources, and roots.
25 
26- **Real-time Streaming:**
27  Server-Sent Events (SSE) for live command execution updates and terminal output.
28 
29- **Security Enhancements:**
30  Basic authentication, rate limiting, input validation, and security headers for safer operation.
31 
32- **Multiple Transport Options:**
33  Supports both HTTP REST API and STDIO command-line interface for flexibility.
34 
35- **Session Management:**
36  Improved session handling and conversation storage.
37 
38- **Docker Support:**
39  Containerization for easier deployment and testing.
40 
41## Getting Started
42 
43### Prerequisites
44 
45- Python 3.8+
46- [pip](https://pip.pypa.io/)
47- A valid DeepSeek API key
48 
49### Installation
50 
511. **Clone the repository:**
52 
53   ```bash
54   git clone https://github.com/OthmaneBlial/term_mcp_deepseek.git
55   cd term_mcp_deepseek
56   ```
57 
582. **Create and activate a virtual environment:**
59 
60   ```bash
61   python3 -m venv venv
62   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
63   ```
64 
653. **Install the required dependencies:**
66 
67   ```bash
68   pip install -r requirements.txt
69   ```
70 
714. **Configure your API key:**
72 
73   Update the `DEEPSEEK_API_KEY` in `.env` with your DeepSeek API key.
74 
75### Running the Server
76 
77#### Quick Start
78 
79Use the provided startup script for convenience:
80 
81```bash
82chmod +x startup.sh
83./startup.sh
84```
85 
86#### Manual Start
87 
88Run the Flask server with:
89 
90```bash
91python server.py
92```
93 
94Visit [http://127.0.0.1:8000](http://127.0.0.1:8000) to access the chat interface.
95 
96#### Docker
97 
98For containerized deployment:
99 
100```bash
101docker-compose up -d
102```
103 
104## Endpoints
105 
106### Chat Endpoint
107- **URL:** `/chat`
108- **Method:** `POST`
109- **Payload:** `{ "message": "your message here" }`
110- **Description:**
111  Adds the user message to the conversation, sends it to the DeepSeek API, looks for any command instructions (`CMD:`), executes them, and returns the final response.
112 
113### MCP Endpoints
114 
115#### List Tools
116- **URL:** `/mcp/list_tools`
117- **Method:** `POST`
118- **Response:**
119  JSON listing available tools (e.g., `write_to_terminal`, `read_terminal_output`, `send_control_character`).
120 
121#### Call Tool
122- **URL:** `/mcp/call_tool`
123- **Method:** `POST`
124- **Payload:**
125  ```json
126  {
127    "name": "tool_name",
128    "arguments": { ... }
129  }
130  ```
131- **Description:**
132  Directly invoke a tool command on the server.
133 
134### Real-time Streaming
135- **URL:** `/stream?session_id=session_id`
136- **Method:** `GET`
137- **Description:** Server-Sent Events endpoint for real-time command output updates.
138 
139## Future Improvements
140 
141- **Protocol Standardization:**
142  Implement JSON‑RPC for a more robust and standardized communication protocol.
143 
144- **Real-time Communication:**
145  Add Server‑Sent Events (SSE) or WebSockets for live command output streaming.
146 
147- **Session & Security Enhancements:**
148  Introduce per‑user sessions, proper authentication, input sanitization, and comprehensive error handling.
149 
150- **Modular Code Architecture:**
151  Further separate API logic from business logic for better maintainability and scalability.
152 
153## License
154 
155This project is open-source and available under the [MIT License](LICENSE).