AI导哈

终端MCP服务器

一个全面的模型上下文协议（MCP）服务器，为AI代理提供完整的终端和系统访问能力，使其能够执行命令行操作、管理进程、运行Python脚本和进行系统级任务。

  • by thepeacefulprogrammer
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 thepeacefulprogrammer/terminal_mcp_server

使用说明

终端MCP服务器

一个全面的模型上下文协议（MCP）服务器，为AI代理提供完整的终端和系统访问能力。此服务器使AI编码代理能够通过安全可靠的MCP接口执行任何命令行操作、管理进程、执行Python脚本和执行系统级任务。

🎯 项目愿景

将AI代理转化为自主开发人员 通过提供与人类开发人员相当的完整终端访问。该服务器弥合了人工智能推理和系统级操作之间的差距，实现了：

  • 自主发展：AI代理可以编译、测试、调试和部署代码
  • 系统管理：完全访问Linux命令行操作
  • 流程管理：后台流程生命周期管理
  • Python集成：使用虚拟环境支持执行脚本
  • 实时反馈：用于即时决策的流式命令输出
  • 项目意识执行：通过智能工作目录检测从项目目录执行命令

✅ 当前功能（生产就绪）

18个完全实施的MCP工具

命令执行

  • ✅ execute_command -执行带有实时输出和项目感知工作目录的shell命令
  • ✅ execute_command_background -通过进程管理在后台启动命令
  • ✅ get_process_output -从后台命令检索输出

流程管理

  • ✅ list_background_processes -列出所有活动的后台进程
  • ✅ kill_background_process -安全终止后台进程
  • ✅ get_process_status -获取详细的流程状态和监控
  • ✅ restart_background_process -自动重新启动失败的进程

Python集成

  • ✅ execute_python_script -运行具有输出流和虚拟环境支持的Python脚本
  • ✅ execute_python_code -直接使用项目上下文执行Python代码
  • ✅ execute_python_code_with_streaming -实时流式Python执行
  • ✅ install_python_package -通过虚拟环境集成管理Python依赖关系

环境管理

  • ✅ change_directory -通过验证更改工作目录
  • ✅ get_current_directory -获取当前目录信息
  • ✅ set_environment_variable -设置具有持久性的环境变量
  • ✅ get_environment_variables -通过过滤获取环境变量

虚拟环境工具

  • ✅ list_virtual_environments -发现可用的虚拟环境
  • ✅ activate_virtual_environment -无缝切换虚拟环境
  • ✅ create_virtual_environment -通过软件包安装创建新的虚拟环境
  • ✅ install_dependencies -自动安装requirements.txt依赖项

🚀 主要功能和改进

项目感知工作目录（v1.1）

  • 智能检测：使用自动检测项目目录 pyproject.toml, README.md，以及源代码结构
  • 自然工作流：命令如下 ls src/ 没有绝对路径的工作
  • 向后兼容：明确 working_directory 参数仍然覆盖默认值
  • 配置驱动：可通过以下方式定制 config/config.yaml

实时输出流

  • <50ms延迟：近乎瞬时的命令反馈
  • 异步处理：具有完全异步/等待支持的非阻塞执行
  • 流管理：适当的缓冲和输出处理

稳健的流程管理

  • 后台进程：具有监控功能的全生命周期管理
  • 过程安全：自动清理和资源管理
  • 状态监测：实时流程状态和健康检查

Python集成卓越

  • 虚拟环境支持：无缝的venv创建和管理
  • 依赖管理：自动包装安装和需求处理
  • 脚本执行：基于文件和直接代码执行
  • 项目上下文：Python代码通过正确的项目导入执行

📋 实施状态

✅ 第一阶段：核心功能- 完成

  • ✅ 使用输出流执行基本命令
  • ✅ 错误处理和退出代码报告
  • ✅ 后台流程管理
  • ✅ 工作目录智能和项目检测

✅ 第二阶段：Python集成- 完成

  • ✅ Python脚本执行
  • ✅ 虚拟环境支持
  • ✅ 依赖管理
  • ✅ 实时流媒体执行

✅ 第三阶段：高级功能- 完成

  • ✅ 过程监控和重启功能
  • ✅ 高级输出处理和过滤
  • ✅ 性能优化
  • ✅ 全面的错误处理

🎯 当前状态：生产就绪

  • 301单元测试通过 （成功率100%）
  • >95%代码覆盖率 具有全面的边缘情况测试
  • TDD实施 确保稳健可靠的功能
  • 完全符合MCP 正确的工具注册和错误处理

🎯 目标用例

主要用户：AI编码代理 /home/randy/workspace/personal/my_coding_agent

功能已启用:

  • ✅ 自主代码编译和测试
  • ✅ 实时调试，即时反馈
  • ✅ 文件系统操作和项目管理
  • ✅ 包安装和依赖关系管理
  • ✅ 系统监控和过程控制
  • ✅ 集成测试和部署任务
  • ✅ 项目感知命令执行

