AI导哈

文件系统与Git操作服务器

FastFS-MCP是一个高性能的模型上下文协议服务器，为AI助手（如Claude）提供本地文件系统操作、Git仓库管理和交互式提示功能，适用于AI辅助开发、内容创建和自动化文件管理。

  • by aj-geddes
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 aj-geddes/fastfs-mcp

使用说明

FastFS MCP

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

🚀 概述

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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Claude[Claude AI Assistant] <-->|JSON Protocol| MCP[FastFS-MCP Server]
    MCP <-->|File Operations| FS[Local Filesystem]
    MCP <-->|Git Operations| Git[Git Repositories]
    MCP <-->|Interactive Prompts| User[Human User]
    
    subgraph "FastFS-MCP Capabilities"
        FS
        Git
        User
    end

✨ 主要特点

  • 超高速文件系统操作：以最小的延迟访问、修改和管理文件
  • 完成Git集成：执行所有标准Git操作和高级存储库分析
  • 交互式提示：使Claude能够通过结构化的提示和表单吸引用户
  • GitHub身份验证：使用个人访问令牌或GitHub应用程序在GitHub上进行安全身份验证
  • JSON协议：使用标准界面与Claude Desktop、VSCode和其他AI原生工具进行通信

🛠️ 核心组件架构

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Server[server.py] --> FastMCP[FastMCP Class]
    Server --> FileOps[Filesystem Operations]
    Server --> GitTools[git_tools.py]
    Server --> PromptHelpers[prompt_helpers.py]
    
    FileOps --> Basic[Basic Commands]
    FileOps --> Advanced[Advanced Operations]
    FileOps --> Text[Text Processing]
    FileOps --> Archive[Archive & Compression]
    
    GitTools --> BasicGit[Basic Git]
    GitTools --> AdvancedGit[Advanced Git]
    GitTools --> GitAnalysis[Repository Analysis]
    GitTools --> GitAuth[GitHub Authentication]
    
    PromptHelpers --> Templates[Prompt Templates]
    PromptHelpers --> Interactive[Interactive Tools]
    
    GitAuth --> PAT[Personal Access Token]
    GitAuth --> GitHubApp[GitHub App]
    GitHubApp --> DirectKey[Direct Key]
    GitHubApp --> KeyFromFile[Key from File]

💻 安装和快速启动

Docker快速入门

# Build the Docker image
docker build -t fastfs-mcp .

# Run with your local filesystem mounted
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 GITHUB_APP_PRIVATE_KEY="$(cat path/to/private-key.pem)" \
  -e GITHUB_APP_INSTALLATION_ID=your_installation_id \
  fastfs-mcp

使用GitHub应用程序（选项2：工作区文件中的私钥）

# First, copy your private key to the workspace
cp path/to/private-key.pem C:\\Users\\username\\github-app-key.pem

# Then run with the path to the private key
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[Filesystem Operations]
    MCP --> Git[Git Operations]
    MCP --> Prompts[Interactive Prompts]
    MCP --> Processing[Text & File Processing]
    MCP --> Archive[Archive & Compression]
    
    FS --> Basic[Basic Operations]
    FS --> Advanced[Advanced Operations]
    
    Git --> BasicGit[Basic Commands]
    Git --> AdvancedGit[Advanced Analysis]
    Git --> GitHubAuth[GitHub Authentication]
    
    GitHubAuth --> PAT[Personal Access Token]
    GitHubAuth --> GitHubApp[GitHub App]
    
    Prompts --> Templates[Prompt Templates]
    Prompts --> Interactive[Interactive Tools]
    
    Processing --> Text[Text Manipulation]
    Processing --> Filters[Filters & Transformations]
    
    Archive --> Tar[Tar Operations]
    Archive --> Zip[Zip Operations]
    Archive --> Compress[Compression Tools]

🗂️ 文件系统操作

