使用说明

🐧 Linux MCP服务器聊天机器人

一个基于人工智能的Linux诊断聊天机器人，使用 克劳德通过谷歌顶点AI 通过以下方式在任何Linux主机（本地或远程）上运行系统诊断 Linux MCP服务器.

✨ 特性

🤖 克劳德·十四行诗4.5 -与Claude Code CLI的模型和身份验证相同
🌐 远程和本地诊断 -基于SSH访问任何Linux主机
⚡ 快速响应 -并行工具执行的2-3秒查询响应
🔧 19诊断工具 -系统信息、CPU、内存、磁盘、网络、服务、进程、日志等
💬 自然语言接口 -用简单的英语提问
🔄 多步推理 -用于复杂诊断的LangChain ReAct代理

🚀 快速开始

先决条件

Python 3.10+
Google Cloud凭据（应用程序默认凭据）
已安装Linux MCP服务器
通过Google Vertex AI访问Claude（与Claude Code CLI相同）

安装

克隆存储库

git clone <repository-url>
cd linux-mcp-server-chatbot

创建虚拟环境并安装依赖项

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

安装Linux MCP服务器
```
pip install linux-mcp-server
```

配置环境

cp .env.example .env
nano .env  # Edit configuration

最低配置要求：

MODEL_ENDPOINT=https://vertex-ai-anthropic
MODEL_NAME=claude-sonnet-4-5@20250929
GOOGLE_PROJECT_ID=your-gcp-project-id
GOOGLE_LOCATION=us-east5
MCP_COMMAND=/path/to/linux-mcp-server
LINUX_MCP_USER=remote-ssh-username  # For remote hosts

为远程主机配置SSH（推荐）

mkdir -p ~/.ssh/controlmasters
cat >> ~/.ssh/config << 'EOF'

Host *
    ControlMaster auto
    ControlPath ~/.ssh/controlmasters/%r@%h:%p
    ControlPersist 10m
EOF

这实现了SSH连接的重用，大大加快了并行诊断查询的速度。

启动聊天机器人
```
./start-chatbot.sh
```
聊天机器人将在您的浏览器中打开http://localhost:8501

📖 用法

查询示例

本地系统诊断：

What's the system hostname and OS version?
Show me CPU and memory usage
Check disk space
List running services

远程主机诊断：

Check health status of demo.example.local
Show me failed services on prod-server
What's using disk space on /var on web-server?
Find high memory processes on db-server

多步骤调查：

The web server is slow, investigate why
Find what's consuming the most CPU
Check for errors in the last hour
Diagnose network connectivity issues

有关更多示例，请参见 docs/EXAMPLE_QUERIES.md

🏗️ 建筑

┌─────────────────────────────────────────────┐
│         Streamlit Web UI (app.py)           │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  LangChain ReAct Agent (create_agent)       │
└──────────┬──────────────────────┬───────────┘
           │                      │
           ▼                      ▼
┌─────────────────────┐  ┌──────────────────┐
│ ClaudeVertexChat    │  │  19 MCP Tools    │
│ (Vertex AI wrapper) │  │  (Structured     │
│                     │  │   Tool)          │
└─────────┬───────────┘  └────────┬─────────┘
          │                       │
          ▼                       ▼
┌─────────────────────┐  ┌──────────────────┐
│ Anthropic Vertex    │  │ LinuxMCPClient   │
│ SDK                 │  │ (JSON-RPC/stdio) │
└─────────┬───────────┘  └────────┬─────────┘
          │                       │
          ▼                       ▼
┌─────────────────────┐  ┌──────────────────┐
│ Google Cloud ADC    │  │ Linux MCP Server │
└─────────┬───────────┘  └────────┬─────────┘
          │                       │
          ▼                       ▼
┌─────────────────────┐  ┌──────────────────┐
│ Vertex AI API       │  │ SSH to Remote    │
│ (us-east5)          │  │ Linux Hosts      │
└─────────────────────┘  └──────────────────┘

📁 项目结构

linux-mcp-server-chatbot/
├── README.md                    # This file
├── QUICKSTART.md                # Quick start guide
├── requirements.txt             # Python dependencies
├── .env.example                 # Environment template
├── .env                         # Your configuration (git-ignored)
├── .gitignore                   # Git ignore rules
│
├── app.py                       # Main Streamlit application
├── mcp_client.py                # MCP protocol client (thread-safe JSON-RPC)
├── claude_vertex_wrapper.py     # LangChain wrapper for Claude via Vertex AI
├── start-chatbot.sh             # Launcher script with verification
│
├── docs/                        # Documentation
│   ├── TROUBLESHOOTING.md       # Common issues and solutions
│   ├── EXAMPLE_QUERIES.md       # 100+ example queries
│   └── archive/                 # Historical documentation
│
├── tests/                       # Test scripts
│   ├── test_setup.py            # Setup verification (used by start-chatbot.sh)
│   ├── test_mcp_direct.py       # Test MCP client directly
│   ├── test_mcp_parallel.py     # Test parallel tool execution
│   └── ...                      # Other test scripts
│
└── scripts/                     # Utility scripts
    ├── port-forward.sh          # Port forwarding helper
    └── run-debug.sh             # Debug mode launcher

🔧 配置

环境变量