🛠️ 安装和设置

快速启动（生产）

# Clone the repository
git clone <repository-url> terminal_mcp_server
cd terminal_mcp_server

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install production dependencies
pip install -e .

# Run the server
python -m terminal_mcp_server.server

开发设置

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

配置

服务器使用 config/config.yaml 配置：

terminal:
  execution:
    default_working_directory: "."  # Auto-detects project directory
    timeout: 300
    max_background_processes: 10
  
logging:
  level: "INFO"
  file: "logs/mcp_server.log"

📚 文档

🔧 架构概述

设计原则

  • 异步优先：所有操作都使用async/await进行非阻塞执行
  • 实时流媒体：使用异步生成器实时输出命令流
  • 过程安全：具有清理功能的全面流程生命周期管理
  • 项目智能：自动项目检测和上下文感知执行
  • 资源限制：内存使用和进程计数的可配置限制
  • 综合录井：所有业务的完整审计跟踪

技术栈

  • FastMCP：MCP协议实施
  • psutil：先进的过程监控
  • 异步IO：异步进程执行
  • 派丹蒂克：数据验证和建模
  • pytest：覆盖率>95%的测试框架

项目结构

terminal_mcp_server/
├── src/terminal_mcp_server/    # Core server implementation
│   ├── handlers/               # MCP tool handlers
│   ├── models/                 # Data models and schemas
│   ├── utils/                  # Utilities and managers
│   └── server.py              # Main server entry point
├── tests/unit/                # Comprehensive unit tests (301 tests)
├── config/                    # Configuration files
├── tools/                     # Development and debugging tools
└── tasks/                     # Project management and documentation

🎮 MCP工具参考

命令执行工具

# Execute commands with project-aware working directory
execute_command(command="ls src/")
execute_command(command="pytest", working_directory="/custom/path")

# Background process management
execute_command_background(command="npm run dev")
list_background_processes()
get_process_status(process_id="abc123")
kill_background_process(process_id="abc123")

Python集成工具

# Execute Python code with project context
execute_python_code(code="import sys; print(sys.path)")
execute_python_script(script_path="scripts/deploy.py")

# Virtual environment management
create_virtual_environment(name="myproject")
activate_virtual_environment(name="myproject")
install_python_package(package="requests", virtual_environment="myproject")

环境管理工具

# Directory and environment management
get_current_directory()
change_directory(path="/home/user/project")
set_environment_variable(name="API_KEY", value="secret")
get_environment_variables(variables=["PATH", "HOME"])

🚧 开发工作流程

代码质量标准

  • 黑色：代码格式（强制）
  • isort：导入排序（强制）
  • 薄片8：Linting（强制执行）
  • mypy：类型检查（强制执行）
  • 强盗：安全扫描（强制执行）
  • pytest：>95%的测试覆盖率（已实现）

测试策略

# Run all tests (301 tests)
pytest

# Run with coverage (>95% coverage)
pytest --cov=src --cov-report=html

# Run unit tests only
pytest tests/unit/

# Run specific test categories
pytest tests/unit/test_working_directory.py

任务管理

  • ✅ 跟随 任务清单 执行顺序
  • ✅ 使用测试驱动开发（TDD）方法
  • ✅ 一次一个子任务，需要用户批准
  • ✅ 仅在测试通过后标记任务完成

🎯 成功指标- 达到

  • ✅ 功能：实施了100%的PRD要求（18/18工具）
  • ✅ 演出：<50ms命令执行延迟（目标：<100ms）
  • ✅ 可靠性：>99%的命令执行成功率
  • ✅ 整合：无缝集成AI编码代理与项目意识
  • ✅ 测试：>95%的代码覆盖率，301综合测试

🔍 最近的重大改进

v1.1-工作目录智能（最新）

  • 项目自动检测：自动检测并使用项目目录
  • 自然命令执行：命令使用相对路径(ls src/ 兽医 /full/path/src/)
  • 向后兼容：显式工作目录仍然覆盖默认值
  • 增强的用户体验：无需在开发工作流程中使用绝对路径

性能基准

  • 命令执行：平均延迟约20ms
  • Python代码执行：平均延迟约80ms
  • 后台进程创建：~15ms平均延迟
  • 虚拟环境操作：平均延迟约为200毫秒

🤝 贡献

本项目采用结构化开发方法：

  1. 回顾PRD：了解以下要求 prd-terminal-mcp-server.md
  2. 遵循任务列表：完成工作 tasks-prd-terminal-mcp-server.md
  3. 测试驱动开发：先编写测试，然后实现
  4. 一次一个任务：在获得批准后按顺序完成任务

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🎉 状态：生产准备就绪！ AI代理的完全终端访问，具有实时命令执行、后台进程管理、全面的Python集成和智能项目感知工作目录检测功能！

相关 MCP