FS-MCP: Universal File Reader & Intelligent Search MCP Server

FS-MCP：通用文件读取与智能搜索 MCP 服务

---

English

🚀 功能特性

• 🧠 智能文本检测：自动识别文本文件，不依赖文件扩展名
• 📄 多格式支持：支持文本文件和文档格式（Word、Excel、PDF 等）
• 🔒 安全优先：仅允许访问已配置的安全目录
• 📏 范围读取：支持读取大型文件中的指定行范围
• 🔄 文档转换：自动将文档转换为 Markdown 并缓存
• 🔍 向量搜索：由 AI 嵌入提供支持的语义搜索
• ⚡ 高性能：支持批处理和智能缓存
• 🌐 多语言：支持英文和中文内容

📋 目录

• 快速开始
• 安装
• 配置
• MCP 工具
• 向量搜索
• 支持的格式
• 安全特性
• 集成
• 开发
• 贡献
• 许可证

🚀 快速开始

1. 克隆并安装

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

使用 uv（推荐）：

uv sync

使用 pip：

pip install -r requirements.txt  # If you have a requirements.txt
# OR install directly
pip install fastmcp>=2.0.0 langchain>=0.3.0 python-dotenv>=1.1.0

2. 环境配置

在项目根目录中创建 .env 文件：

# Security Settings
SAFE_DIRECTORY=.                    # Directory restriction (required)
MAX_FILE_SIZE_MB=100                # File size limit in MB

# Encoding Settings
DEFAULT_ENCODING=utf-8

# AI Embeddings Configuration (for vector search)
OPENAI_EMBEDDINGS_API_KEY=your-api-key
OPENAI_EMBEDDINGS_BASE_URL=http://your-embedding-service/v1
EMBEDDING_MODEL_NAME=BAAI/bge-m3    # Or your preferred model
EMBEDDING_CHUNK_SIZE=1000

3. 启动服务

python main.py

服务将在 http://localhost:3002 上启动，并自动构建向量索引。

🛠️ 安装

系统要求

• Python：3.12 或更高版本
• 操作系统：Windows、macOS、Linux
• 内存：建议为向量搜索配置 4GB 以上
• 存储空间：缓存和索引需要 1GB 以上

依赖项

核心依赖项在 pyproject.toml 中管理：

• fastmcp>=2.0.0 - MCP 服务框架
• langchain>=0.3.0 - AI 和向量搜索
• python-dotenv>=1.1.0 - 环境管理
• 文档处理库（pandas、openpyxl、python-docx 等）

⚙️ 配置

环境变量

变量	默认值	描述
SAFE_DIRECTORY	.	文件访问的根目录
MAX_FILE_SIZE_MB	100	最大文件大小限制
DEFAULT_ENCODING	utf-8	默认文件编码
OPENAI_EMBEDDINGS_API_KEY	-	嵌入服务的 API 密钥
OPENAI_EMBEDDINGS_BASE_URL	-	嵌入服务 URL
EMBEDDING_MODEL_NAME	BAAI/bge-m3	用于生成嵌入的 AI 模型
EMBEDDING_CHUNK_SIZE	1000	处理文本块的大小

高级配置

对于生产环境部署，可考虑：

• 设置速率限制
• 配置日志轮换
• 使用外部向量数据库
• 设置监控

🔧 MCP 工具

1. view_directory_tree

用途：以树形格式显示目录结构

view_directory_tree(
    directory_path=".",     # Target directory
    max_depth=3,           # Maximum depth
    max_entries=300        # Maximum entries to show
)

2. read_file_content

用途：读取文件内容，支持指定行范围

read_file_content(
    file_path="example.py",  # File path
    start_line=1,           # Start line (optional)
    end_line=50             # End line (optional)
)

3. search_documents

用途：对文档进行智能语义搜索

search_documents(
    query="authentication logic",     # Search query
    search_type="semantic",          # semantic/filename/hybrid/extension
    file_extensions=".py,.js",       # File type filter (optional)
    max_results=10                   # Maximum results
)

4. rebuild_document_index

用途：重建用于搜索的向量索引

rebuild_document_index()  # No parameters needed

