file-control-mcp

🚀 增强目录上下文MCP服务器

增强目录上下文MCP服务器是一个全面的模型上下文协议（MCP）服务器，它为像Claude这样的AI助手提供了高级的目录分析和文件管理功能。该服务器将目录上下文提取与完整的文件编辑功能相结合，是代码分析、项目管理和文件操作的强大工具。

🚀 快速开始

快速设置

1. 安装依赖：npm install
2. 添加到你的Claude桌面配置中：

{
  "mcpServers": {
    "directory-context": {
      "command": "node",
      "args": ["path/to/server.js"]
    }
  }
}

✨ 主要特性

🔍 目录分析

• 完整的目录结构：获取任何目录的详细树状视图及元数据
• 智能项目分析：自动检测项目类型并总结上下文
• 智能文件搜索：支持跨多种文件类型的正则表达式和基于文本的搜索
• Git集成：提取仓库上下文、提交历史和工作目录状态
• 文件统计：全面分析文件类型、大小和修改日期

📝 文件操作

• 创建文件：生成具有指定内容的新文件
• 更新文件：支持正则表达式的复杂搜索和替换操作
• 追加内容：以格式化选项将内容添加到现有文件中
• 删除文件：可选择创建备份后删除文件
• 重命名/移动文件：具有冲突检测功能的文件重定位和重命名
• 目录管理：递归创建目录结构

其他特性

• 智能搜索：支持正则表达式，可在多个文件中查找代码或文本
• Git集成：查看提交、分支和更改
• 安全操作：自动备份和事务回滚

📦 安装指南

前提条件

• Node.js 18.0.0或更高版本
• npm或yarn包管理器

安装步骤

1. 克隆或下载MCP服务器文件。
2. 安装依赖：

npm install

3. 配置你的MCP客户端（如Claude Desktop）以使用此服务器：

Claude桌面配置

添加到你的claude_desktop_config.json文件中：

{
  "mcpServers": {
    "directory-context": {
      "command": "node",
      "args": ["path/to/your/server.js"],
      "cwd": "your-default-working-directory"
    }
  }
}

替代配置

使用提供的mcp-json-config.json作为模板，并相应地更新路径。

💻 使用示例

设置工作目录

在使用任何功能之前，设置你的工作目录：

set_working_directory(directory="/path/to/your/project")

目录分析工具

获取目录结构

get_directory_structure(
  max_depth=10,           // 最大遍历深度
  include_hidden=false,   // 是否包含隐藏文件/目录
  file_types=[".js", ".py", ".md"]  // 按文件扩展名过滤
)

分析项目上下文

analyze_project_context(
  include_code_analysis=true,    // 是否包含复杂度分析
  focus_files=["specific_file.js"]  // 关注特定文件
)

搜索文件

search_files(
  query="function myFunction",  // 搜索查询
  file_types=[".js", ".ts"],   // 要搜索的文件类型
  is_regex=false,              // 是否使用正则表达式匹配
  max_results=50               // 最大结果数
)

获取Git上下文

get_git_context(
  include_diff=true,     // 是否包含工作目录更改
  commit_count=10        // 最近提交的数量
)

文件管理工具

创建文件

create_file(
  path="src/new-component.js",
  content="const MyComponent = () => { ... }",
  encoding="utf8",
  overwrite=false
)

更新文件

update_file(
  path="src/config.js",
  updates=[
    {
      search: "oldValue: 'old'",
      replace: "newValue: 'new'",
      regex: false,
      all: true
    }
  ],
  backup=true
)

追加内容到文件

append_to_file(
  path="README.md",
  content="## New Section\nContent here...",
  newline_before=true
)

删除文件

delete_file(
  path="old-file.js",
  backup=true  // 创建.deleted备份
)

重命名/移动文件

rename_file(
  old_path="old-name.js",
  new_path="new-name.js",
  overwrite=false
)

创建目录

create_directory(
  path="src/components/new-feature",
  recursive=true
)

批量操作

原子执行多个操作：

batch_file_operations(
  operations=[
    {
      operation: "create",
      params: {
        path: "src/component.js",
        content: "export default () => {}"
      }
    },
    {
      operation: "update",
      params: {
        path: "src/index.js",
        updates: [...]
      }
    }
  ],
  rollback_on_error=true
)

📚 详细文档

项目类型检测

服务器根据配置文件自动检测项目类型：

• Node.js/JavaScript：package.json
• Python：requirements.txt
• Rust：Cargo.toml
• Go：go.mod
• Java：pom.xml、build.gradle
• PHP：composer.json
• Ruby：Gemfile
• Docker：Dockerfile、docker-compose.yml
• 还有更多...

文件优先级检测

服务器自动识别重要文件：

• 配置文件（如package.json、config.js等）
• 入口点（如index.js、main.py、app.js）
• 文档（如README.md、docs）
• Docker文件
• 环境文件（如.env）

资源暴露

重要文件会自动作为MCP资源暴露，使AI助手无需显式的文件读取请求即可轻松访问。

错误处理和安全特性

• 备份创建：对破坏性操作自动创建备份
• 冲突检测：防止意外覆盖
• 事务回滚：错误发生时可完全回滚批量操作
• 路径验证：确保操作在工作目录范围内进行
• 详细错误消息：提供全面的错误报告以进行调试

🔧 技术细节

API参考

核心工具

| 工具 | 描述 | 必需参数 | |------|------|----------| | set_working_directory | 设置工作目录 | directory | | get_directory_structure | 获取目录树 | 无 | | get_file_contents | 读取多个文件 | files | | search_files | 在文件中搜索 | query | | analyze_project_context | 分析项目 | 无 | | get_git_context | 获取Git仓库信息 | 无 |

文件操作

| 工具 | 描述 | 必需参数 | |------|------|----------| | create_file | 创建新文件 | path、content | | update_file | 更新现有文件 | path、updates | | append_to_file | 追加内容到文件 | path、content | | delete_file | 删除文件 | path | | rename_file | 重命名/移动文件 | old_path、new_path | | create_directory | 创建目录 | path | | batch_file_operations | 批量操作 | operations |

配置选项

服务器配置

• 工作目录：通过set_working_directory或在初始化时设置
• 文件类型过滤：可配置文件扩展名过滤
• 搜索限制：可配置最大搜索结果数
• 备份策略：对破坏性操作可选择创建备份

MCP客户端配置

在你的MCP客户端中配置服务器，使用适当的命令和参数。服务器通过标准输入输出进行通信，无需额外的网络配置。

开发与贡献

项目结构

enhanced-directory-context-mcp/
├── server.js                 # 主要的MCP服务器实现
├── package.json             # Node.js包配置
├── mcp-json-config.json     # 示例MCP客户端配置
└── README.md               # 本说明文档

依赖项

• @modelcontextprotocol/sdk：核心MCP功能
• Node.js内置模块：fs、path、child_process

开发模式运行

npm run dev

这将启动服务器，并启用Node.js检查器以进行调试。

📄 许可证

本项目采用MIT许可证，详情请参阅package.json。

支持与问题反馈

如有问题、功能请求或想要贡献代码，请参考仓库的问题跟踪器。

⚠️ 重要提示

此MCP服务器提供强大的文件系统访问功能。请确保你信任AI助手，并了解正在执行的操作，特别是像文件删除或修改这样的破坏性操作。