文件统计MCP工具

一个基于MCP（Model Context Protocol）的文件统计与分析工具，提供全面的文件系统分析功能。

🎯 功能特性

✅ 已实现功能

1. 通用文件统计

• 文件计数: 统计任意类型文件数量
• 文件列表: 列出指定类型或全部文件
• 分类统计: 按文件扩展名自动分类
• 递归支持: 可选是否包含子目录

2. 文件大小分析

• 目录总大小: 计算整个目录的存储占用
• 平均大小: 计算文件的平均大小
• 智能单位: 自动选择B、KB、MB、GB显示
• 大文件识别: 找出超过指定大小的文件

3. 文件系统维护

• 空文件夹检测: 识别无内容的空目录
• 重复文件查找: 基于文件内容MD5哈希值检测重复文件

4. 时间维度分析 (v2.3.0 新增)

• 最近文件统计: 获取最近N天修改的文件列表
• 日期范围查询: 按指定日期范围筛选文件
• 时间线视图: 按天/周/月分组显示文件活动
• 扩展名过滤: 支持按文件类型进行时间分析

🚧 待实现功能

• 访问频率统计
• 文件变化追踪
• 可视化报告生成
• 实时监控通知

🛠️ 技术架构

核心组件

• mcp_server.py: MCP服务端，包含所有文件分析工具
• test_client.py: 测试客户端，验证功能正确性
• requirements.txt: 依赖管理
• mcp.json: MCP服务配置文件

MCP服务配置

服务信息

• 服务名称: file-stats-mcp
• 版本: v2.3.0
• 协议: MCP (Model Context Protocol)
• 传输方式: stdio
• 运行命令: python mcp_server.py

依赖库

fastmcp>=0.4.1

服务元数据 (mcp.json)

{
  "name": "file-stats-mcp",
  "version": "2.3.0",
  "description": "基于MCP的文件统计与分析工具，提供全面的文件系统分析功能",
  "mcp": {
    "transport": "stdio",
    "command": "python",
    "args": ["mcp_server.py"]
  },
  "tools": [
    {
      "name": "count_files",
      "description": "统计指定目录中符合类型的文件数量"
    },
    {
      "name": "list_files", 
      "description": "列出指定目录中符合类型的文件详细信息"
    },
    {
      "name": "categorize_files_by_extension",
      "description": "按文件扩展名对文件进行分类统计"
    },
    {
      "name": "get_directory_size",
      "description": "计算目录的总大小"
    },
    {
      "name": "get_recent_files",
      "description": "获取最近N天修改的文件列表"
    },
    {
      "name": "get_file_timeline",
      "description": "获取文件时间线视图，按时间分组显示文件活动"
    },
    {
      "name": "find_empty_folders",
      "description": "查找指定目录中的空文件夹"
    },
    {
      "name": "find_duplicate_files",
      "description": "基于内容MD5值查找重复文件"
    }
  ]
}

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动MCP服务

python mcp_server.py

3. 运行测试

python test_client.py

🔌 MCP集成使用

作为MCP工具调用

服务启动后，可以通过MCP协议调用以下工具函数：

基础配置

{
  "mcpServers": {
    "file-stats": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}

工具调用示例

1. 文件统计

{
  "tool": "count_files",
  "arguments": {
    "directory": "~/Desktop",
    "extension": "pdf",
    "recursive": true
  }
}

2. 时间维度分析

{
  "tool": "get_recent_files",
  "arguments": {
    "directory": "~/Documents",
    "days": 7,
    "extension_filter": "txt"
  }
}

3. 文件时间线

{
  "tool": "get_file_timeline",
  "arguments": {
    "directory": "~/Downloads",
    "days": 30,
    "group_by": "day"
  }
}

Python集成示例

from mcp import Client

# 连接MCP服务
client = Client()
await client.connect_to_server("stdio", ["python", "mcp_server.py"])

# 调用工具函数
result = await client.call_tool("count_files", {
    "directory": "~/Desktop",
    "extension": "pdf"
})

print(f"PDF文件数量: {result}")

命令行测试

# 统计桌面PDF文件数量
echo '{"directory": "~/Desktop", "extension": "pdf"}' | python mcp_server.py

# 获取最近7天修改的文件
echo '{"directory": "~/Documents", "days": 7}' | python mcp_server.py

📊 输出示例

时间维度分析结果

==================================================
时间维度功能测试 (MCP客户端)
==================================================
最近7天修改文件: 7个
最新3个文件:
  - yellow.txt (10.0 B) - 2025-08-22 02:34:27
  - hello.txt (19.0 B) - 2025-08-22 02:34:08
  - 截屏2025-08-19 02.27.08.png (182.4 KB) - 2025-08-19 02:27:14

最近30天时间线:
总文件数: 15个
总大小: 5.8 MB
  2025-08-22: 2个文件, 29.0 B
  2025-08-19: 1个文件, 182.4 KB
  2025-08-18: 2个文件, 54.8 KB

🔧 开发状态

• v1.0.0: 基础文件统计功能 ✅
• v2.0.0: 文件大小分析功能 ✅
• v2.1.0: 空文件夹检测功能 ✅
• v2.2.0: 重复文件查找功能 ✅
• v2.3.0: 时间维度分析功能 ✅

🎯 下一步计划

1. 访问频率统计: 分析文件访问模式
2. 可视化报告: 生成图表和统计报告
3. 实时监控: 文件变化实时通知
4. 性能优化: 处理大目录的优化策略

⚙️ MCP配置参考

环境变量

# 可选配置
export MCP_FILE_STATS_TIMEOUT=30  # 超时时间(秒)
export MCP_FILE_STATS_MAX_DEPTH=10  # 最大递归深度

客户端配置示例

Claude Desktop配置

{
  "mcpServers": {
    "file-stats": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/project"
      }
    }
  }
}

VS Code配置

在.vscode/settings.json中添加：

{
  "mcp": {
    "servers": {
      "file-stats": {
        "command": "python",
        "args": ["mcp_server.py"],
        "cwd": "${workspaceFolder}"
      }
    }
  }
}

故障排除

常见问题

1. 权限问题: 确保有目标目录的读取权限
2. 路径问题: 使用绝对路径或正确展开用户目录(~)
3. Python环境问题: 确认Python版本>=3.8

调试模式

# 启用调试日志
DEBUG=1 python mcp_server.py

📄 许可证

MIT License