File Context Server

File Context Server

一个为大语言模型（LLM）提供文件系统上下文的模型上下文协议（MCP）服务。此服务支持 LLM 读取、搜索和分析代码文件，并具备高级缓存和实时文件监控功能。

功能

• 文件操作

  • 读取文件和目录内容
  • 列出文件及其详细元数据
  • 实时文件监控和缓存失效
  • 支持多种文件编码
  • 递归遍历目录
  • 按文件类型筛选

• 代码分析

  • 计算圈复杂度
  • 提取依赖项
  • 分析注释
  • 质量指标：
    • 检测重复行
    • 检测长行（>100 个字符）
    • 识别复杂函数
    • 行数统计（总行数、非空行数、注释行数）

• 智能缓存

  • LRU（最近最少使用）缓存策略
  • 文件变更时自动使缓存失效
  • 支持按大小管理缓存，并可配置限制
  • 缓存统计和性能指标
  • 缓存最近读取的结果，以便高效搜索

• 高级搜索

  • 正则表达式模式匹配
  • 提供带上下文的搜索结果，并可配置周边行数
  • 按文件类型筛选
  • 支持多模式搜索
  • 搜索缓存结果
  • 排除模式

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 File Context Server：

npx -y @smithery/cli install @bsmi021/mcp-file-context-server --client claude

手动安装

npm install @modelcontextprotocol/file-context-server

使用方法

启动服务

npx file-context-server

可用工具

1. list_context_files

   • 列出目录中的文件及其详细元数据

   {
     "path": "./src",
     "recursive": true,
     "includeHidden": false
   }
   

2. read_context

   • 读取文件或目录内容及其元数据

   {
     "path": "./src/index.ts",
     "encoding": "utf8",
     "maxSize": 1000000,
     "recursive": true,
     "fileTypes": ["ts", "js"]
   }
   

3. search_context

   • 搜索文件中的模式并提供上下文

   {
     "pattern": "function.*",
     "path": "./src",
     "options": {
       "recursive": true,
       "contextLines": 2,
       "fileTypes": ["ts"]
     }
   }
   

4. analyze_code

   • 分析代码文件的质量指标

   {
     "path": "./src",
     "recursive": true,
     "metrics": ["complexity", "dependencies", "quality"]
   }
   

5. cache_stats

   • 获取缓存统计和性能指标

   {
     "detailed": true
   }
   

错误处理

服务会提供包含特定错误代码的详细错误消息：

• FILE_NOT_FOUND：文件或目录不存在
• PERMISSION_DENIED：访问权限问题
• INVALID_PATH：文件路径格式无效
• FILE_TOO_LARGE：文件超出大小限制
• ENCODING_ERROR：文件编码问题
• UNKNOWN_ERROR：意外错误

配置

用于自定义的环境变量：

• MAX_CACHE_SIZE：缓存条目的最大数量（默认值：1000）
• CACHE_TTL：缓存生存时间，单位为毫秒（默认值：1 小时）
• MAX_FILE_SIZE：读取文件的最大字节数

开发

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Start in development mode
npm run dev

许可证

MIT

贡献

欢迎贡献！请阅读我们的贡献指南，了解行为准则和提交拉取请求的流程。

跨平台路径兼容性

**注意：**截至 2025 年 4 月，File Context Server 已更新所有文件和目录路径处理逻辑，以提升跨平台兼容性（Windows、macOS、Linux）：

• 所有 glob 模式内部均使用 POSIX 风格路径（正斜杠），确保在不同操作系统上都能一致地匹配文件。
• 所有文件系统操作（读取、写入、stat 等）均使用规范化的绝对路径，以确保可靠性。
• 如果你正在开发或扩展此服务，请在 glob 模式中使用 path.posix.join，并在访问文件系统时使用 path.normalize。
• 此更改可避免不同操作系统上的路径分隔符和文件匹配问题。

最终用户无需进行任何更改，但开发者在为项目做贡献时应遵循这些约定。