技术文档摘要

中文

🚀 功能特点

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

---

<div align="center">

Made with ❤️ for the AI community

⬆ 返回顶部

</div>