技术文档摘要

文件上下文服务器

这是一个提供文件系统上下文给大型语言模型（LLMs）的Model Context Protocol (MCP)服务器。此服务器使LLMs能够读取、搜索和分析代码文件，并具备高级缓存和实时文件监控功能。

功能

• 文件操作

  • 读取文件和目录内容
  • 列出带有详细元数据的文件
  • 实时文件监控和缓存失效
  • 支持多种文件编码
  • 递归目录遍历
  • 文件类型过滤

• 代码分析

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

• 智能缓存

  • 最近最少使用（LRU）缓存策略
  • 文件更改时自动缓存失效
  • 带有可配置限制的大小感知缓存
  • 缓存统计和性能指标
  • 最后读取结果缓存以提高搜索效率

• 高级搜索

  • 正则表达式模式匹配
  • 可配置上下文行的上下文感知结果
  • 文件类型过滤
  • 多模式搜索支持
  • 缓存结果搜索
  • 排除模式

安装

通过Smithery安装

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

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: 读取的最大文件大小（字节）

开发

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 开发模式启动
npm run dev

许可证

MIT

贡献

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

跨平台路径兼容性

注意： 自2025年4月起，File Context Server中的所有文件和目录路径处理已更新，以提高跨平台兼容性（Windows、macOS、Linux）：

• 所有通配符模式内部均使用POSIX风格路径（正斜杠），确保无论操作系统如何都能一致地匹配文件。
• 所有文件系统操作（读取、写入、状态等）均使用标准化的绝对路径以保证可靠性。
• 如果您正在开发或扩展该服务器，请在通配符模式中使用path.posix.join，在文件系统访问中使用path.normalize。
• 这一变更防止了不同操作系统上的路径分隔符和文件匹配问题。

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