MCP Source Server

🚀 MCP 服务器

本项目旨在借助现有的 AI 助手（如 Claude Desktop）辅助开发，打破受限于 Cursor 或 Windsurf 等需额外 API 成本工具的局面。搭建此 MCP 服务器后，AI 助手能自动搜索项目相关文件、分析代码库并给出智能修正建议，为已订阅 AI 服务的用户减少重复的复制粘贴工作，让开发流程更高效。

🚀 快速开始

安装

# 克隆仓库
git clone git@hgithub.com/Chakotay-Lee/mcp-source-server
cd mcp-source-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

Claude Desktop 配置

将以下配置添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "source-code-server": {
      "command": "node",
      "args": ["/path/to/your/mcp-source-server/dist/index.js"],
      "env": {
        "MCP_WORKSPACE_DIR": "/path/to/your/workspace"
      }
    }
  }
}

请将 /path/to/your/mcp-source-server 替换为该项目的实际路径，/path/to/your/workspace 替换为你期望的工作区目录。

✨ 主要特性

核心文件操作

• 读取文件：安全读取有大小限制的源代码文件。
• 写入文件：可选择备份，创建和更新文件。
• 列出文件：浏览带有元数据的目录内容。
• 流式写入：高效处理大文件写入。

🆕 增强操作（v0.2.1）

• 删除文件：安全删除文件并自动备份。
• 重命名/移动文件：重命名文件或在目录间移动文件。
• 部分写入：经 LLM 优化的功能，可更新文件特定部分而无需重写整个文件。

🔒 安全特性

• 目录遍历保护：防止访问工作区外的内容。
• 文件扩展名白名单：仅允许批准的文件类型。
• 路径黑名单：阻止访问敏感目录。
• 大小限制：防止过度的文件操作。
• 并发操作限制：保护系统资源。

📋 可用工具

基本操作

• read_source_file - 读取文件内容
• write_source_file - 向文件写入内容
• list_source_files - 列出目录中的文件
• stream_write_source_file - 大文件的流式写入

🆕 增强操作

• delete_source_file - 删除文件并可选择备份
• rename_source_file - 重命名或移动文件并备份
• partial_write_source_file - 更新文件特定内容（LLM 优化）

实用工具

• get_server_stats - 获取服务器状态和统计信息

🔧 配置

环境变量

• MCP_WORKSPACE_DIR：设置工作区目录（默认：./workspace）

安全配置

服务器包含内置的安全配置：

允许的文件扩展名

• 编程：.js, .ts, .jsx, .tsx, .py, .cpp, .c, .h 等。
• 网页：.html, .css, .scss, .json, .xml, .yaml 等。
• 文档：.md, .txt, .rst, .adoc
• 模板：.template, .example, .sample, .config
• 无扩展名：Dockerfile, Makefile, .gitignore 等。

黑名单路径

• .. - 防止目录遍历
• .git/ - Git 仓库文件
• node_modules/ - 依赖目录
• .env. - 环境文件（模板除外）
• secrets/ - 机密目录
• 系统文件（.DS_Store, Thumbs.db）

💻 使用示例

基础用法

// 读取文件
await callTool('read_source_file', { filePath: 'src/index.js' });

// 写入文件
await callTool('write_source_file', {
  filePath: 'src/new-file.js',
  content: 'console.log("Hello World");',
  createBackup: true
});

// 列出文件
await callTool('list_source_files', { dirPath: 'src' });

高级用法

// 删除文件（带备份）
await callTool('delete_source_file', {
  filePath: 'old-file.js',
  createBackup: true
});

// 重命名/移动文件
await callTool('rename_source_file', {
  oldPath: 'old-name.js',
  newPath: 'src/new-name.js',
  createBackup: true
});

// LLM 优化的部分更新
await callTool('partial_write_source_file', {
  filePath: 'utils.js',
  oldContent: 'function oldFunction() { return "old"; }',
  newContent: 'function newFunction() { return "updated"; }'
});

🛡️ 安全说明

允许的开发文件

✅ .gitignore, .env.template, Dockerfile, Makefile, package.json, tsconfig.json

受保护的文件

🔒 .env, .env.local, .env.production, .git/config, node_modules/, secrets/

🧪 测试

# 运行所有测试
npm test

# 运行特定测试
npm test -- --testNamePattern="should allow development configuration files"

# 运行并生成覆盖率报告
npm run test:coverage

🔄 备份系统

服务器会在 .backups 目录中自动创建带时间戳的备份：

• 格式：filename.timestamp.backup
• 位置：workspace/.backups/ 建议进行自动清理。

📊 性能特性

• 并发操作限制：防止系统过载。
• 文件大小限制：默认每个文件 10MB。
• LLM 优化：部分写入减少小更改的文件 I/O。
• 流处理：高效处理大文件。

🤝 贡献代码

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

📝 许可证

[此处填写你的许可证]

🆕 变更日志

v0.2.1

• ✨ 新增文件删除功能
• ✨ 新增文件重命名/移动功能
• ✨ 新增 LLM 优化的部分写入功能
• 🔧 修复 .env.template 文件访问问题
• 🔧 通过精确模式匹配增强安全性
• 🧪 全面的测试套件（21 个测试）

v0.1.0

• 🎉 初始版本，具备基本文件操作功能
• 🔒 安全特性和路径验证
• 📚 MCP 协议实现