Skip to main content
Glama
maicFir

maic-server-fs-mcp

by maicFir

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

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


🛠️ 核心工具 (Tools)

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

工具名称

作用描述

输入参数

readFile

读取指定本地文件内容

filePath (string)

writeFile

写入或更新本地文件(若父级目录不存在会自动创建)

filePath (string), content (string)

readDirectory

列出目标文件夹内容(已自动忽略 node_modules 等庞大文件夹)

filePath (string, 默认 .)

executeCommand

在终端中运行命令(同步执行,最长 30 秒超时)

command (string)

dispatchTask

派发特定任务给下属专家(CODERTESTER

worker ('CODER' | 'TESTER'), taskInstruction (string)

humanReview

人工审核插桩,用于人工确认

message (string)

buildCodebaseIndex

扫描并为代码库构建本地向量索引(支持 JS/TS/JSX/TSX)

dirPath (string, 默认 .)

searchCodebase

语义化检索整个代码库,寻找匹配的代码片段

query (string), topK (number, 默认 3)


Related MCP server: Sentinel Core Agent

🧠 本地代码 RAG 功能说明

为了使用 buildCodebaseIndexsearchCodebase(基于 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"
      }
    }

工作机制:

  1. 构建索引:调用 buildCodebaseIndex 时,系统将扫描目录内的所有代码文件并按最长 40 行的窗口进行滑动切片,再通过 Gemini Embeddings API 向量化并保存在项目根目录的 .rag_cache.json 中。

  2. 语义化检索:调用 searchCodebase 时,系统向量化您的查询,计算其与本地缓存中所有代码片段的余弦相似度(Cosine Similarity),并返回相似度最高的 topK 个真实代码片段。


🔌 接入与集成当前 MCP 服务

您可以通过 NPM 方式直接运行(推荐),或者使用本地克隆源码开发模式

方式 1: 通过 NPM 接入(最简便,推荐)

A. 接入 Cursor 编辑器

  1. 打开 Cursor 设置:进入 Settings ➡️ Features ➡️ MCP

  2. 点击 + Add New MCP Server

    • Name: maic-local-filesystem-mcp

    • Type: command

    • Command:

      npx -y --package maic-server-fs-mcp mcp-server-fs
  3. 点击 Save。等待状态指示灯亮起绿色 🟢。

B. 接入 Claude Desktop

  1. 打开并编辑 Claude Desktop 的配置文件:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. mcpServers 节点内,追加如下配置:

    {
      "mcpServers": {
        "maic-local-filesystem-mcp": {
          "command": "npx",
          "args": [
            "-y",
            "--package",
            "maic-server-fs-mcp",
            "mcp-server-fs"
          ]
        }
      }
    }
  3. 保存文件并重启 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() 输出,客户端会自动捕获并展示在控制台或日志文件中。

Available Tools

7 tools
buildCodebaseIndexA

扫描整个本地代码库(js/ts/jsx/tsx文件),调用 Gemini Embedding API 构建/重构本地向量索引。当项目代码发生重大变化后,或者首次使用 searchCodebase 前,必须调用此工具构建索引。

ParametersJSON Schema
NameRequiredDescriptionDefault
dirPathNo要扫描和索引的根目录路径,支持相对路径,默认当前项目根目录 '.'.

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It mentions scanning specific file types and calling an external API, but does not state whether the previous index is overwritten, the time/network cost, or any side effects. This is insufficient for a tool that has destructive potential (rebuilding index).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences. First sentence states purpose and scope. Second sentence provides essential usage guidance. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers when to invoke but lacks details on what happens after invocation (e.g., progress indication, result, error handling). No output schema, so description should explain expected outcome or side effects. It is adequate but not complete for a complex indexing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter dirPath with default and description. The tool description adds no further parameter semantics beyond what is in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it scans local JS/TS/JSX/TSX files and builds/rebuilds a vector index using Gemini Embedding API. It distinguishes itself from sibling searchCodebase by noting it must be called before first use of searchCodebase or after major code changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly specifies when to use: after major code changes or before first use of searchCodebase. Does not provide alternatives or when not to use, but the context is clear that this is the only index-building tool among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

dispatchTaskA

当需要安排下属专家执行具体工作时调用此工具。每次只能派发一个任务,等下属汇报结果后,再派发下一个。

ParametersJSON Schema
NameRequiredDescriptionDefault
workerYes接收任务的专家。'CODER' 负责读写代码文件;'TESTER' 负责运行终端编译或测试命令。
taskInstructionYes具体要这个专家执行的详细指令。例如:'帮我查看 src/index.ts 的内容并修复其中的类型 Bug'。

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that it dispatches one task and waits for results, but lacks details on side effects, failure handling, or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently convey purpose and usage guideline. The description is front-loaded and contains no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main workflow but lacks information on return values or what happens after dispatch, which would be helpful given the absence of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The description adds global workflow context but no additional parameter-specific meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: dispatching a task to a subordinate expert. It distinguishes from siblings like buildCodebaseIndex or writeFile by focusing on delegation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: only one task at a time and wait for results. It does not explicitly mention when not to use it or alternatives, but the sibling tools are distinct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

executeCommandA