5. get_document_stats

用途：获取索引统计信息和系统状态

get_document_stats()  # Returns comprehensive stats

6. list_files

用途：根据模式匹配列出目录中的文件

list_files(
    directory_path="./src",  # Directory to list
    pattern="*.py",         # File pattern
    include_size=True       # Include file sizes
)

7. preview_file

用途：快速预览文件内容

preview_file(
    file_path="example.py",  # File to preview
    lines=20                # Number of lines
)

🔍 向量搜索

功能

• 语义理解：搜索“用户身份验证”可找到“登录验证”代码
• 同义词识别：搜索“database”可找到“数据库”内容
• 多语言支持：支持英语、中文及混合内容
• 上下文感知：理解代码语义及关系

搜索类型

1. 语义搜索（semantic）：由 AI 驱动的理解
2. 文件名搜索（filename）：快速匹配文件名
3. 扩展名搜索（extension）：按文件类型筛选
4. 混合搜索（hybrid）：结合语义搜索与文件名搜索

技术栈

• 嵌入模型：BAAI/bge-m3（1024 维向量）
• 向量数据库：ChromaDB
• 文本切分：智能语义分块
• 增量更新：基于哈希的变更检测

📁 支持的格式

自动检测的文本文件

• 编程语言：.py、.js、.ts、.java、.cpp、.c、.go、.rs 等
• 配置文件：.json、.yaml、.toml、.ini、.xml、.env
• 文档：.md、.txt、.rst
• Web 文件：.html、.css、.scss
• 数据文件：.csv、.tsv
• 无扩展名文件（自动检测）

文档格式（自动转换为 Markdown）

• Microsoft Office：.docx、.xlsx、.pptx
• OpenDocument：.odt、.ods、.odp
• PDF：.pdf（文本提取）
• 旧版格式：.doc、.xls（支持有限）

🔒 安全功能

访问控制

• 目录限制：访问范围限制为 SAFE_DIRECTORY 及其子目录
• 路径遍历防护：自动防止 ../ 攻击
• 符号链接控制：可配置符号链接访问权限
• 文件大小限制：防止读取过大的文件

验证

• 路径净化：自动清理并验证路径
• 权限检查：访问前验证读取权限
• 错误处理：发生故障时优雅处理并提供说明性消息

🔗 集成

Claude Desktop

将其添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "fs-mcp": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/fs-mcp",
      "env": {
        "SAFE_DIRECTORY": "/your/project/directory"
      }
    }
  }
}

其他 MCP 客户端

使用 Server-Sent Events（SSE）协议连接到 http://localhost:3002。

API 集成

该服务提供标准 MCP 端点，可与任何兼容 MCP 的客户端集成。

🏗️ 项目结构

fs-mcp/
├── main.py                    # Main MCP server
├── src/                       # Core modules
│   ├── __init__.py           # Package initialization
│   ├── file_reader.py        # Core file reading logic
│   ├── security_validator.py # Security and validation
│   ├── text_detector.py      # Intelligent file detection
│   ├── config_manager.py     # Configuration management
│   ├── document_cache.py     # Document caching system
│   ├── file_converters.py    # Document format converters
│   ├── dir_tree.py          # Directory tree generation
│   ├── embedding_config.py   # AI embedding configuration
│   ├── codebase_indexer.py   # Vector indexing system
│   ├── codebase_search.py    # Search engine
│   ├── index_scheduler.py    # Index scheduling
│   └── progress_bar.py       # Progress display utilities
├── tests/                    # Test suite
├── cache/                    # Document cache (auto-created)
├── logs/                     # Log files (auto-created)
├── pyproject.toml           # Project configuration
├── .env.example             # Environment template
├── .gitignore              # Git ignore rules
└── README.md               # This file

💻 开发

设置开发环境

# Clone repository
git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# Install with development dependencies
uv sync --group dev

# OR with pip
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test
pytest tests/test_file_reader.py

代码质量

# Format code
black src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

调试

实时监控日志：

tail -f logs/mcp_server_$(date +%Y%m%d).log

🤝 贡献

欢迎贡献！以下是开始参与的步骤：

1. Fork 并克隆

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

