AI导哈

文件阅读与智能搜索服务器

FS-MCP是一个多功能的MCP服务器，提供智能文件读取、多格式文档处理和基于AI的语义搜索功能，适用于代码库管理和文档检索等场景。

  • by boleyn
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 boleyn/fs-mcp-server

使用说明

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

强大的MCP（模型上下文协议）服务器，提供智能文件读取和语义搜索功能

英语 | 中文

英语

🚀 特性

  • 🧠 智能文本检测：自动识别文本文件，不依赖于文件扩展名
  • 📄 多格式支持：处理文本文件和文档格式（Word、Excel、PDF等）
  • 🔒 安全第一：仅限制对配置的安全目录的访问
  • 📏 范围读数：支持读取大文件的特定行范围
  • 🔄 文档转换：通过缓存将文档自动转换为Markdown
  • 🔍 矢量搜索：基于AI嵌入的语义搜索
  • ⚡ 高性能：批处理和智能缓存支持
  • 🌐 多语言：支持英文和中文内容

📋 目录

🚀 快速开始

1.克隆和安装

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

使用紫外线（推荐）：

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 -人工智能和矢量搜索
  • 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
)

🔍 矢量搜索

能力

  • 语义理解：搜索“用户身份验证”找到“登录验证”代码
  • 同义词识别：搜索“数据库”找到“数据库”（中文）内容
  • 多语言支持：处理英语、中文和混合内容
  • 情境感知：了解代码语义和关系

搜索类型

  1. 语义搜索 (semantic)：人工智能驱动的理解
  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）

  • 微软: .docx, .xlsx, .pptx
  • OpenDocument 文件: .odt, .ods, .odp
  • 可移植文档格式: .pdf （文本提取）
  • 传统格式: .doc, .xls （有限支持）

🔒 安全功能

访问控制

  • 目录限制：访问权限仅限于 SAFE_DIRECTORY 和子目录
  • 路径横向保护：自动预防 ../ 攻击
  • Symlink控制：可配置的符号链接访问
  • 文件大小限制：防止读取超大文件

验证

  • 路径消毒：自动路径清理和验证
  • 权限检查：在访问之前验证读取权限
  • 错误处理：优雅的失败，信息丰富

🔗 整合

克劳德桌面

添加到您的Claude Desktop MCP配置中：

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

其他MCP客户端

连接到 http://localhost:3002 使用服务器发送事件（SSE）协议。

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.分叉和克隆

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.提交拉取请求

  • 清楚地描述你的变化
  • 参考任何相关问题
  • 确保所有测试通过

开发指南

  • 代码的风格：遵循PEP 8，使用黑色进行格式化
  • 测试：保持测试覆盖率在80%以上
  • 文档：更新README和文档字符串
  • 承诺：使用常规提交消息
  • 安全：遵循安全最佳实践

📋 路线图

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

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

📞 支持

中文

🚀 功能特点

  • 🧠 智能文本检测: 无需依赖扩展名，自动识别文本文件
  • 📄 多格式支持: 支持文本文件和文档格式（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工具 章节。

🔍 向量搜索功能

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

📁 支持的文件格式

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

🔒 安全特性

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

🔗 集成方式

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

🤝 贡献

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

📄 许可证

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

由以下材料制成❤️ 对于AI社区

⬆ 返回页首

相关 MCP