mcp菲力泡芙
用于Claude Code的基于Go的MCP（模型上下文协议）服务器，提供智能文件操作，具有快速搜索、AST感知查询、LSP集成和安全编辑功能。
特性
- 快速文本搜索：由ripgrep提供支持，支持正则表达式，可实现超快的代码搜索
- AST感知文件读取：使用Tree sitter读取带有符号提取的文件
- 代码模式匹配：使用带有捕获占位符的模式查询代码
- LSP集成：通过语言服务器转到定义、查找引用和符号信息
- 安全编辑：具有语法验证的AST感知文件编辑（edit_apply）
- 多语言支持：Go、TypeScript、JavaScript、Python、C、C++、HTML、Vue、React
- 代币高效：优化了仅符号模式和输出限制，以实现最小的令牌使用
安装
快速安装（推荐）
使用单个命令安装最新版本：
curl -sSL https://raw.githubusercontent.com/lukaszraczylo/filepuff-mcp/main/scripts/install.sh | bash此脚本将：
- 自动检测您的平台（操作系统和架构）
- 下载最新版本
- 验证校验和
- 安装到
~/.local/bin（或/usr/local/bin如果需要） - 使二进制文件可执行
码头工人
docker pull ghcr.io/lukaszraczylo/filepuff-mcp:latestMCP服务器通过stdio进行通信。安装您的工作区并使用 -i:
docker run -i --rm -v /path/to/workspace:/workspace ghcr.io/lukaszraczylo/filepuff-mcp:latest -workspace /workspaceClaude代码配置(.claude/settings.json):
{
"mcpServers": {
"filepuff": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", ".:/workspace", "ghcr.io/lukaszraczylo/filepuff-mcp:latest", "-workspace", "/workspace"]
}
}
}手动安装
从下载预构建的二进制文件 发布页面:
# macOS (Apple Silicon)
curl -fsSL -o mcp-filepuff https://github.com/lukaszraczylo/filepuff-mcp/releases/latest/download/mcp-filepuff__darwin_arm64
chmod +x mcp-filepuff && mv mcp-filepuff ~/.local/bin/
# Linux (ARM64)
curl -fsSL -o mcp-filepuff https://github.com/lukaszraczylo/filepuff-mcp/releases/latest/download/mcp-filepuff__linux_arm64
chmod +x mcp-filepuff && mv mcp-filepuff ~/.local/bin/
# Linux (AMD64)
curl -fsSL -o mcp-filepuff https://github.com/lukaszraczylo/filepuff-mcp/releases/latest/download/mcp-filepuff__linux_amd64
chmod +x mcp-filepuff && mv mcp-filepuff ~/.local/bin/
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/lukaszraczylo/filepuff-mcp/releases/latest/download/mcp-filepuff__windows_amd64.exe" -OutFile mcp-filepuff.exe
Move-Item mcp-filepuff.exe $env:USERPROFILE\.local\bin\替换 ` 与实际版本（例如。， v1.0.0`).
先决条件
- ripgrep (
rg)已安装并位于PATH中
可选依赖关系（用于LSP功能）
gopls-Go语言服务器typescript-language-server-Types/JavaScript语言服务器pylsp-Python语言服务器clangd-C/C++语言服务器
从源代码构建
git clone https://github.com/lukaszraczylo/filepuff-mcp.git
cd filepuff-mcp
make build二进制文件将在 bin/mcp-filepuff.
通过Claude代码安装
下载或构建二进制文件后，在Claude Code中配置它：
- 创建或编辑
~/.config/claude-code/claude_desktop_config.json:
{
"mcpServers": {
"filepuff": {
"command": "/usr/local/bin/mcp-filepuff",
"args": ["-workspace", "/path/to/your/workspace"],
"env": {
"MCP_LOG_LEVEL": "info"
}
}
}
}- 重新启动Claude代码 加载MCP服务器
- 验证 问克劳德：“你能ping一下filepuff服务器吗？”
请参阅 克劳德代码MCP文档 了解更多详情。
推荐的Claude代码配置
选择性工具延期
为了获得最佳性能，请在启动时加载最常用的工具，并推迟其余工具的加载 Anthropic推荐做法 立即装载3-5个高使用率工具：
{
"mcpServers": {
"filepuff": {
"command": "mcp-filepuff",
"args": ["-workspace", "."],
"alwaysAllow": ["file_read", "file_search", "edit_apply"]
}
}
}这保持 file_read, file_search，以及 edit_apply 立即可用，同时推迟不太常用的工具(ping, ast_query, symbol_at, find_definition, find_references).
系统提示指导
将以下内容添加到您的 CLAUDE.md 帮助Claude了解可用的工具类别：
You have access to filepuff MCP tools providing:
- File reading with AST symbol summaries (file_read)
- Fast regex search powered by ripgrep (file_search)
- Structural code pattern matching across 9+ languages (ast_query)
- LSP-powered go-to-definition, find-references, and symbol info (find_definition, find_references, symbol_at)
- AST-aware file editing with syntax validation (edit_apply)用法
运行服务器（独立）
./bin/mcp-filepuff -workspace /path/to/workspace命令行选项
-workspace string：工作区根目录（默认：当前目录）-log-level string：日志级别-调试、信息、警告、错误（默认值：“信息”）-log-file string：日志文件路径（默认值：stderr）
配置
服务器可以通过以下方式配置：
- 环境变量:
- MCP_WORKSPACE_ROOT：工作区根目录 - MCP_LSP_TIMEOUT：LSP超时持续时间（例如“10m”） - MCP_SEARCH_TIMEOUT：搜索超时持续时间（例如“1m”） - MCP_ENABLE_LSP：启用LSP功能（“真”/“假”） - MCP_FOLLOW_SYMLINKS：遵循符号链接（“true”/“false”） - MCP_RESPECT_GITIGNORE：尊重.gitignore文件（“true”/“false”）
- 配置文件：创建
.mcp-filepuff.json在工作区根目录中：
{
"enable_lsp": true,
"follow_symlinks": true,
"respect_gitignore": true
}Claude代码集成
要将mcp filepuff与Claude Code一起使用，请将其添加到mcp服务器配置中：
- 全局配置 (
~/.config/claude-code/mcp_servers.json):
{
"mcpServers": {
"filepuff": {
"command": "/path/to/mcp-filepuff",
"args": ["-workspace", "/path/to/your/workspace"]
}
}
}- 项目特定配置 (
.claude/mcp_servers.json在您的项目中）：
{
"mcpServers": {
"filepuff": {
"command": "mcp-filepuff",
"args": ["-workspace", "."]
}
}
}配置后，Claude Code将可以访问所有mcp filepuff工具以增强文件操作。
让Claude代码更喜欢Filepuff工具
默认情况下，Claude Code使用其内置的文件操作工具。要使其更喜欢filepuff的增强工具，请在您的 CLAUDE.md 文件：
全局配置 (~/.claude/CLAUDE.md):
# MCP Tool Preferences
When performing file operations, prefer filepuff MCP tools over built-in equivalents:
| Operation | Use This | Instead Of |
|-----------|----------|------------|
| Read files | `mcp__filepuff__file_read` | Read |
| Search content | `mcp__filepuff__file_search` | Grep |
| AST pattern search | `mcp__filepuff__ast_query` | Grep/Glob |
| Edit files | `mcp__filepuff__edit_apply` | Edit |
| Find definitions | `mcp__filepuff__find_definition` | Grep |
| Find references | `mcp__filepuff__find_references` | Grep |
| Symbol info | `mcp__filepuff__symbol_at` | - |
Benefits of filepuff tools:
- AST-aware operations that understand code structure
- LSP integration for accurate symbol navigation
- Syntax validation before applying edits您还可以将其放置在特定于项目的位置 CLAUDE.md 或 .claude/CLAUDE.md 文件。
可选：限制内置工具
要强制使用filepuff，请在中添加权限限制 .claude/settings.json:
{
"permissions": {
"deny": ["Read", "Edit", "Grep"]
}
}可用工具
ping
运行状况检查工具，用于验证服务器是否正在运行。
退货：“乒乓球”
______________________________________________________________________
file_search
使用ripgrep在文件中搜索文本模式。
参数:
pattern（必填）：搜索模式（默认为正则表达式）paths：搜索路径（默认为工作区根）file_types：要搜索的文件类型（例如，\[“go”、“ts”、“py”\]）ignore_case：不区分大小写的搜索regex：将模式视为正则表达式（默认值：true）context_lines：匹配项周围的上下文行数（默认值：2）max_results：要返回的最大结果数
______________________________________________________________________
file_read
使用可选的行范围和AST符号摘要读取文件内容。支持AI助手的令牌高效模式。
参数:
path（必填）：要读取的文件的路径line_start：起始行号（1-索引）line_end：结束行号（含）include_ast：包括AST符号摘要（函数、类、类型等）symbols_only: \[代币高效\] 仅返回符号摘要，不返回文件内容。需要include_ast=true。将令牌使用量减少约90-98%。max_lines: \[代币高效\] 返回的最大行数。适用于只需要预览的大文件。
AST输出示例:
**server.go** (245 lines, go)
Symbols:
func NewServer L12
func (Server).Start L45
struct Server L5
type Config L150
---
12│ func NewServer(config Config) *Server {
13│ return &Server{config: config}
14│ }令牌有效示例（仅符号）:
{"path": "server.go", "include_ast": true, "symbols_only": true}仅返回符号摘要（约500个标记，而不是完整文件的约8000个标记）：
**server.go** (245 lines, go)
Symbols:
func NewServer L12
func (Server).Start L45
struct Server L5
type Config L150令牌高效示例（max_lines）:
{"path": "server.go", "max_lines": 50}如果文件较长，则返回带有截断通知的前50行。
______________________________________________________________________
ast_query
使用结构模式匹配在代码文件中搜索AST模式。
参数:
pattern（必填）：带占位符的代码模式
- $NAME -捕获单个节点 - $$$ARGS -捕获多个节点 - $_ -通配符（匹配但不捕获）
language（必填）：目标语言（go、typescript、javascript、python、c、cpp）paths：搜索路径name_matches：按名称筛选的正则表达式模式name_exact：要匹配的确切名称kind_in：要匹配的节点类型（例如function_declaration）max_results：最大结果数（默认值：100）
示例:
// Find all Go functions returning error
{"pattern": "func $NAME($$$ARGS) error", "language": "go"}
// Find all Python classes
{"pattern": "class $NAME: $$$BODY", "language": "python"}
// Find React components (functions starting with uppercase)
{"pattern": "function $NAME($PROPS) { $$$BODY }", "language": "javascript", "name_matches": "^[A-Z]"}______________________________________________________________________
symbol_at
获取特定位置的符号信息。在可用时使用LSP，回退到AST。
参数:
file（必填）：文件路径line（必填）：行号（1-索引）column（必填）：列号（1-索引）
______________________________________________________________________
find_definition
在特定位置找到符号的定义。
参数:
file（必填）：文件路径line（必填）：行号（1-索引）column（必填）：列号（1-索引）
______________________________________________________________________
find_references
查找特定位置处对符号的所有引用。
参数:
file（必填）：文件路径line（必填）：行号（1-索引）column（必填）：列号（1-索引）include_declaration：在结果中包含声明（默认值：true）
______________________________________________________________________
edit_apply
对文件应用编辑。对具有语法验证的代码文件使用AST感知编辑，对其他文件使用基于文本的编辑。
参数:
file（必填）：要编辑的文件的路径operation（必填）：编辑操作（替换、插入前、插入后、删除）new_content：新内容（替换/插入操作所需）
AST模式选择器 （用于代码文件）：
selector_kind：要匹配的节点类型（例如function_declaration）selector_name：要匹配的符号名称
共享选择器:
selector_line：行号（1-索引）。对于AST模式：缩小搜索范围。对于文本模式：行范围的开始。selector_index：如果找到多个匹配项，则使用匹配项的索引（默认值：0）
文本模式选择器 （对于非代码文件或显式文本匹配）：
selector_line_end：范围选择的结束行号selector_text：要匹配的精确文本（必须是唯一的或使用selector_index）selector_pattern：要匹配的正则表达式模式
示例（AST模式-Go文件）:
{
"file": "server.go",
"operation": "replace",
"selector_kind": "function_declaration",
"selector_name": "Hello",
"new_content": "func Hello() {\n\tprintln(\"New Hello\")\n}"
}示例（文本模式-Markdown文件）:
{
"file": "README.md",
"operation": "replace",
"selector_text": "## Installation",
"new_content": "## Getting Started"
}示例（文本模式-带正则表达式的JSON）:
{
"file": "package.json",
"operation": "replace",
"selector_pattern": "\"version\":\\s*\"[^\"]+\"",
"new_content": "\"version\": \"2.0.0\""
}示例（文本模式-行范围）:
{
"file": "config.yaml",
"operation": "replace",
"selector_line": 5,
"selector_line_end": 10,
"new_content": "database:\n host: production.db.example.com\n port: 5432"
}支持的语言
| 语言 | 扩展 | 搜索 | AST | LSP | 编辑 |
|---|---|---|---|---|---|
| Go | .Go | Yes | Yes | gopls | Yes |
| TypeScript | .ts，.tsx | 是 | 是 | TypeScript语言服务器 | 是 |
| JavaScript | .js、.jsx、.mjs、.cjs | 是 | 是 | typescript语言服务器 | 是 |
| Python | .py，.pyw | 是 | 是 | pylsp | 是 |
| C | .C，.h | 是 | 是 | 叮当声 | 是 |
| C++ | .cpp、.cc、.cxx、.hpp、.hxx | 是 | 是 | 叮当声 | 是 |
| HTML | .HTML，.htm | 是 | 是 | - | 是 |
| Vue | .Vue | 是 | 是\* | - | 是 |
| React | .jsx，.tsx | 是 | 是 | typescript语言服务器 | 是 |
| 灵丹妙药 | .ex，.exs | 是 | 是 | 灵丹妙药ls | 是 |
\*Vue对模板部分使用HTML解析器
发展
构建
make build运行测试
make test棉绒
make lint清洁
make clean项目结构
.
├── cmd/
│ └── mcp-filepuff/ # Main entry point
├── internal/
│ ├── config/ # Configuration management
│ ├── edit/ # AST-aware editing engine
│ ├── lsp/ # LSP client and manager
│ ├── parser/ # Tree-sitter integration
│ ├── query/ # AST pattern matching
│ ├── search/ # Ripgrep wrapper
│ └── server/ # MCP server implementation
├── pkg/
│ └── protocol/ # Shared types
├── .github/
│ └── workflows/ # CI configuration
├── Makefile # Build automation
├── .goreleaser.yaml # Release configuration
└── TODO.md # Implementation roadmap建筑
高级概述
┌─────────────────────────────────────────────────────────┐
│ MCP Server │
├─────────────────────────────────────────────────────────┤
│ Tools: file_search, file_read, ast_query, symbol_at, │
│ find_definition, find_references, edit_apply, ping │
├─────────────────────────────────────────────────────────┤
│ Core Engines │
├───────────┬─────────────┬────────────┬─────────────────┤
│ Search │ Parser │ LSP │ Edit │
│ (ripgrep) │(tree-sitter)│ Manager │ Engine │
└───────────┴─────────────┴────────────┴─────────────────┘详细的序列图
LSP集成流程
下图显示了LSP请求（悬停、定义、引用）如何在系统中流动：
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant LSPMgr as LSP Manager
participant LSPSrv as LSP Server (gopls/etc)
participant FS as File System
Client->>Server: symbol_at(file, line, col)
activate Server
Server->>LSPMgr: GetServer(language)
activate LSPMgr
alt Server Not Running
LSPMgr->>LSPSrv: Start Process
LSPMgr->>LSPSrv: initialize request
LSPSrv-->>LSPMgr: capabilities
LSPMgr->>LSPSrv: initialized notification
end
LSPMgr-->>Server: ManagedServer
deactivate LSPMgr
Server->>LSPMgr: ensureDocumentOpen(file)
activate LSPMgr
alt Document Not Open
LSPMgr->>FS: ReadFile(path)
FS-->>LSPMgr: content
LSPMgr->>LSPSrv: textDocument/didOpen
end
LSPMgr-->>Server: ready
deactivate LSPMgr
Server->>LSPSrv: textDocument/hover
activate LSPSrv
LSPSrv-->>Server: HoverResult
deactivate LSPSrv
Server-->>Client: Symbol information
deactivate Server编辑操作流程
编辑引擎使用原子写入和验证来确保安全的文件修改：
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant Edit as Edit Engine
participant Parser as Parser Registry
participant FS as File System
Client->>Server: edit_apply(file, operation, selector, content)
activate Server
Server->>Edit: Apply(ctx, edit)
activate Edit
Edit->>Edit: lockFile(path)
Note over Edit: Per-file mutex prevents
concurrent edits
Edit->>FS: ReadFile(path)
FS-->>Edit: original content
alt AST-Aware Mode (code files)
Edit->>Parser: Parse(ctx, path, content)
activate Parser
Parser-->>Edit: ParseResult with AST
deactivate Parser
Edit->>Edit: resolveSelector(selector, tree)
Note over Edit: Find target node by
kind, name, line, index
Edit->>Edit: applyEdit(operation, node, content)
Note over Edit: Apply replace/insert/delete
with indentation preservation
Edit->>Parser: Parse(ctx, path, newContent)
activate Parser
Parser-->>Edit: Validate syntax
deactivate Parser
alt Syntax Error
Edit-->>Server: ValidationError
Server-->>Client: Error: invalid syntax
end
else Text Mode (non-code files)
Edit->>Edit: resolveTextSelector(selector)
Note over Edit: Find by text, pattern,
or line range
Edit->>Edit: applyTextEditOperation
end
Edit->>Edit: generateDiff(original, new)
Edit->>FS: Stat(path) - get permissions
Edit->>FS: WriteFile(path, content, perm)
Note over Edit,FS: Atomic write preserves
original permissions
Edit->>Edit: unlockFile(path)
Edit-->>Server: EditResult{Success, Diff}
deactivate Edit
Server-->>Client: Success + Diff
deactivate Server解析和缓存流
解析器使用基于内容的缓存来实现高效的AST重用：
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
participant Parser as Parser Registry
participant Cache as LRU Cache
participant TS as Tree-sitter
Client->>Server: file_read(path, include_ast=true)
activate Server
Server->>Parser: Parse(ctx, path, content)
activate Parser
Parser->>Parser: contentHash(content)
Note over Parser: xxHash64 for fast
content fingerprinting
Parser->>Cache: Get(hash)
activate Cache
alt Cache Hit
Cache-->>Parser: CachedTree
Parser->>Parser: cacheHits++
Note over Parser: ~100x faster than parsing
else Cache Miss
Cache-->>Parser: nil
deactivate Cache
Parser->>Parser: cacheMisses++
Parser->>Parser: GetParser(language)
Note over Parser: One parser per language,
reused across requests
Parser->>TS: ParseCtx(ctx, content)
activate TS
Note over TS: Tree-sitter parsing
with timeout support
TS-->>Parser: *sitter.Tree
deactivate TS
Parser->>Cache: Add(hash, tree)
activate Cache
Note over Cache: LRU eviction when
capacity reached (100 entries)
Cache-->>Parser: stored
deactivate Cache
end
Parser->>Parser: extractErrors(tree)
Parser->>Parser: ExtractSymbols(tree)
Parser-->>Server: ParseResult{Tree, Language, Errors, Symbols}
deactivate Parser
Server->>Server: generateASTSummary()
Server-->>Client: File content + Symbol summary
deactivate Server请求流摘要
flowchart TB
subgraph "MCP Protocol Layer"
A[MCP Client] --> B[MCP Server]
end
subgraph "Tool Handlers"
B --> C{Tool Type}
C -->|Search| D[file_search]
C -->|Read| E[file_read]
C -->|Query| F[ast_query]
C -->|LSP| G[symbol_at
find_definition
find_references]
C -->|Edit| H[edit_apply]
end
subgraph "Core Engines"
D --> I[Search Engine
ripgrep]
E --> J[Parser Registry]
F --> J
F --> K[Query Matcher]
G --> L[LSP Manager]
H --> M[Edit Engine]
M --> J
end
subgraph "External Systems"
I --> N[(File System)]
J --> O[Tree-sitter]
J --> P[(Parse Cache)]
L --> Q[gopls
typescript-language-server
pylsp
clangd]
M --> N
end故障排除
常见问题
“未找到ripgrep”错误
这 file_search 该工具需要ripgrep(rg)安装在您的PATH中。
解决方案：安装ripgrep：
# macOS
brew install ripgrep
# Ubuntu/Debian
sudo apt install ripgrep
# Windows (with Chocolatey)
choco install ripgrepLSP功能不工作
LSP功能（转到定义、查找引用、符号）需要安装语言服务器。
解决方案：安装相应的语言服务器：
# Go
go install golang.org/x/tools/gopls@latest
# TypeScript/JavaScript
npm install -g typescript-language-server typescript
# Python
pip install python-lsp-server
# C/C++
# macOS: brew install llvm
# Ubuntu: sudo apt install clangdAST解析无效代码失败
如果正确编译的代码的AST解析失败，则可能是树型语法限制。
解决方案:
- 确保文件具有正确的语言扩展名
- 检查是否存在Tree sitter语法不支持的异常语法
- 尝试使用
file_search用于基于文本的操作的工具
编辑操作失败，出现“语法错误”
编辑引擎在编辑前后验证语法。
解决方案:
- 确保
new_content在语法上对目标语言有效 - 检查选择器是否与一个节点完全匹配
超时错误
长时间运行的操作可能会超时。
解决方案：通过环境变量配置超时值：
export MCP_LSP_TIMEOUT="10m" # LSP operations (default: 5m)
export MCP_SEARCH_TIMEOUT="2m" # Search operations (default: 30s)权限被拒绝错误
服务器需要对工作区文件的读/写访问权限。
解决方案:
- 确保运行服务器的用户具有适当的文件权限
- 检查工作区路径是否正确且可访问
- 在macOS上，如果需要，授予终端/IDE全磁盘访问权限
调试日志记录
启用调试日志以排除问题：
./bin/mcp-filepuff -workspace /path/to/workspace -log-level debug -log-file /tmp/mcp-filepuff.log验证安装
使用 ping 用于验证服务器是否正常运行的工具：
{"tool": "ping"}预期响应： "pong"
许可证
MIT许可证