Filesystem SSE Server in Go

Filesystem MCP

此仓库提供了 MCP 的一种实现，包含一系列用于与文件系统交互的工具，例如列出目录条目、读取和写入文件、获取文件信息，以及重命名和复制文件或目录。

用户可以在本地计算机上通过 stdio 或 SSE 服务运行它。

目录

• 安装
  • 通过克隆仓库在本地安装
  • 使用 Docker
• 使用方法
  • 在 Python 中与 PydanticAI 配合使用示例
    • 使用 SSE 服务
    • 使用 stdio
• 工具说明

安装

1. 确保系统已安装 Go。使用 Go 1.24 版本。
2. 运行以下命令，使用 go install 安装软件包：

go install github.com/lealre/fs-mcp@latest

3. 运行帮助命令：

fs-mcp -h

• -dir 标志用于指定服务要提供服务的基础目录。此项为必填。
• -port 标志用于指定服务监听的端口。此项为可选，默认为 8080。
• -t 标志用于指定传输类型。可以是 stdio 或 http（默认为 stdio）。

通过克隆仓库在本地安装

1. 将仓库克隆到本地计算机：

git clone https://github.com/lealre/fs-mcp.git

2. 进入克隆后的目录：

cd fs-mcp

3. 构建项目：

go build

4. 运行可执行文件：

./fs-mcp -t http -dir /your/directory/path

• 这将在 http://localhost:8080 启动服务。

使用 Docker

此 MCP 只能通过 SSE 选项在 Docker 中运行。为此，请创建一个卷，指向要开放用于文件系统操作的目录。

你可以从 Docker Hub 拉取镜像并按如下方式运行：

docker pull lealre/fs-mcp:latest

或者从克隆的仓库构建镜像：

docker build -t fs-mcp .

运行容器，并映射所需的目录和端口：

docker run -p 8080:8080 -v /your/directory/path:/baseDir lealre/fs-mcp -volume "/your/directory/path:/baseDir"

• 将 /your/directory/path 替换为实际要提供服务的路径。
• -p 标志用于将本地计算机的端口映射到 Docker 容器的端口。
• -v 标志用于指定基础目录的路径，与 --volume 标志类似，以确保 Docker 可以访问你的文件。

此设置将在 http://localhost:8080 启动服务，并提供指定目录。

重要

为确保正常运行，请确保 -v 和 -volume 中的路径完全一致。

容器的基础文件夹卷名称（/baseDir）可以自定义，也可以使用 -port 标志更改端口（同时调整 Docker 中的 -p）。示例：

docker run -p 8081:8081 -v /your/directory/path:/baseDir lealre/fs-mcp -volume "/your/directory/path:/baseDir" -port 8081

使用方法

安装完成后，可以通过运行以下命令使用服务：

fs-mcp -t http -dir /your/directory/path

这将在 http://localhost:8080 启动 MCP 服务，并将文件系统操作限制在此特定路径下。

目前，它只接受一个服务路径。

要更改服务端口，可以将端口作为标志传入：

fs-mcp -dir /your/directory/path -port 3000

要使用 stdio 运行，只需省略 -t 标志。

在 Python 中与 PydanticAI 配合使用示例

使用 SSE 服务

• 运行 MCP 服务：

fs-mcp -dir /your/directory/path

• 创建 Python 客户端（此处使用 OpenAI）：

# script.py

import asyncio
import sys
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerSSE

server = MCPServerSSE('http://localhost:8080/sse')
agent = Agent('openai:gpt-4o', mcp_servers=[server])

async def main():
    if len(sys.argv) < 2:
        print("Usage: python script.py 'your prompt/query here'")
        sys.exit(1)

    query = sys.argv[1]

    async with agent.run_mcp_servers():
        result = await agent.run(query)

    print(result.output)

if __name__ == '__main__':
    asyncio.run(main())

• 然后运行：

python script.py "List all the entries for the path in /your/directory/path/somesubpath"

使用 stdio

• 创建 Python 客户端（此处使用 OpenAI）：

# script.py

import asyncio
import sys
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

base_path = "/your/directory/path"
server = MCPServerStdio(
    'fs-mcp',
    args=['-dir', base_path]
)
agent = Agent('openai:gpt-4o', mcp_servers=[server])

async def main():
    if len(sys.argv) < 2:
        print("Usage: python script.py 'your prompt/query here'")
        sys.exit(1)

    query = sys.argv[1]

    async with agent.run_mcp_servers():
        result = await agent.run(query)

    print(result.output)

if __name__ == '__main__':
    asyncio.run(main())

• 然后运行：

python script.py "List all the entries for the path in /your/directory/path/somesubpath"

工具说明

本项目提供多种与文件系统交互的工具。以下是各个工具的说明：

• listEntries：列出指定路径下的条目。参数：

  • path（string，必填）：要列出所有条目的路径。
  • depth（number，可选）：目录树深度（默认为 3）。

• readFromFile：读取指定路径下文件的内容。参数：

  • path（string，必填）：要读取的文件路径。

• writeToFile：使用给定内容创建或覆盖文件。参数：

  • path（string，必填）：要写入的文件路径。
  • content（string，必填）：要写入的内容。

• getFileInfo：获取文件信息，包括大小、上次修改时间、检测到的 MIME 类型和文件权限。参数：

  • path（string，必填）：要获取信息的文件路径。

• renamePath：将文件或目录重命名。参数：

  • path（string，必填）：要重命名的文件或目录路径。
  • newPathFinalName（string，必填）：文件或目录的新名称（仅名称，不含完整路径）。

• copyFileOrDir：将文件或目录复制到新位置。参数：

  • path（string，必填）：要复制的文件或目录路径。
  • destination（string，必填）：文件或目录的目标复制路径。

本项目使用 mcp-go library 实现核心功能。