FastFS-MCP

<img src="https://img.shields.io/badge/版本-2.8.0-蓝色" alt="版本" /> <img src="https://img.shields.io/badge/许可证-MIT-绿色" alt="许可证" /> <img src="https://img.shields.io/badge/Docker-就绪-信息性" alt="Docker 就绪" />

一个用于文件系统操作、Git集成和交互式提示功能的高速MCP（模型上下文协议）服务器，旨在与Claude和原生AI工具无缝协作。

🚀 概览

FastFS-MCP使像Claude这样的AI助手能够与本地文件系统进行交互，管理Git仓库，并通过标准化的基于JSON的协议提供交互体验。无论您是在构建AI辅助的开发工作流，使用Claude创建内容，还是自动化文件管理任务，FastFS-MCP都提供了AI助手与本地环境之间的桥梁。

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Claude[Claude AI助手] <-->|JSON协议| MCP[FastFS-MCP服务器]
    MCP <-->|文件操作| FS[本地文件系统]
    MCP <-->|Git操作| Git[Git仓库]
    MCP <-->|交互式提示| User[人类用户]
    
    subgraph "FastFS-MCP能力"
        FS
        Git
        User
    end

✨ 主要特性

• 超快速文件系统操作：以极低延迟访问、修改和管理文件
• 完整的Git集成：执行所有标准Git操作和高级仓库分析
• 交互式提示：使Claude能够通过结构化的提示和表单与用户互动
• GitHub认证：使用个人访问令牌或GitHub应用安全地进行GitHub认证
• JSON协议：使用标准接口与Claude桌面、VSCode和其他原生AI工具通信

🛠️ 核心组件架构

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Server[server.py] --> FastMCP[FastMCP类]
    Server --> FileOps[文件系统操作]
    Server --> GitTools[git_tools.py]
    Server --> PromptHelpers[prompt_helpers.py]
    
    FileOps --> Basic[基本命令]
    FileOps --> Advanced[高级操作]
    FileOps --> Text[文本处理]
    FileOps --> Archive[归档与压缩]
    
    GitTools --> BasicGit[基本Git]
    GitTools --> AdvancedGit[高级Git]
    GitTools --> GitAnalysis[仓库分析]
    GitTools --> GitAuth[GitHub认证]
    
    PromptHelpers --> Templates[提示模板]
    PromptHelpers --> Interactive[交互工具]
    
    GitAuth --> PAT[个人访问令牌]
    GitAuth --> GitHubApp[GitHub应用]
    GitHubApp --> DirectKey[直接密钥]
    GitHubApp --> KeyFromFile[从文件中获取密钥]

💻 安装与快速开始

Docker 快速开始

# 构建Docker镜像
docker build -t fastfs-mcp .

# 运行并挂载您的本地文件系统
docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  fastfs-mcp

在Unix/macOS上：替换为 -v $HOME:/mnt/workspace

使用GitHub认证

使用个人访问令牌

docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
  fastfs-mcp

使用GitHub应用（选项1：私钥作为环境变量）

docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_APP_ID=your_app_id \
  -e GGITHUB_APP_PRIVATE_KEY="$(cat path/to/private-key.pem)" \
  -e GITHUB_APP_INSTALLATION_ID=your_installation_id \
  fastfs-mcp

使用GitHub应用（选项2：从工作区中的文件获取私钥）

# 首先，将您的私钥复制到工作区
cp path/to/private-key.pem C:\\Users\\username\\github-app-key.pem

# 然后使用私钥路径运行
docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_APP_ID=your_app_id \
  -e GITHUB_APP_PRIVATE_KEY_PATH=/mnt/workspace/github-app-key.pem \
  -e GITHUB_APP_INSTALLATION_ID=your_installation_id \
  fastfs-mcp

🤖 Claude桌面配置

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ]
    }
  }
}

使用GitHub认证

使用个人访问令牌

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

使用GitHub应用（私钥作为环境变量）

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_APP_ID",
        "-e", "GITHUB_APP_PRIVATE_KEY",
        "-e", "GITHUB_APP_INSTALLATION_ID",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_APP_ID": "your_app_id",
        "GITHUB_APP_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
        "GITHUB_APP_INSTALLATION_ID": "your_installation_id"
      }
    }
  }
}

