maic-server-fs-mcp 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +93 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# Local Filesystem MCP Server (maic-server-fs-mcp)
|
|
2
|
+
|
|
3
|
+
一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 构建的自定义本地文件系统与命令行执行服务。此工具已被发布至 NPM，支持通过 `npx` 直接在 LLM 客户端（如 Cursor、Claude Desktop 等）中无缝运行。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 🛠️ 核心工具 (Tools)
|
|
8
|
+
|
|
9
|
+
本 MCP 服务端向 LLM 提供了以下接口能力：
|
|
10
|
+
|
|
11
|
+
| 工具名称 | 作用描述 | 输入参数 |
|
|
12
|
+
| :--- | :--- | :--- |
|
|
13
|
+
| `readFile` | 读取指定本地文件内容 | `filePath` (string) |
|
|
14
|
+
| `writeFile` | 写入或更新本地文件（若父级目录不存在会自动创建） | `filePath` (string), `content` (string) |
|
|
15
|
+
| `readDirectory` | 列出目标文件夹内容（已自动忽略 `node_modules` 等庞大文件夹） | `filePath` (string, 默认 `.`) |
|
|
16
|
+
| `executeCommand` | 在终端中运行命令（同步执行，最长 30 秒超时） | `command` (string) |
|
|
17
|
+
| `dispatchTask` | 派发特定任务给下属专家（`CODER` 或 `TESTER`） | `worker` ('CODER' \| 'TESTER'), `taskInstruction` (string) |
|
|
18
|
+
| `humanReview` | 人工审核插桩，用于人工确认 | `message` (string) |
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🔌 接入与集成当前 MCP 服务
|
|
23
|
+
|
|
24
|
+
您可以通过 **NPM 方式直接运行（推荐）**，或者使用**本地克隆源码开发模式**。
|
|
25
|
+
|
|
26
|
+
### 方式 1: 通过 NPM 接入（最简便，推荐）
|
|
27
|
+
|
|
28
|
+
#### A. 接入 Cursor 编辑器
|
|
29
|
+
1. 打开 Cursor 设置：进入 **Settings** ➡️ **Features** ➡️ **MCP**。
|
|
30
|
+
2. 点击 **+ Add New MCP Server**：
|
|
31
|
+
- **Name**: `maic-local-filesystem-mcp`
|
|
32
|
+
- **Type**: `command`
|
|
33
|
+
- **Command**:
|
|
34
|
+
```bash
|
|
35
|
+
npx -y --package maic-server-fs-mcp mcp-server-fs
|
|
36
|
+
```
|
|
37
|
+
3. 点击 **Save**。等待状态指示灯亮起绿色 🟢。
|
|
38
|
+
|
|
39
|
+
#### B. 接入 Claude Desktop
|
|
40
|
+
1. 打开并编辑 Claude Desktop 的配置文件：
|
|
41
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
42
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
43
|
+
2. 在 `mcpServers` 节点内，追加如下配置：
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"mcpServers": {
|
|
47
|
+
"maic-local-filesystem-mcp": {
|
|
48
|
+
"command": "npx",
|
|
49
|
+
"args": [
|
|
50
|
+
"-y",
|
|
51
|
+
"--package",
|
|
52
|
+
"maic-server-fs-mcp",
|
|
53
|
+
"mcp-server-fs"
|
|
54
|
+
]
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
3. 保存文件并重启 Claude Desktop。
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
### 方式 2: 使用本地克隆源码运行（适合贡献者/二次开发）
|
|
64
|
+
|
|
65
|
+
#### 1. 安装与构建
|
|
66
|
+
```bash
|
|
67
|
+
git clone https://github.com/maicFir/server-fs-mcp.git
|
|
68
|
+
cd server-fs-mcp
|
|
69
|
+
npm install
|
|
70
|
+
npm run build # 编译生成 dist/server.js
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
#### 2. 在客户端中配置本地路径
|
|
74
|
+
* **Cursor (Command)**:
|
|
75
|
+
```bash
|
|
76
|
+
node /absolute/path/to/server-fs-mcp/dist/server.js
|
|
77
|
+
```
|
|
78
|
+
* **Claude Desktop (`claude_desktop_config.json`)**:
|
|
79
|
+
```json
|
|
80
|
+
"maic-local-filesystem-mcp": {
|
|
81
|
+
"command": "node",
|
|
82
|
+
"args": [
|
|
83
|
+
"/absolute/path/to/server-fs-mcp/dist/server.js"
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## ⚠️ 开发者必看避坑指南 (Gotchas)
|
|
91
|
+
|
|
92
|
+
- **标准输出占用**：MCP 的 stdio 传输机制完全独占了标准输出流 (`stdout`) 用于 JSON-RPC 通信。因此在开发调试时，**绝对不能**在工具执行或初始化逻辑中使用 `console.log()` 或 `process.stdout.write()`。
|
|
93
|
+
- **调试日志**：所有打印日志、调试信息请全部使用 `console.error()` 输出，客户端会自动捕获并展示在控制台或日志文件中。
|