maic-server-fs-mcp

v1.0.6

Published

23 days ago

一个用于读取本地文件的自定义标准 MCP 服务端

0High
0Medium
0Low

maicfir

mcp model-context-protocol mcp-server filesystem fs local-files

Local Filesystem MCP Server (maic-server-fs-mcp)

一个基于 Model Context Protocol (MCP) 构建的自定义本地文件系统与命令行执行服务。此工具已被发布至 NPM，支持通过 npx 直接在 LLM 客户端（如 Cursor、Claude Desktop 等）中无缝运行。

🛠️ 核心工具 (Tools)

本 MCP 服务端向 LLM 提供了以下接口能力：

📰 掘金文章工具说明

downloadJuejinDraft 和 processLocalMarkdown 这两个工具专为从掘金平台抓取和本地化文章内容而设计。

工作场景对比

前置配置：`JUEJIN_COOKIE`

两个工具都依赖 JUEJIN_COOKIE 环境变量来访问掘金私有 CDN（p*-xtjj-private.juejin.cn）中的图片。如果不配置，图片下载会返回 403 Forbidden。

如何获取完整的 Cookie：

在 Chrome 中登录掘金，打开 DevTools（F12）→ Network 面板
访问任意掘金页面，找到一个对 juejin.cn 的请求
右键该请求 → Copy as cURL
从 cURL 命令中提取 -b '...' 后的完整字符串，确保包含以下关键登录态字段：
- sessionid=...
- uid_tt=...
- sid_tt=...
将其配置到环境变量中：

# 在 .env 文件中
JUEJIN_COOKIE="sessionid=xxx; uid_tt=xxx; sid_tt=xxx; ..."

# 或在启动前临时导出
export JUEJIN_COOKIE="sessionid=xxx; ..."

`processLocalMarkdown` 图片处理细节

图片按在 Markdown 中出现的顺序命名为 1.webp、2.png 等
掘金私有 CDN 图片（.awebp 格式）自动重命名为 .webp 以便本地正常打开
对私有 CDN 域名自动附加 Cookie + Referer 请求头，绕过鉴权
处理结果另存为 原文件名_processed.md，不覆盖原文件
图片统一存放在 原文件名_images/ 文件夹下

🧠 本地代码 RAG 功能说明

为了使用 buildCodebaseIndex 和 searchCodebase（基于 text-embedding-004 模型），您需要在使用前配置 GEMINI_API_KEY 环境变量：

命令行启动时设置：

export GEMINI_API_KEY="your-gemini-api-key"
npx -y --package maic-server-fs-mcp mcp-server-fs

Cursor 编辑器配置：在 Cursor 设置 MCP 时，您也可以在 Shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中全局导出 GEMINI_API_KEY，这样 Cursor 启动的进程可以读取到该变量。

Claude Desktop 配置文件配置 (claude_desktop_config.json)：

"maic-local-filesystem-mcp": {
  "command": "npx",
  "args": [
    "-y",
    "--package",
    "maic-server-fs-mcp",
    "mcp-server-fs"
  ],
  "env": {
    "GEMINI_API_KEY": "your-gemini-api-key"
  }
}

工作机制：

构建索引：调用 buildCodebaseIndex 时，系统将扫描目录内的所有代码文件并按最长 40 行的窗口进行滑动切片，再通过 Gemini Embeddings API 向量化并保存在项目根目录的 .rag_cache.json 中。
语义化检索：调用 searchCodebase 时，系统向量化您的查询，计算其与本地缓存中所有代码片段的余弦相似度（Cosine Similarity），并返回相似度最高的 topK 个真实代码片段。

🔌 接入与集成当前 MCP 服务

您可以通过 NPM 方式直接运行（推荐），或者使用本地克隆源码开发模式。

方式 1: 通过 NPM 接入（最简便，推荐）

A. 接入 Cursor 编辑器

打开 Cursor 设置：进入 Settings ➡️ Features ➡️ MCP。
点击 + Add New MCP Server：
- Name: maic-local-filesystem-mcp
- Type: command
- Command:
```
npx -y --package maic-server-fs-mcp mcp-server-fs
```
点击 Save。等待状态指示灯亮起绿色 🟢。

B. 接入 Claude Desktop

打开并编辑 Claude Desktop 的配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 节点内，追加如下配置：

{
  "mcpServers": {
    "maic-local-filesystem-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "maic-server-fs-mcp",
        "mcp-server-fs"
      ]
    }
  }
}

保存文件并重启 Claude Desktop。

方式 2: 使用本地克隆源码运行（适合贡献者/二次开发）

1. 安装与构建

git clone https://github.com/maicFir/server-fs-mcp.git
cd server-fs-mcp
npm install
npm run build # 编译生成 dist/server.js

2. 在客户端中配置本地路径

Cursor (Command):

node /absolute/path/to/server-fs-mcp/dist/server.js

Claude Desktop (claude_desktop_config.json):

"maic-local-filesystem-mcp": {
  "command": "node",
  "args": [
    "/absolute/path/to/server-fs-mcp/dist/server.js"
  ]
}

⚠️ 开发者必看避坑指南 (Gotchas)

标准输出占用：MCP 的 stdio 传输机制完全独占了标准输出流 (stdout) 用于 JSON-RPC 通信。因此在开发调试时，绝对不能在工具执行或初始化逻辑中使用 console.log() 或 process.stdout.write()。
调试日志：所有打印日志、调试信息请全部使用 console.error() 输出，客户端会自动捕获并展示在控制台或日志文件中。