使用GitHub应用（从文件获取私钥）

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_APP_ID",
        "-e", "GITHUB_APP_PRIVATE_KEY_PATH",
        "-e", "GITHUB_APP_INSTALLATION_ID",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_APP_ID": "your_app_id",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/mnt/workspace/github-app-key.pem",
        "GITHUB_APP_INSTALLATION_ID": "your_installation_id"
      }
    }
  }
}

📋 工具分类

FastFS-MCP提供了一整套工具，按逻辑类别组织：

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    MCP[FastFS-MCP] --> FS[文件系统操作]
    MCP --> Git[Git操作]
    MCP --> Prompts[交互式提示]
    MCP --> Processing[文本及文件处理]
    MCP --> Archive[归档与压缩]
    
    FS --> Basic[基本操作]
    FS --> Advanced[高级操作]
    
    Git --> BasicGit[基本命令]
    Git --> AdvancedGit[高级分析]
    Git --> GitHubAuth[GitHub认证]
    
    GitHubAuth --> PAT[个人访问令牌]
    GitHubAuth --> GitHubApp[GitHub应用]
    
    Prompts --> Templates[提示模板]
    Prompts --> Interactive[交互工具]
    
    Processing --> Text[文本操作]
    Processing --> Filters[过滤器与转换]
    
    Archive --> Tar[Tar操作]
    Archive --> Zip[Zip操作]
    Archive --> Compress[压缩工具]

🗂️ 文件系统操作

基本操作

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph LR
    ls[ls] --> list[列出文件和目录]
    cd[cd] --> change[更改当前目录]
    pwd[pwd] --> print[打印工作目录]
    read[read] --> display[显示文件内容]
    write[write] --> create[创建或修改文件]
    grep[grep] --> search[搜索文件内容]
    which[which] --> locate[定位可执行文件]

方法	描述
ls	列出目录中的文件
cd	更改当前工作目录
pwd	打印当前工作目录
read	读取文件内容
write	创建或覆盖文件内容
grep	使用ripgrep快速搜索文件
which	在PATH中定位可执行文件

高级操作

方法	描述
tree	显示目录结构
find	按模式查找文件
cp	复制文件或目录
mv	移动或重命名文件
rm	删除文件或目录
mkdir	创建目录
stat	显示文件元数据
chmod	更改文件权限
du	显示磁盘使用情况
df	显示磁盘空间
touch	创建新的空文件或更新时间戳

文本及文件处理

方法	描述
sed	流编辑器用于文本转换
gawk	使用AWK进行文本处理
head	显示文件的前几行
tail	显示文件的最后几行
wc	统计行数、单词数和字节数
cut	从文件中选择列
sort	对文本文件的行进行排序
uniq	报告或过滤重复行
nl	对文件中的行进行编号
split	将文件分割成更小的部分
readlink	显示符号链接的解析路径
realpath	显示解析后的绝对路径

归档与压缩

方法	描述
tar	创建或提取tar归档
gzip	压缩或解压文件
zip	创建或提取zip归档

🌿 Git操作

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Git[Git操作] --> Repo[仓库管理]
    Git --> Changes[变更管理]
    Git --> Branch[分支操作]
    Git --> Remote[远程操作]
    Git --> Analysis[仓库分析]
    Git --> Auth[GitHub认证]
    
    Repo --> init[初始化仓库]
    Repo --> clone[克隆仓库]
    Repo --> status[检查状态]
    
    Changes --> add[暂存变更]
    Changes --> commit[提交变更]
    Changes --> diff[查看差异]
    
    Branch --> checkout[切换分支]
    Branch --> branch[管理分支]
    Branch --> merge[合并分支]
    
    Remote --> push[推送变更]
    Remote --> pull[拉取变更]
    Remote --> fetch[获取更新]
    
    Analysis --> context[获取仓库上下文]
    Analysis --> validate[验证仓库]
    Analysis --> suggest[建议提交消息]
    Analysis --> audit[审核仓库历史]
    
    Auth --> PAT[个人访问令牌]
    Auth --> GitHubApp[GitHub应用]

基本Git操作