基本操作

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph LR
    ls[ls] --> list[List files and directories]
    cd[cd] --> change[Change current directory]
    pwd[pwd] --> print[Print working directory]
    read[read] --> display[Display file contents]
    write[write] --> create[Create or modify files]
    grep[grep] --> search[Search file content]
    which[which] --> locate[Locate executables]
方法 说明
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 Operations] --> Repo[Repository Management]
    Git --> Changes[Change Management]
    Git --> Branch[Branch Operations]
    Git --> Remote[Remote Operations]
    Git --> Analysis[Repository Analysis]
    Git --> Auth[GitHub Authentication]
    
    Repo --> init[Initialize Repository]
    Repo --> clone[Clone Repository]
    Repo --> status[Check Status]
    
    Changes --> add[Stage Changes]
    Changes --> commit[Commit Changes]
    Changes --> diff[View Differences]
    
    Branch --> checkout[Switch Branches]
    Branch --> branch[Manage Branches]
    Branch --> merge[Merge Branches]
    
    Remote --> push[Push Changes]
    Remote --> pull[Pull Changes]
    Remote --> fetch[Fetch Updates]
    
    Analysis --> context[Get Repository Context]
    Analysis --> validate[Validate Repository]
    Analysis --> suggest[Suggest Commit Messages]
    Analysis --> audit[Audit Repository History]
    
    Auth --> PAT[Personal Access Token]
    Auth --> GitHubApp[GitHub App]

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[Interactive Prompts] --> Templates[Prompt Templates]
    Prompts --> Operations[Prompt Operations]
    
    Templates --> FilePrompts[File Prompts]
    Templates --> ContentPrompts[Content Prompts]
    Templates --> ProjectPrompts[Project Prompts]
    Templates --> CustomPrompts[Custom Prompts]
    
    Operations --> prompt[Send Prompt]
    Operations --> interactive_write[Interactive Write]
    Operations --> confirm_overwrite[Confirm Overwrite]
    Operations --> select_file[Select File]
    Operations --> get_file_content[Get File Content]
    Operations --> init_project[Initialize Project]
    
    FilePrompts --> confirm_file_overwrite[Confirm File Overwrite]
    FilePrompts --> confirm_directory_delete[Confirm Directory Delete]
    FilePrompts --> file_not_found_options[File Not Found Options]
    
    ContentPrompts --> enter_file_content[Enter File Content]
    ContentPrompts --> enter_search_pattern[Enter Search Pattern]
    
    ProjectPrompts --> project_initialization[Project Initialization]
    ProjectPrompts --> coding_task[Coding Task]
    
    CustomPrompts --> custom[Custom Message]

提示模板

模板 说明
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
}

例子

基本文件操作

// Request
{
  "method": "ls",
  "params": { "path": "." }
}

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

Git存储库上下文

// Request
{
  "method": "context",
  "params": {}
}

// Response
{
  "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"
    ]
  }
}

交互式提示流

// Request
{
  "method": "prompt",
  "params": { 
    "prompt_type": "custom", 
    "message": "What would you like to name your file?" 
  }
}

// Response to stdout (visible to user)
{
  "type": "user_prompt",
  "prompt": "What would you like to name your file?"
}

// User response (from stdin)
{
  "type": "user_response",
  "response": "myfile.txt"
}

// Final result to Claude
{
  "result": {
    "response": "myfile.txt",
    "timestamp": 1622548123.45
  }
}

🔧 GitHub身份验证

FastFS MCP支持两种GitHub身份验证方法，以在GitHub存储库中实现安全的Git操作：

个人访问令牌（PAT）身份验证

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
sequenceDiagram
    participant Claude
    participant FastFS
    participant GitHub
    
    Claude->>FastFS: git_clone(private_repo_url)
    FastFS->>GitHub: Authentication with PAT
    GitHub-->>FastFS: Authentication successful
    FastFS->>GitHub: Clone repository
    GitHub-->>FastFS: Repository content
    FastFS-->>Claude: Clone successful

当GitHub PAT通过 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量，与GitHub交互的Git操作（克隆、推送、拉取、获取）将自动使用令牌进行身份验证，从而启用：

  • 访问私有存储库
  • 需要身份验证的操作（推送、创建仓库等）
  • 避免API调用的速率限制

