# MCP Terminal Server (Python)

MCP Terminal Server — это сервер для выполнения терминальных команд через протокол Model Context Protocol (MCP), интегрируемый с Cursor AI. Проект предоставляет инструменты для безопасного и гибкого запуска команд в различных оболочках (bash, cmd, PowerShell) с поддержкой ограничений и метрик.

---

## Возможности
- **Поддерживаемые оболочки:** PowerShell (по умолчанию на Windows), cmd, bash
- **Параметры:**
  - `command` — команда для выполнения
  - `shell` — оболочка (опционально)
  - `cwd` — рабочая директория (опционально)
  - `timeout_seconds` — таймаут выполнения (опционально)
- **Транспорт MCP:** stdio
- **Метрики и ограничения:**
  - Максимальный размер stdout/stderr
  - Ограничение длины команды
  - Ограничение числа одновременных процессов
  - Грейс-период для завершения процессов

---

## Быстрый старт

### 1. Клонирование и установка зависимостей
```bash
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# или .venv\Scripts\activate  # Windows PowerShell
pip install -r requirements.txt
```

### 2. Конфигурация Cursor
Создайте файл `.cursor/mcp.json` в корне TMCP:
```json
{
  "mcpServers": {
    "terminal-mcp": {
      "command": "python",
      "args": ["-m", "TMCP.mcp_terminal.server"]
    }
  }
}
```
Cursor автоматически запустит MCP сервер через stdio.

### 3. Запуск вручную (для отладки)
```bash
python -m TMCP.mcp_terminal.server
```

---

## Использование
После запуска сервера инструмент `run_command` будет доступен в Cursor.

### Примеры вызова
- **PowerShell (по умолчанию на Windows):**
  - `command`: `Get-ChildItem`
- **Через cmd:**
  - `shell`: `cmd`
  - `command`: `dir`
- **С указанием рабочей папки и таймаута:**
  - `cwd`: `C:\CursorProjects\TMCP`
  - `timeout_seconds`: `60`

---

## Структура проекта
```
TMCP/
├── mcp_terminal/
│   ├── __init__.py
│   └── server.py         # Основная логика MCP сервера
├── scripts/
│   └── test_terminal_mcp.py  # Пример теста клиента
├── .cursor/
│   └── mcp.json          # Пример конфигурации для Cursor
├── requirements.txt
├── README.md
└── __init__.py
```

---

## Для разработчиков
- Код сервера написан на Python 3.8+
- Для тестирования используйте скрипты из папки `scripts/`
- Для расширения функционала добавляйте новые инструменты через декоратор `@server.tool`
- Метрики и кастомные маршруты реализованы для мониторинга и интеграции

---

## Безопасность
- **Не передавайте неподтверждённые команды** — сервер выполняет любые команды, полученные через MCP.
- **Запускайте сервер без повышенных прав** (не от root/Administrator).
- Используйте переменные окружения для ограничения разрешённых оболочек, директорий и таймаутов.

---

## Лицензия
MIT License

---

## Контакты и поддержка
Автор: magadsm
Вопросы и предложения: через GitHub Issues