Tea 文件操作 MCP 服务器

一个 Model Context Protocol (MCP) 服务器，通过调用 NestJS API 提供文件操作工具，专为 AI 代码助手设计。

功能特性

🔧 可用工具

1. read_file - 读取文件内容
2. write_file - 写入或创建文件
3. delete_file - 删除文件
4. list_directory - 列出目录内容
5. modify_file - 修改文件内容（替换）⭐
6. read_all_code - 读取所有代码文件并拼接 ⭐

🔒 安全设计

• 所有操作通过 NestJS API 执行
• 文件操作限制在 workspace 目录内
• 防止路径穿越攻击
• 返回相对路径，不暴露服务器信息

安装

npm install

配置

环境变量

在使用前，可以设置以下环境变量：

# API 服务器地址（默认: http://localhost:3000/api/files）
export API_BASE_URL=http://localhost:3000/api/files

前置条件

确保 NestJS 文件操作服务器正在运行：

cd ../file-operations-server
npm run dev
# 服务将运行在 http://localhost:3000

在 Cursor / Claude Desktop 中使用

1. Cursor 配置

在 Cursor 的 MCP 设置中添加：

{
  "mcpServers": {
    "tea-file-operations": {
      "command": "node",
      "args": ["/absolute/path/to/tea-file-operations-mcp-server/src/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:3000/api/files"
      }
    }
  }
}

2. Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tea-file-operations": {
      "command": "node",
      "args": ["/absolute/path/to/tea-file-operations-mcp-server/src/index.js"],
      "env": {
        "API_BASE_URL": "http://localhost:3000/api/files"
      }
    }
  }
}

3. 使用 npx（推荐）

如果发布到 npm，可以直接使用：

{
  "mcpServers": {
    "tea-file-operations": {
      "command": "npx",
      "args": ["-y", "tea-file-operations-mcp-server"],
      "env": {
        "API_BASE_URL": "http://localhost:3000/api/files"
      }
    }
  }
}

工具详解

1. read_file

读取指定文件的内容。

参数：

• path (string): 文件路径（相对于 workspace 目录）

示例：

{
  "path": "demo-project/src/index.js"
}

返回：

{
  "path": "demo-project/src/index.js",
  "content": "文件内容...",
  "message": "文件读取成功"
}

2. write_file

写入或创建文件。

参数：

• path (string): 文件路径
• content (string): 文件内容

示例：

{
  "path": "demo-project/src/new-file.js",
  "content": "console.log('Hello, World!');"
}

3. delete_file

删除指定文件。

参数：

• path (string): 文件路径

示例：

{
  "path": "demo-project/temp.txt"
}

4. list_directory

列出目录内容。

参数：

• path (string, optional): 目录路径，默认为 "."（根目录）

示例：

{
  "path": "demo-project"
}

返回：

{
  "path": "demo-project",
  "workspaceRoot": "/absolute/path/to/workspace",
  "files": [
    { "name": "package.json", "isDirectory": false, "isFile": true },
    { "name": "src", "isDirectory": true, "isFile": false }
  ],
  "tree": "demo-project/\n├── package.json\n└── src/",
  "message": "目录列表获取成功"
}

5. modify_file ⭐

用新内容替换文件中的指定旧内容。

参数：

• path (string): 文件路径
• oldContent (string): 要替换的旧内容
• newContent (string): 替换后的新内容

示例：

{
  "path": "demo-project/src/index.js",
  "oldContent": "const greeting = \"Hello, World!\";",
  "newContent": "const greeting = \"你好，世界！\";"
}

返回：

{
  "path": "demo-project/src/index.js",
  "message": "文件修改成功",
  "replaced": true,
  "occurrences": 1,
  "success": true
}

6. read_all_code ⭐

递归读取项目中所有代码文件并拼接，用于 AI 代码检查和分析。

参数：

• path (string, optional): 项目路径，默认为 "."
• extensions (string[], optional): 文件扩展名列表
• excludeDirs (string[], optional): 排除的目录列表

默认扩展名： .html, .htm, .css, .js, .json, .vue, .ts, .jsx, .tsx, .md, .py, .java, .go, .rs, .c, .cpp, .h

默认排除目录： node_modules, dist, build, target, .git, .idea, .vscode, coverage

示例：

{
  "path": "demo-project",
  "extensions": [".js", ".json", ".md"],
  "excludeDirs": ["node_modules", "dist"]
}

返回：

{
  "projectPath": "demo-project",
  "content": "# 项目文件结构和代码内容\n\n## 文件: src/index.js\n\n```js\nconsole.log('Hello');\n```\n\n",
  "fileCount": 5,
  "totalSize": 1024,
  "message": "成功读取 5 个文件，总大小 1.00 KB"
}

使用场景：

• 🔍 AI 代码审查
• 📊 项目代码分析
• ✅ 代码质量检查
• 🔄 批量代码处理

架构说明

┌─────────────────┐
│  AI Assistant   │
│  (Cursor/Claude)│
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────┐
│   MCP Server    │
│  (This Package) │
└────────┬────────┘
         │ HTTP API
         ▼
┌─────────────────┐
│  NestJS Server  │
│ (File Operations)│
└────────┬────────┘
         │ File System
         ▼
┌─────────────────┐
│   Workspace     │
│   Directory     │
└─────────────────┘

开发

本地测试

# 启动 NestJS 服务器（在另一个终端）
cd ../file-operations-server
npm run dev

# 测试 MCP 服务器
node src/index.js

调试

MCP 服务器会将日志输出到 stderr，不会干扰 stdio 通信：

console.error("调试信息");

故障排除

1. API 连接失败

确保 NestJS 服务器正在运行：

curl http://localhost:3000/api/files/health

2. 权限错误

确保 API_BASE_URL 环境变量正确设置。

3. 文件不存在

所有路径都相对于 workspace 目录，使用 list_directory 查看可用文件。

与 NestJS 服务器的关系

此 MCP 服务器是 NestJS 文件操作服务器的客户端包装器：

• NestJS 服务器：提供 HTTP API，处理实际的文件操作
• MCP 服务器：将 API 包装为 MCP 工具，供 AI 助手使用

优势：

• ✅ 集中式文件操作管理
• ✅ 更好的安全控制
• ✅ 易于扩展和维护
• ✅ 支持远程文件操作
• ✅ 统一的错误处理

许可证

MIT

相关项目

• file-operations-server - NestJS 文件操作 API 服务器