Servidor de terminales MCP
Un servidor de ejecución de terminal seguro que implementa el Protocolo de Contexto de Modelo (MCP). Este servidor proporciona capacidades de ejecución controlada de comandos con funciones de seguridad y límites de recursos.
Características
- Ejecución de comandos : Ejecute comandos de shell con captura de salida y manejo de errores
- Controles de seguridad : restrinja los comandos permitidos y evite la inyección de comandos
- Controles de recursos :
- Tiempos de espera de comandos
- Límites de tamaño máximo de salida
- Compatibilidad con el protocolo MCP :
- Formato de mensaje MCP estándar
- Anuncio de capacidad
- Compatibilidad con salida de streaming
Desarrollo
Configuración local
# Clone the repository
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal
# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
# Install development dependencies
uv pip install -e ".[dev]"
Publicación en PyPI
# Build the package
uv pip install build
python -m build
# Upload to PyPI
uv pip install twine
python -m twine upload dist/*
Pruebas con MCP Inspector
La herramienta MCP Inspector se puede utilizar para probar la implementación del servidor:
# Install inspector
npm install -g @modelcontextprotocol/inspector
# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"
Ejecución de pruebas
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_terminal.py
# Run with coverage
pytest --cov=mcp_terminal tests/
Uso con Claude Desktop
Una vez que el paquete se publica en PyPI:
- Instalar UV (si aún no está instalado):
- Instalar el paquete usando UV :
uv pip install mcp-terminal
- Configurar Claude Desktop : edite el archivo de configuración de Claude Desktop (normalmente en
~/Library/Application Support/Claude/claude_desktop_config.json en macOS):{
"mcpServers": {
"terminal": {
"command": "uv",
"args": [
"pip",
"run",
"mcp-terminal",
"--allowed-commands",
"python,pip,git,ls,cd",
"--timeout-ms",
"30000",
"--max-output-size",
"1048576"
]
}
}
}
Implementación del protocolo
El servidor implementa el Protocolo de Contexto de Modelo (MCP) con las siguientes capacidades:
Anuncio de capacidades
{
"protocol": "1.0.0",
"name": "terminal",
"version": "1.1.0",
"capabilities": {
"execute": {
"description": "Execute a terminal command",
"parameters": {
"command": {
"type": "string",
"description": "The command to execute"
}
},
"returns": {
"type": "object",
"properties": {
"exitCode": { "type": "number" },
"stdout": { "type": "string" },
"stderr": { "type": "string" },
"startTime": { "type": "string" },
"endTime": { "type": "string" }
}
}
}
}
}
Pedido :
{
"type": "execute",
"data": {
"command": "echo 'hello world'"
}
}
Respuesta :
{
"type": "result",
"data": {
"command": "echo 'hello world'",
"exitCode": 0,
"stdout": "hello world\n",
"stderr": "",
"startTime": "2024-01-20T12:34:56.789Z",
"endTime": "2024-01-20T12:34:56.790Z"
}
}
Error :
{
"type": "error",
"data": {
"message": "command not allowed"
}
}
Consideraciones de seguridad
- Validación de comandos :
- Sólo se pueden ejecutar los comandos permitidos
- Los operadores de Shell están bloqueados
- Se evitan los intentos de inyección de comandos
- Protección de recursos :
- Los tiempos de espera de los comandos evitan que se cuelguen
- Los límites de tamaño de salida evitan el agotamiento de la memoria
- Manejo de errores para todos los casos de falla
- Mejores prácticas :
- Establezca siempre
allowed-commands en producción - Utilice límites de tamaño y tiempo de espera conservadores
- Supervisar los registros de ejecución de comandos
Contribuyendo
- Bifurcar el repositorio
- Crea tu rama de funciones (
git checkout -b feature/amazing-feature ) - Confirme sus cambios (
git commit -m 'Add some amazing feature' ) - Empujar a la rama (
git push origin feature/amazing-feature ) - Abrir una solicitud de extracción
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.