方法	描述
clone	克隆一个Git仓库
init	初始化一个新的Git仓库
add	将文件添加到暂存区域
commit	提交变更到仓库
status	显示工作树状态
push	将变更推送到远程仓库
pull	从远程仓库拉取变更
log	显示提交日志
checkout	切换分支或恢复文件
branch	列出、创建或删除分支
merge	合并分支的发展历史
show	显示Git对象
diff	显示提交之间或工作树的变化
remote	管理远程仓库
stash	存储工作目录中的变更
tag	管理Git标签
config	获取或设置仓库或全局选项
fetch	从另一个仓库下载对象和引用
blame	显示每个文件行的修订和作者
git_grep	在跟踪文件中打印匹配模式的行
head	显示当前HEAD提交信息

高级Git分析

方法	描述
context	获取全面的仓库上下文
repo_info	获取详细的仓库信息
validate	检查仓库是否存在常见问题
summarize_log	生成提交日志统计
suggest_commit	自动建议提交消息
audit_history	审核仓库的安全问题

🤝 交互式提示

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Prompts[交互式提示] --> Templates[提示模板]
    Prompts --> Operations[提示操作]
    
    Templates --> FilePrompts[文件提示]
    Templates --> ContentPrompts[内容提示]
    Templates --> ProjectPrompts[项目提示]
    Templates --> CustomPrompts[自定义提示]
    
    Operations --> prompt[发送提示]
    Operations --> interactive_write[交互写入]
    Operations --> confirm_overwrite[确认覆盖]
    Operations --> select_file[选择文件]
    Operations --> get_file_content[获取文件内容]
    Operations --> init_project[初始化项目]
    
    FilePrompts --> confirm_file_overwrite[确认文件覆盖]
    FilePrompts --> confirm_directory_delete[确认目录删除]
    FilePrompts --> file_not_found_options[未找到文件选项]
    
    ContentPrompts --> enter_file_content[输入文件内容]
    ContentPrompts --> enter_search_pattern[输入搜索模式]
    
    ProjectPrompts --> project_initialization[项目初始化]
    ProjectPrompts --> coding_task[编码任务]
    
    CustomPrompts --> custom[自定义消息]

提示模板

模板	描述
confirm_file_overwrite	在覆盖现有文件之前询问用户确认
confirm_directory_delete	在删除目录之前警告用户
file_not_found_options	当文件未找到时提供选项
enter_file_content	从用户处获取文件内容
enter_search_pattern	询问用户搜索模式
project_initialization	收集信息以初始化新项目
coding_task	定义编码任务的参数
select_file_from_list	让用户从列表中选择文件
custom	创建完全自定义的提示消息

交互函数

函数	描述
prompt	向用户发送交互式提示
get_prompt_types	列出可用的提示模板
interactive_write	使用用户提供的内容写入文件
confirm_overwrite	在覆盖文件之前询问确认
select_file	让用户从文件列表中选择
get_file_content	从用户处获取文件内容
init_project	使用引导设置初始化项目

📝 协议用法

FastFS-MCP使用简单的基于JSON的协议与Claude和其他AI工具通信。

请求格式

{
  "method": "METHOD_NAME",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

响应格式

{
  "result": RESPONSE_DATA
}

示例

基本文件操作

// 请求
{
  "method": "ls",
  "params": { "path": "." }
}

// 响应
{
  "result": ["main.tf", "README.md"]
}

Git仓库上下文

// 请求
{
  "method": "context",
  "params": {}
}

// 响应
{
  "result": {
    "current_branch": "main",
    "repository_root": "/mnt/workspace/my-project",
    "is_clean": false,
    "head_commit": "a1b2c3d4e5f6...",
    "remotes": {
      "origin": "https://github.com/user/repo.git"
    },
    "recent_commits": [
      "a1b2c3d4 Update README.md",
      "b2c3d4e5 Fix bug in main function",
      "c3d4e5f6 Add new feature"
    ]
  }
}

交互式提示流程

// 请求
{
  "method": "prompt",
  "params": { 
    "prompt_type": "custom", 
    "message": "您想给文件起什么名字？" 
  }
}

// 响应到stdout（可见于用户）
{
  "type": "user_prompt",
  "prompt": "您想给文件起什么名字？"
}

// 用户响应（来自stdin）
{
  "type": "user_response",
  "response": "myfile.txt"
}

// 最终结果