# filemcp

**Repository Path**: fexcode/filemcp

## Basic Information

- **Project Name**: filemcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 MCP Server v2.3.0

基于 MCP (Model Context Protocol) 的全能工具服务器，提供文件编辑、Git 操作、代码质量检查、系统监控等 **39 个工具**。

![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)
![Version](https://img.shields.io/badge/Version-2.3.1-orange.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

## ✨ 特性

- 🎯 **AI 优先设计** - 采用 SEARCH/REPLACE 黄金编辑模式
- ✏️ **意图式编辑** - 基于内容匹配，无需行号
- 🔒 **原子性操作** - 要么全部成功，要么全部回滚
- 🎨 **模糊匹配** - 自动处理缩进、空格差异
- 👁️ **预览模式** - `dry_run` 先预览再应用
- 🌐 **Streamable HTTP** - 标准 HTTP 协议，支持 Token 认证
- 📦 **模块化架构** - 7 大工具模块，37 个工具

## 📦 安装

### 方式一：uv（推荐）

```bash
git clone https://gitee.com/fexcode/filemcp.git
cd filemcp
uv sync
uv run python3 streamable_server.py
```

### 方式二：pip

```bash
git clone https://gitee.com/fexcode/filemcp.git
cd filemcp
pip install starlette uvicorn black ruff
python3 streamable_server.py
```

> 💡 建议使用 Python 3.11+，推荐配合 venv 虚拟环境。
>
> 📱 **Android/Termux** 用户可直接使用此方式，`psutil` 在 Android 上不可用但不影响核心功能，系统工具会自动降级为命令行模式。

### 方式三：一键安装脚本

```bash
git clone https://gitee.com/fexcode/filemcp.git
cd filemcp
chmod +x install.sh
./install.sh
```

安装脚本会自动：
- 检测并安装 Python 依赖
- 创建工作目录 `~/mcpworkdir`
- 可选安装为 systemd 服务
- 可选创建全局命令 `mcp-server`

## 🚀 启动服务

```bash
# Python 直接启动（适配所有环境，推荐 Termux 使用）
python3 streamable_server.py

# 后台运行
nohup python3 streamable_server.py > ~/mcpworkdir/mcp-server.log 2>&1 &

# 使用启动脚本
./start-filesystem.sh                 # 前台
./start-filesystem.sh --background    # 后台

# systemd 服务（仅 Linux 服务器）
sudo systemctl start mcp-filesystem
```

服务器默认启动在 `http://0.0.0.0:8080`。

## ⚙️ 配置文件

### 配置文件位置

- 主配置: `config.json` (项目根目录)
- 示例文件: `config.example.json`

### 配置优先级 (高→低)

1. 环境变量
2. config.json
3. 默认值

### 完整配置示例

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "workers": 1
  },
  "security": {
    "token": "your-secret-token-here",
    "token_min_length": 16,
    "admin_token": "",
    "admin_password": ""
  },
  "paths": {
    "work_dir": "~/mcpworkdir",
    "temp_dir": "temp"
  },
  "logging": {
    "level": "INFO",
    "file": "~/mcpworkdir/mcp-server.log"
  },
  "git": {
    "github_mirrors": [
      "https://gitclone.com/github.com/",
      "https://kkgithub.com/",
      "https://bgithub.xyz/"
    ],
    "download_proxies": [
      "https://gh-proxy.com/",
      "https://ghproxy.net/"
    ]
  }
}
```

### 配置项说明

| 配置路径 | 类型 | 默认值 | 说明 |
|:---|:---|:---|:---|
| `server.host` | string | `0.0.0.0` | 监听地址 |
| `server.port` | int | `8080` | 监听端口 |
| `server.workers` | int | `1` | 工作进程数 |
| `security.token` | string | `""` | API鉴权Token，为空则不鉴权 |
| `security.token_min_length` | int | `16` | Token最小长度 |
| `security.admin_token` | string | `""` | Admin管理Token |
| `paths.work_dir` | string | `~/mcpworkdir` | 工作目录 |
| `paths.temp_dir` | string | `temp` | 临时目录（相对于工作目录） |
| `logging.level` | string | `INFO` | 日志级别 |
| `logging.file` | string | `~/mcpworkdir/mcp-server.log` | 日志文件路径 |

### 环境变量

| 环境变量 | 配置路径 | 示例 |
|:---|:---|:---|
| `MCP_HOST` | `server.host` | `127.0.0.1` |
| `MCP_PORT` | `server.port` | `9090` |
| `MCP_TOKEN` | `security.token` | `my-secret-token-1234` |
| `MCP_WORK_DIR` | `paths.work_dir` | `/data/mcp` |
| `MCP_LOG_LEVEL` | `logging.level` | `DEBUG` |

```bash
# 使用环境变量启动
export MCP_TOKEN=my-secret-token-1234
export MCP_PORT=9090
python3 streamable_server.py
```

## 🔒 鉴权配置

### Token鉴权机制

- **方式**: Bearer Token (HTTP Authorization Header)
- **配置**: `security.token` 或 `MCP_TOKEN` 环境变量
- **最小长度**: 16字符（可通过 `token_min_length` 配置）

### 启用鉴权

**方式一：配置文件**

```json
{
  "security": {
    "token": "my-secret-token-min-16chars"
  }
}
```

**方式二：环境变量**

```bash
export MCP_TOKEN=my-secret-token-min-16chars
python3 streamable_server.py
```

### 请求示例

```bash
# 带Token请求
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer my-secret-token-min-16chars" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list"}'

