内容
# 增强型目录上下文 MCP 服务器
**简而言之**: 一个强大的 MCP 服务器，为 AI 助手提供完整的目录分析和文件编辑能力。
## 功能
- 📁 **分析目录** - 获取项目结构，查找文件，搜索内容
- ✏️ **编辑文件** - 创建、更新、删除、重命名文件和文件夹
- 🔍 **智能搜索** - 使用正则表达式支持在多个文件中查找代码/文本
- 🔄 **Git 集成** - 查看提交、分支和更改
- 🛡️ **安全操作** - 自动备份和事务回滚
## 快速设置
1. 安装依赖: `npm install`
2. 添加到你的 Claude Desktop 配置中：
```json
{
"mcpServers": {
"directory-context": {
"command": "node",
"args": ["path/to/server.js"]
}
}
}
```
## 主要工具
| 工具 | 功能 |
|------|-------------|
| `set_working_directory` | 设置工作目录 |
| `get_directory_structure` | 显示文件夹/文件树 |
| `search_files` | 在文件中查找文本 |
| `create_file` | 创建新文件 |
| `update_file` | 编辑现有文件 |
| `delete_file` | 删除文件（带备份） |
| `batch_file_operations` | 一次执行多个操作 |
# 增强型目录上下文 MCP 服务器
一个全面的模型上下文协议 (MCP) 服务器，为 AI 助手（如 Claude）提供高级目录分析和文件管理能力。该服务器将目录上下文提取与完整的文件编辑能力相结合，使其成为代码分析、项目管理和文件操作的强大工具。
## 特性
### 🔍 目录分析
- **完整目录结构**: 获取任何目录的详细树状视图及元数据
- **智能项目分析**: 自动项目类型检测和上下文摘要
- **智能文件搜索**: 在多种文件类型中进行正则表达式和基于文本的搜索
- **Git 集成**: 提取仓库上下文、提交历史和工作目录状态
- **文件统计**: 对文件类型、大小和修改日期进行全面分析
### 📝 文件操作
- **创建文件**: 生成具有指定内容的新文件
- **更新文件**: 进行复杂的搜索和替换操作，支持正则表达式
- **追加内容**: 向现有文件添加内容，并提供格式选项
- **删除文件**: 删除文件并可选择创建备份
- **重命名/移动文件**: 重新定位和重命名文件，具有冲突检测
- **目录管理**: 递归创建目录结构
### 🔄 高级功能
- **批量操作**: 在单个事务中执行多个文件操作
- **自动备份**: 对破坏性操作可选择创建备份
- **事务回滚**: 对失败的批量操作具有回滚能力
- **资源暴露**: 自动将重要项目文件暴露为 MCP 资源
- **错误处理**: 提供全面的错误处理和详细反馈
## 安装
### 先决条件
- Node.js 18.0.0 或更高版本
- npm 或 yarn 包管理器
### 设置
1. 克隆或下载 MCP 服务器文件
2. 安装依赖：
```bash
npm install
```
3. 配置你的 MCP 客户端（Claude Desktop 等）以使用此服务器：
**Claude Desktop 配置:**
添加到你的 `claude_desktop_config.json`：
```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`
### 在开发模式下运行
```bash
npm run dev
```
这将启动带有 Node.js 调试器的服务器以进行调试。
## 许可证
MIT 许可证 - 详见 package.json。
## 支持与问题
如有问题、功能请求或贡献，请参考仓库的问题跟踪器。
---
**注意**: 此 MCP 服务器提供强大的文件系统访问。确保你信任 AI 助手，并理解正在执行的操作，特别是像文件删除或修改这样的破坏性操作。
