MCP Server for Software Development

用于软件开发的 MCP 服务

一个为 Claude 桌面版提供文件系统和 Shell 访问能力的 MCP 服务。

架构

Claude ←→ MCP Server ←→ Unix Socket ←→ Filesystem Daemon
       (2 tools)      (JSON RPC)     (file operations, shell)

主要优势

• ✅ 只需一次权限提示（原本需要 15+ 个工具，现在只需 2 个）
• ✅ 环境控制（守护进程在正确的虚拟环境和目录中运行）
• ✅ 终端可见性（所有操作都会记录日志和上下文）
• ✅ 动态发现（操作会自动生成文档）
• ✅ 丰富的错误处理（提供详细错误信息和建议）
• ✅ 类型安全（参数架构带有校验）

快速开始

1. 启动文件系统守护进程（在目标目录中）：

   python fs_access.py           # Normal mode
   python fs_access.py --verbose # Verbose mode (shows shell output, file contents, edit details)
   

2. 通过配置将 Claude 连接到 MCP 服务：

   {
     ...
     "mcpServers": {
       "Dev": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "fastmcp",
           "$path/mcp-server-dev/mcp_server.py"
         ]
       }
     }
   }
   

3. 测试集成：

   • 检查 Claude Desktop 的“搜索和工具”菜单中是否能看到 Dev
   • 运行文件系统访问服务，并与 Claude 对话，确认它能否使用这些工具。

Claude 可用的 MCP 工具

1. get_available_operations()

• 用途：发现可用的文件系统操作及其架构
• 返回值：包含操作架构的字典，其中包括类型、描述和默认值

2. execute_fs_operation(operation, params)

• 用途：通过守护进程执行文件系统操作
• 参数：
  • operation：操作名称（字符串）
  • params：操作参数（字典）
• 返回值：包含成功状态、结果/错误和日志的字典

可用操作

文件操作

ls(path=".")

列出指定路径中的文件和目录。

• 示例：execute_fs_operation("ls", {})
• 示例：execute_fs_operation("ls", {"path": "/tmp"})

read_file(path)

以 UTF-8 字符串形式读取文件内容。

• 示例：execute_fs_operation("read_file", {"path": "README.md"})

write_file(path, content)

将内容写入文件（新建或覆盖）。

• 示例：execute_fs_operation("write_file", {"path": "test.txt", "content": "Hello world!"})

edit_file(path, changes)

对文件执行搜索和替换操作。

• 示例：

execute_fs_operation("edit_file", {
    "path": "config.py",
    "changes": [
        ["DEBUG = False", "DEBUG = True"],
        ["localhost", "production.com"]
    ]
})

目录管理

mkdir(path)

创建目录以及所有必要的父目录。

• 示例：execute_fs_operation("mkdir", {"path": "project/src/utils"})

rmdir(path)

递归删除目录及其所有内容（请谨慎使用！）。

• 示例：execute_fs_operation("rmdir", {"path": "temp_project"})

文件和目录管理

rm(path)

删除文件或空目录。

• 示例：execute_fs_operation("rm", {"path": "unwanted_file.txt"})
• 示例：execute_fs_operation("rm", {"path": "empty_dir"})（仅限空目录）

mv(src, dst)

移动或重命名文件和目录。

• 示例：execute_fs_operation("mv", {"src": "old_name.txt", "dst": "new_name.txt"})
• 示例：execute_fs_operation("mv", {"src": "temp", "dst": "project/temp"})

Shell 命令

shell(command, args=[], timeout=30)

执行 Shell 命令并返回 stdout、stderr 和 exit_code。

• 示例：execute_fs_operation("shell", {"command": "git", "args": ["status"]})
• 示例：execute_fs_operation("shell", {"command": "python", "args": ["--version"]})
• 示例：execute_fs_operation("shell", {"command": "find", "args": [".", "-name", "*.py"], "timeout": 60})
• 返回值：{"stdout": "...", "stderr": "...", "exit_code": 0, "command": "...", "working_directory": "..."}

错误处理

• 连接错误：守护进程未运行 → 提供实用提示
• 无效操作：列出可用操作及其签名
• 文件错误：提供详细的错误类型（FileNotFoundError、PermissionError 等）
• 参数错误：进行类型校验并检查必填项

Claude 的使用模式

1. 发现：调用 get_available_operations() 查看可用内容
2. 执行：调用 execute_fs_operation(operation_name, params_dict)

核心文件

• fs_access.py - 包含所有操作的文件系统守护进程
• mcp_server.py - 提供 Claude 接口的 MCP 服务
• socket_protocol.py - Unix 套接字通信层
• shell_examples.py - Shell 命令示例