在本地终端安全运行 shell 命令(如 npm test, git status, npm run build)。当修改代码后需要验证是否报错,或者需要安装依赖、运行构建时使用此工具。

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYes要执行的 Shell 命令
timeoutMsNo命令超时时间(毫秒)

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It mentions 'safely run' but gives no details on safety mechanisms, restrictions, side effects, or output behavior (stdout/stderr). The agent lacks critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two efficient sentences: the first defines the tool's action with examples, the second provides usage context. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has moderate complexity with two well-documented parameters and no output schema. The description covers purpose and usage but omits crucial details: return output (stdout/stderr with exit code), execution environment (project root directory), and blocking nature. These gaps reduce completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters have descriptions in the schema (100% coverage). The description adds example commands (npm test, git status, npm run build) which help ground the usage, but does not add additional semantic depth beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs shell commands safely on the local terminal, gives concrete examples (npm test, git status, npm run build), and distinguishes from sibling tools that handle file operations, search, or task dispatch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies when to use the tool: after code modifications to verify errors, install dependencies, or run builds. It does not explicitly mention alternatives or exclusions, but the provided contexts cover common use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

readDirectoryA

列出指定目录下的所有文件和文件夹名称(已自动忽略 node_modules 等大文件夹)。当你不确定项目结构、找不到某个文件在哪里时,必须先调用此工具,辅助 AI 了解项目结构。

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYes要扫描的目录路径,支持相对路径,绝对路径,(默认当前项目根).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses automatic ignoring of 'node_modules 等大文件夹', a behavioral trait not in annotations. No annotations are provided, so the description adds value by mentioning this filter. However, it does not explicitly state that the operation is read-only (though implied by '列出').

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one paragraph with front-loaded main action. It is concise but could be slightly more structured; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks output format details (e.g., whether paths or just names, recursion depth). While it covers when to use and auto-ignoring behavior, the missing return information leaves ambiguity for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already describes the filePath parameter including supported paths and default. The description adds no additional semantic value beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all file and folder names in a directory, with a specific verb '列出'. It distinguishes from siblings like readFile (reads single file) and searchCodebase (searches) by positioning itself as a prerequisite for understanding project structure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use: '当你不确定项目结构、找不到某个文件在哪里时' and states '必须先调用此工具', establishing clear usage context and positioning it as a first step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

readFileB

读取指定路径的本地文件内容,允许 AI 查看文件代码或文本。

ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYes相对或绝对路径,例如 'package.json' 或 'src/index.js'

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It only states the basic operation without disclosing error handling, permissions, or encoding assumptions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, concise and front-loaded. Could be slightly more informative without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple read tool, but lacks details on output format, encoding, or potential errors. No output schema to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description and example; the tool description adds no extra meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads file content from a local path, and is distinct from sibling tools like writeFile (write) and readDirectory (list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage for viewing file content, but no explicit when-to-use or when-not-to-use guidance relative to alternatives like readDirectory or searchCodebase.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

searchCodebaseA

语义化检索整个本地代码库。当不知道某段功能、组件、路由在哪里时,调用此工具通过关键词或功能描述找出最相关的真实代码片段。

ParametersJSON Schema
NameRequiredDescriptionDefault
topKNo返回的最相关的代码片段数量,默认为 3
queryYes搜索词或代码功能描述,例如 'JWT 鉴权拦截器' 或 'Button 组件'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes a read-only search operation but does not disclose potential behaviors like indexing prerequisites, resource cost, or limitations on search scope beyond 'local codebase'. Basic transparency is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that front-loads the core purpose. It is concise with no extraneous information, earning every word.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers when and what to use, and parameter semantics are clear. Lack of output format details is minor for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters. The description adds contextual examples (e.g., 'JWT 鉴权拦截器') for query and explains topK's purpose, but the value over schema is marginal. The description does not compensate for any missing schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the verb (semantic search), resource (local codebase), and provides a clear use case (when location of code is unknown). It implicitly distinguishes from siblings like readFile (specific file) and executeCommand (commands).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use ('when you don't know where'), providing clear context. However, it does not explicitly mention when not to use or suggest alternative sibling tools like buildCodebaseIndex for indexing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

writeFileA

向指定路径写入或覆盖文件内容,常用于生成/修改代码,允许 AI 修改文件代码或文本。

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYes要写入文件的内容
filePathYes目标文件路径,相对或绝对路径,例如 'package.json' 或 'src/index.js'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, description carries full burden. It mentions write/overwrite but does not disclose side effects like overwrite behavior without confirmation, permissions, or what happens if file doesn't exist (creates?). Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence in Chinese, front-loaded with core purpose. No redundant information. Extremely concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 simple parameters and no output schema, description covers purpose and usage context. Could mention overwrite behavior explicitly, but overall sufficient for a basic file write tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions for both parameters. Description adds use-case context but no new parameter-level meaning beyond schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool writes/overwrites file content at a specified path, used for code generation/modification. It distinguishes from siblings like readFile (read-only) and readDirectory (listing). Verb and resource are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for writing/modifying code, but lacks explicit guidance on when not to use or alternatives. However, based on sibling tools, the context is clear enough for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.5
    • First observedbuildCodebaseIndex
    • First observeddispatchTask
    • First observedexecuteCommand
    • First observedreadDirectory
    • First observedreadFile
    • First observedsearchCodebase
    • First observedwriteFile

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: indexing, task dispatch, command execution, directory listing, file reading, semantic search, and file writing. No overlapping functionality.

Naming Consistency5/5

All tool names follow a consistent camelCase verb_noun pattern (e.g., readFile, searchCodebase, writeFile). No mixed conventions or irregularities.

Tool Count5/5

With 7 tools, the server covers its core file system and codebase functionality without being too sparse or bloated. The count feels well-scoped for its purpose.

Completeness3/5

While the tools cover reading, writing, and searching, they lack file deletion, renaming, and directory creation, which are common file system operations. The inclusion of dispatchTask seems out of place for an FS server.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maicFir/server-fs-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server