凌宇博客

标签： 调试

  • 解决MCP Server SSH远程路径配置问题：macOS与Linux路径差异

    解决MCP Server SSH远程路径配置问题：macOS与Linux路径差异

    在开发基于Model Context Protocol (MCP)的博客管理工具时，遇到了一个典型的跨平台路径配置问题。本文详细记录了问题的发现、分析和解决过程，希望能帮助遇到类似问题的开发者。

    问题现象

    MCP Server astro-blog-ssh 在启动时报错：

    failed to initialize MCP client for astro-blog-ssh: MCP 服务启动失败: Error: Command failed: ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 mkdir -p '/home/mahongliang/workspace/astro-site/content/blog' && test -d '/home/mahongl...

    问题分析

    1. 初步排查

    首先确认SSH密钥文件权限正确（600），SSH连接本身能够正常建立：

    ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "echo 'SSH connection successful'"

    2. 深入诊断

    执行完整的目录创建命令时发现问题：

    ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "mkdir -p '/home/mahongliang/workspace/astro-site/content/blog' && test -d '/home/mahongliang/workspace/astro-site/content/blog'"

    返回错误：mkdir: /home/mahongliang: Operation not supported

    3. 根本原因

    通过查询远程服务器的用户主目录：

    ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "echo \$HOME"

    发现返回结果是：/Users/mahongliang

    这说明远程服务器实际上是macOS系统，而不是假设的Linux系统！

    • Linux系统：用户主目录为 `/home/ `
    • macOS系统：用户主目录为 `/Users/ `

    解决方案

    将MCP配置中的远程路径从Linux路径改为macOS路径：

    错误配置：

    "BLOG_REMOTE_POSTS_DIR": "/home/mahongliang/workspace/astro-site/content/blog"

    正确配置：

    "BLOG_REMOTE_POSTS_DIR": "/Users/mahongliang/workspace/astro-site/content/blog"

    验证修复

    使用修正后的路径测试：

    ssh -p 7122 -o BatchMode=yes -o StrictHostKeyChecking=accept-new -i /Users/mhl/.ssh/id_ed25519 mahongliang@111.228.52.26 "mkdir -p '/Users/mahongliang/workspace/astro-site/content/blog' && test -d '/Users/mahongliang/workspace/astro-site/content/blog' && echo 'Directory check successful'"

    返回：Directory check successful

    MCP Server成功启动：

    Astro Blog SSH MCP Server 已启动 -> mahongliang@111.228.52.26:/Users/mahongliang/workspace/astro-site/content/blog

    经验总结

    1. 不要假设远程系统类型：在配置远程路径时，务必确认远程操作系统的实际类型
    2. 动态验证路径：使用 echo $HOME 命令获取远程用户的实际主目录路径
    3. 跨平台兼容性：在开发工具时考虑不同操作系统的路径差异
    4. 详细的错误日志：保留完整的错误信息有助于快速定位问题

    这个问题虽然简单，但体现了开发中常见的"假设陷阱"。通过系统性的排查和验证，我们能够快速找到并解决问题。

    相关技术栈

    • MCP (Model Context Protocol): 标准化的AI上下文协议
    • Astro: 现代化静态站点生成器
    • SSH: 安全远程连接协议
    • macOS/Linux: 不同的操作系统路径约定