GitHub应用程序身份验证

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
sequenceDiagram
    participant Claude
    participant FastFS
    participant GitHub
    
    Claude->>FastFS: git_clone(private_repo_url)
    FastFS->>FastFS: Generate JWT using private key
    FastFS->>GitHub: Request installation token with JWT
    GitHub-->>FastFS: Installation token
    FastFS->>GitHub: Clone repository with installation token
    GitHub-->>FastFS: Repository content
    FastFS-->>Claude: Clone successful

与个人访问令牌相比，GitHub应用程序身份验证提供了更精细的权限和更好的安全性：

  • 细化权限：GitHub Apps可以配置特定权限
  • 特定于存储库的访问：GitHub Apps可以安装在特定的存储库上
  • 组织级控制：组织管理员可以控制安装哪些应用程序
  • 自动令牌刷新：安装令牌在1小时后过期并自动刷新

要使用GitHub App身份验证，请提供以下环境变量：

  • GITHUB_APP_ID：您的GitHub应用程序ID

私钥的其中一个选项是：

  • GITHUB_APP_PRIVATE_KEY：作为环境变量的GitHub应用程序的私钥内容（PEM格式）
  • GITHUB_APP_PRIVATE_KEY_PATH：包含私钥的文件的路径（PEM格式）

可选：

  • GITHUB_APP_INSTALLATION_ID：要使用的特定安装ID（如果没有提供，FastFS MCP将尝试使用第一个安装）

私钥的安全考虑

使用GitHub App身份验证时，请考虑以下管理私钥的安全实践：

  1. 基于文件的私钥 （推荐）：

    • 将私钥存储在工作区中并使用 GITHUB_APP_PRIVATE_KEY_PATH
    • 确保私钥文件具有适当的文件权限（chmod 600）
    • 这种方法避免了过程中的关键环境变量或shell历史记录

  2. 环境变量私钥:

    • 用于开发或无法装载文件时
    • 请注意，在某些系统的流程列表中可以看到环境变量

🐳 Docker环境

FastFS MCP在Docker容器中运行，以实现可移植性和隔离性，并安装了以下工具：

  • ripgrep 用于高性能文件搜索
  • jq 用于JSON解析和操作
  • sed 和 gawk 用于文本处理
  • tree 用于目录可视化
  • fd-find 用于替代文件查找
  • coreutils 用于标准Unix工具
  • zip/unzip, gzip，以及 xz-utils 用于压缩
  • git 用于存储库操作

🚀 用例

  • 人工智能辅助开发：让Claude在同一次对话中帮助您编写代码、管理文件和使用Git
  • 内容创建工作流：使Claude能够读取、写入和组织用于编写项目的文件
  • 存储库管理：深入了解Git存储库并自动化常见的Git操作
  • 交互式项目设置：通过交互式提示引导用户完成结构化项目初始化
  • 系统管理：在人工智能的帮助下执行文件系统操作和维护任务

🔒 安全考虑

FastFS MCP提供对文件系统和Git存储库的直接访问。考虑以下安全实践：

  1. 仅以适当的文件系统权限运行FastFS MCP
  2. 只挂载需要向Claude公开的目录
  3. 使用单独的GitHub PAT进行有限的身份验证，或者更喜欢GitHub Apps以获得更好的安全性
  4. 定期查看服务器执行的日志和命令
  5. 对于GitHub Apps，安全地存储私钥并使用特定于安装的令牌
  6. 使用GitHub App身份验证时，如果可能的话，更喜欢基于文件的私钥而不是环境变量

📄 许可证

FastFS MCP是在MIT许可证下发布的。有关详细信息，请参阅LICENSE文件。

🤝 贡献

欢迎投稿！请随时提交拉取请求。

  1. 复刻仓库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

📚 更多文件

专为AI增强的CLI和开发人员工作流而构建，具有速度、结构和简单性。

相关 MCP