# 调用工具
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer my-secret-token-min-16chars" \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"read_file","arguments":{"path":"example.py"}}}'
```

### 无Token模式

当 `security.token` 为空时，服务端跳过鉴权，适合本地开发环境。

```bash
# 直接请求，无需Authorization头
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/list"}'
```

### 鉴权失败响应

```json
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Unauthorized"
  }
}
```

## 📊 Admin管理后台

### 访问地址

| 端点 | 方法 | 说明 |
|:---|:---|:---|
| `/admin` | GET | 管理后台页面 |
| `/admin/api/stats` | GET | 统计数据API |
| `/health` | GET | 健康检查 |
| `/ready` | GET | 就绪检查 |

### 管理后台功能

- **工具调用统计**: 总调用次数、各工具调用量
- **错误统计**: 失败次数、错误率
- **运行时间**: 服务启动时长
- **调用历史**: 最近50条调用记录
- **每日趋势**: 按日期统计调用量

### 访问方式

```bash
# 浏览器访问管理页面
http://localhost:8080/admin

# API获取统计数据
curl http://localhost:8080/admin/api/stats

# 健康检查
curl http://localhost:8080/health
```

### 统计数据示例

```json
{
  "total_calls": 150,
  "errors": 3,
  "uptime": "2d 5h 30m 15s",
  "tools": {
    "read_file": {"calls": 50, "errors": 0, "total_duration": 1200},
    "edit_file": {"calls": 30, "errors": 2, "total_duration": 800}
  },
  "history": [
    {"tool": "read_file", "time": "2024-01-15T10:30:00", "success": true, "duration": 25}
  ]
}
```

### 健康检查响应

```json
{
  "status": "healthy",
  "version": "2.3.0",
  "uptime": "2d 5h 30m",
  "tools_count": 37
}
```

### 数据存储

- 统计文件: `data/tool_stats.json`
- 自动保存: 每次调用后自动写入
- 优雅关闭: 收到 SIGTERM/SIGINT 信号时保存

## 持续集成

项目使用 Gitea Actions 自动进行代码质量检查与格式化：

```yaml
# .gitea/workflows/lint.yml
# 每次 push 自动执行：
#   - isort 导入排序
#   - black 代码格式化  
#   - ruff lint 检查
# 自动修复并提交，保持代码风格统一
```

## 🧰 工具模块一览

### 📁 文件操作 (FileTools)

| 工具 | 功能 | 关键参数 |
|:---|:---|:---|
| `read_file` | 读取文件（支持分页） | `path`, `offset`, `limit` |
| `edit_file` | SEARCH/REPLACE 编辑 | `path`, `edits[]`, `dry_run` |
| `list_directory` | 列出目录内容 | `path` |
| `create_directory` | 创建目录 | `path` |
| `move_file` | 移动/重命名文件 | `source`, `destination` |
| `delete_file` | 删除文件/空目录 | `path` |

### 🔍 搜索工具 (SearchTools)

| 工具 | 功能 |
|:---|:---|
| `search_files` | 按文件名搜索（支持通配符） |
| `search_content` | 按内容关键词搜索 |
| `find_large_files` | 查找大文件 |

### 💻 系统工具 (SystemTools)

| 工具 | 功能 |
|:---|:---|
| `execute_command` | 执行系统命令 |
| `get_system_info` | 获取系统信息 |
| `get_process_list` | 获取进程列表 |
| `get_disk_usage` | 获取磁盘使用情况 |
| `get_memory_info` | 获取内存使用情况 |

### 🌿 Git 工具 (GitTools)

| 工具 | 功能 |
|:---|:---|
| `git_clone` | 克隆仓库（支持镜像加速） |
| `github_download` | 下载 GitHub 文件 |
| `git_status` / `git_log` / `git_diff` | 状态查看 |
| `git_add` / `git_commit` / `git_push` / `git_pull` | 提交推送 |
| `git_branch` / `git_remote` / `git_config` | 分支与配置 |
| `git_init` | 初始化仓库 |

### ✅ 代码质量 (CodeQualityTools)

| 工具 | 功能 |
|:---|:---|
| `python_lint` | Python 代码检查 (ruff) |
| `python_format` | Python 代码格式化 (black) |
| `code_stats` | 代码统计（行数/函数/类） |
| `python_docstring_check` | 文档字符串检查 |

### ⏰ 定时任务 (CronTools)

| 工具 | 功能 |
|:---|:---|
| `cron_list` | 列出定时任务 |
| `cron_add` | 添加定时任务 |
| `cron_remove` | 删除定时任务 |
| `cron_enable` | 启用/禁用任务 |

### 🌲 目录树 (TreeTools)

| 工具 | 功能 |
|:---|:---|
| `tree` | 显示目录结构 |
| `tree_summary` | 目录结构摘要 |

### 🔄 v2.3.1 新特性

- 🚀 **优化 CI/CD 流水线** — 通过 Gitea Actions 实现自动化代码检查
- 🎯 **改进模糊匹配** — 编辑时更精准地定位代码块
- 🧹 **代码质量升级** — 全面采用 ruff 进行静态检查

## 📝 核心用法示例

### 编辑文件（SEARCH/REPLACE）

```json
{
  "path": "example.py",
  "edits": [
    {
      "old_text": "print('Hello')",
      "new_text": "print('Hello World')",
      "description": "修改输出"
    }
  ],
  "dry_run": false
}
```

### 预览修改

```json
{
  "path": "config.py",
  "edits": [
    {"old_text": "DEBUG = false", "new_text": "DEBUG = true"}
  ],
  "dry_run": true
}
```

### 读取文件

```json
{
  "path": "example.py",
  "offset": 1,
  "limit": 20
}
```

## 🏗️ 项目结构

```
filemcp/
├── streamable_server.py       # MCP 服务器主入口
├── search_replace_editor.py   # SEARCH/REPLACE 核心引擎
├── admin.py                   # 管理后台模块
├── test_new_tools.py          # 测试文件
├── pyproject.toml             # 项目配置
├── config.example.json        # 配置示例
├── data/                      # 数据目录
│   └── tool_stats.json        # 工具调用统计
├── static/                    # 静态文件
│   └── admin.html             # 管理后台页面
├── tools/                     # 工具模块
│   ├── file_tools.py          # 文件操作
│   ├── search_tools.py        # 搜索工具
│   ├── system_tools.py        # 系统工具
│   ├── git_tools.py           # Git 工具
│   ├── code_quality_tools.py  # 代码质量
│   ├── cron_tools.py          # 定时任务
│   └── tree_tools.py          # 目录树
└── common/                    # 通用模块
    ├── config.py              # 配置管理
    ├── response.py            # 响应格式
    ├── version.py             # 版本号
    └── ...
```

## 📄 License

MIT