2. 创建功能分支

git checkout -b feature/your-feature-name

3. 进行修改

• 遵循现有代码风格
• 为新功能添加测试
• 根据需要更新文档

4. 测试你的修改

pytest
black src/ tests/
flake8 src/ tests/

5. 提交 Pull Request

• 清晰描述你的修改
• 引用相关问题
• 确保所有测试通过

开发指南

• 代码风格：遵循 PEP 8，使用 Black 格式化代码
• 测试：保持测试覆盖率高于 80%
• 文档：更新 README 和文档字符串
• 提交：使用约定式提交消息
• 安全：遵循安全最佳实践

📋 路线图

• 增强 PDF 处理：改进表格和图像提取
• 更多嵌入模型：支持本地模型
• 实时索引：文件系统监视器
• 高级搜索：正则表达式、邻近搜索、分面搜索
• 性能优化：异步处理、改进缓存
• Web 界面：可选的管理 Web UI
• 插件系统：自定义文件类型处理器
• 企业功能：身份验证、速率限制、监控

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 Acknowledgments

• FastMCP - MCP server framework
• LangChain - AI integration
• ChromaDB - Vector database
• BGE-M3 - Embedding model

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Check the docs/ folder (when available)

---

中文

🚀 功能特点

• 🧠 智能文本检测: 无需依赖扩展名，自动识别文本文件
• 📄 多格式支持: 支持文本文件和文档格式（Word、Excel、PDF等）
• 🔒 安全验证: 只允许读取配置的安全目录中的文件
• 📏 按行读取: 支持指定行范围读取，便于处理大文件
• 🔄 文档转换: 自动将文档格式转换为Markdown并缓存
• 🔍 向量搜索: 基于AI嵌入的语义搜索
• ⚡ 高性能: 支持批量文件处理和智能缓存
• 🌐 多语言: 支持中英文内容处理

🚀 快速开始

1. 克隆和安装

git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# 推荐使用 uv
uv sync

# 或使用 pip
pip install -r requirements.txt

2. 环境配置

创建 .env 文件：

# 安全设置
SAFE_DIRECTORY=.                    # 目录访问限制（必需）
MAX_FILE_SIZE_MB=100                # 文件大小限制（MB）

# 编码设置
DEFAULT_ENCODING=utf-8

# AI嵌入配置（用于向量搜索）
OPENAI_EMBEDDINGS_API_KEY=your-api-key
OPENAI_EMBEDDINGS_BASE_URL=http://your-embedding-service/v1
EMBEDDING_MODEL_NAME=BAAI/bge-m3    # 或您偏好的模型
EMBEDDING_CHUNK_SIZE=1000

3. 启动服务器

python main.py

服务器将在 http://localhost:3002 启动并自动建立向量索引。

🛠️ MCP工具说明

详细的工具使用方法请参考英文部分的 MCP Tools 章节。

🔍 向量搜索功能

• 概念匹配：搜索"用户认证"能找到"登录验证"相关代码
• 同义词理解：搜索"database"能找到"数据库"相关内容
• 多语言支持：同时理解中英文代码和注释
• 上下文理解：理解代码的语义和上下文关系

📁 支持的文件格式

详细的格式支持请参考英文部分的 Supported Formats 章节。

🔒 安全特性

• 路径验证: 只允许访问配置的安全目录及其子目录
• 文件大小限制: 防止读取过大文件
• 路径遍历防护: 自动防止 ../ 等路径遍历攻击
• 符号链接控制: 可配置是否允许访问符号链接

🔗 集成方式

Claude Desktop集成

在 Claude Desktop 的 MCP 配置中添加：

{
  "mcpServers": {
    "fs-mcp": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/fs-mcp",
      "env": {
        "SAFE_DIRECTORY": "/your/project/directory"
      }
    }
  }
}

💻 开发

开发环境设置

# 克隆仓库
git clone https://github.com/yourusername/fs-mcp.git
cd fs-mcp

# 安装开发依赖
uv sync --group dev

运行测试

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=src

🤝 贡献

欢迎贡献代码！请参考英文部分的 Contributing 章节了解详细信息。

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

---