Fast Fs 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]

高级操作

文本和文件处理

存档和压缩

🌿 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基本操作

高级Git分析

🤝 互动提示

%%{ 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]

提示模板

交互功能

📝 协议使用

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历史记录

1. 环境变量私钥:

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

🐳 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. 打开拉取请求

📚 更多文件

• 快速指南 -关于交互式提示的详细文档
• 克劳德提示示例 -Claude如何使用FastFS MCP的示例
• 克劳德提示指南 -Claude使用FastFS MCP的指南

______________________________________________________________________

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