变量	描述	示例	必填
`MODEL_ENDPOINT`	API端点标识符	`https://vertex-ai-anthropic`	是的
`MODEL_NAME`	克劳德型号名称	`claude-sonnet-4-5@20250929`	是的
`GOOGLE_PROJECT_ID`	GCP项目ID	`your-project-id`	是的
`GOOGLE_LOCATION`	Vertex AI的GCP区域	`us-east5`	是的
`MCP_COMMAND`	linux mcp服务器的路径	`/home/user/.local/bin/linux-mcp-server`	是的
`LINUX_MCP_USER`	远程主机的SSH用户名	`localuser`	可选
`REQUEST_TIMEOUT`	API请求超时（秒）	`300`	可选

Vertex AI上Claude的可用区域

✅ 美国东部5 （测试和工作）
欧洲西部1 （可以工作）
亚洲-东南亚1 （可以工作）

注： Claude不在 us-central1 在Vertex AI上。

🔍 可用的诊断工具

聊天机器人可以通过MCP服务器访问19个Linux诊断工具：

类别	工具
系统	`get_system_information`, `get_hardware_information`
中央处理器	`get_cpu_information`
记忆	`get_memory_information`
磁盘	`get_disk_usage`, `list_block_devices`, `list_directories`, `list_files`
网络	`get_network_interfaces`, `get_network_connections`, `get_listening_ports`
服务	`list_services`, `get_service_status`, `get_service_logs`
过程	`list_processes`, `get_process_info`
日志	`get_journal_logs`, `get_audit_logs`, `read_log_file`, `read_file`

所有工具均支持 host 用于通过SSH远程执行的参数。

🛠️ 故障排除

常见问题

1.远程主机超时错误

症状： 并行调用时工具超时，显示“错误：等待MCP响应超时”

解决方案：

配置SSH ControlMaster以实现连接重用（请参阅安装步骤5）
聊天机器人现在包括线程安全的并行执行，超时120秒

2.“权限被拒绝”顶点AI错误

症状： 启动聊天机器人时发生GCP身份验证错误

解决方案：

gcloud auth application-default login

3.“模型在区域内不可用”

症状： 在某些地区尝试使用Claude时出错

解决方案： 使用 GOOGLE_LOCATION=us-east5 在.env中（Claude在us-central中不可用1）

4.克劳德产生幻觉而不是调用工具

症状： 聊天机器人返回看似合理但虚假的数据

解决方案： 清除Streamlit缓存并重新启动：

pkill -f streamlit
rm -rf ~/.streamlit/cache
./start-chatbot.sh

5.调试输出中未出现工具

症状： [DEBUG] Built 0 tools 启动输出

解决方案： 验证MCP_COMMAND指向正确的linux MCP服务器二进制文件

有关更多故障排除，请参阅 docs/TROUBLESHOOTING.md

💡 运作原理

认证

聊天机器人使用 与Claude Code CLI相同的身份验证:

Google Cloud应用程序默认凭据（ADC）
不需要API密钥
向您的GCP组织收取的费用

工具调用流程

用户用自然语言提问
朗链代理 接收问题并计划调用哪些工具
克劳德（通过顶点AI） 做出工具调用决策（尽可能并行）
MCP客户端 通过Linux MCP Server子进程执行工具（线程安全）
Linux MCP服务器 在本地或通过SSH运行命令
结果返回克劳德进行合成
克劳德 通过分析生成自然语言响应
用户在Streamlit UI中看到格式化的答案

并行工具执行

当Claude同时调用多个工具时：

所有调用都以并行线程的方式发送到MCP服务器
MCP客户端使用与唯一ID匹配的线程安全请求/响应
SSH ControlMaster重用连接以提高速度（每次呼叫0.03秒，而1-2秒）
典型的7工具查询总共在1.5-2秒内完成

📊 演出

度量	值
响应时间	2-3秒（与克劳德·维特斯一起）
工具执行	7个平行工具在约1.5秒内完成
SSH开销	每次通话0.03秒（使用ControlMaster）
模型	与Claude Code CLI相同
成本	每次查询约0.01-0.03美元（组织账单）

与本地模型比较：

上一个：每次查询30分钟以上（CPU上24B Mistral）
当前：每个查询2-3秒（Claude通过Vertex AI）
~加速900倍！

🎯 关键实施细节

线程安全MCP客户端

这 mcp_client.py 包括并行工具执行的关键修复：

使用锁进行线程安全的stdin写入
具有唯一请求ID的响应字典
基于轮询的响应检索（避免队列竞争条件）
远程SSH操作超时120秒

克劳德顶点包装

这 claude_vertex_wrapper.py 提供LangChain集成：

实现 bind_tools() 用于工具绑定
将LangChain工具转换为Anthropic格式
处理从Claude响应中提取工具调用
管理ToolMessage、AIMessage和HumanMessage的转换

SSH配置

SSH ControlMaster显著提高了性能：

首次连接：约1-2秒
后续连接：~0.03秒（重复使用插座）
上次使用后持续10分钟
实现真正的并行执行

🙏 致谢

Linux MCP服务器 -通过MCP的Red Hat Linux诊断工具
LangChain -代理框架
安thropic克劳德 -通过Vertex AI建立AI模型
溪流 -Web UI框架
谷歌云顶点AI -人工智能管理平台

📞 支持

问题：通过GitHub Issues报告错误和请求功能
文档：参见 QUICKSTART.md 和 docs/
例子：参见 docs/EXAMPLE_QUERIES.md
测试：运行 python tests/test_setup.py 验证您的设置

内置于❤️ 通过谷歌顶点AI使用克劳德·松内特4.5