# unifiles-mcp

MCP server for [unifiles](https://github.com/Asheng008/unifiles) - unified file operations library.

## 简介

`unifiles-mcp` 是一个基于 [MCP Python SDK](https://pypi.org/project/mcp/) 官方 SDK 构建的 Model Context Protocol (MCP) 服务器，为 AI 助手提供统一的文件操作能力。它使用官方的 `FastMCP` 高级接口，封装了 `unifiles` 库的功能，支持 Excel、PDF、Word、SQLite 等多种文件格式的读取、写入、查询和管理。

## 功能特性

- ✅ **统一接口**: 通过 MCP 协议提供标准化的文件操作接口
- ✅ **多格式支持**: Excel (.xlsx, .xls), PDF (.pdf), Word (.docx), SQLite (.db, .sqlite)
- ✅ **类型安全**: 完整的类型注解，基于 Pydantic V2
- ✅ **异步优先**: 所有操作使用异步方式，提高性能
- ✅ **LLM 友好**: 优化的工具设计，减少调用次数

## 环境要求

- **Python**: 3.10+
- **操作系统**: Windows 10+, Linux, macOS 10.14+

## 安装

从源码安装（开发模式，含测试与类型检查等依赖）：

```powershell
git clone https://github.com/Asheng008/unifiles-mcp.git
cd unifiles-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```

仅安装运行依赖：

```powershell
pip install -e .
```

使用依赖锁文件安装（推荐用于生产环境）：

```powershell
pip install -r requirements.txt
```

若已发布到 PyPI：

```bash
pip install unifiles-mcp
```

## 快速开始

### 启动服务器

安装后可在终端直接运行：

```bash
unifiles-mcp
```

或从代码启动：

```python
from unifiles_mcp.main import mcp

if __name__ == "__main__":
    mcp.run()
```

### 使用 MCP 客户端连接

服务器启动后，可通过 MCP 客户端连接使用。以下为常见客户端的配置方式。

#### Cursor

在项目或用户配置的 `.cursor/mcp.json` 中加入（使用 PyPI 已发布包，需已安装 [uv](https://docs.astral.sh/uv/)）：

```json
{
  "mcpServers": {
    "unifiles-mcp": {
      "command": "uvx",
      "args": ["unifiles-mcp"]
    }
  }
}
```

使用本地开发环境时，可改为指定 venv 中的 Python 与模块（将 `D:\path\to\unifiles-mcp` 替换为你的项目根目录）：

```json
"unifiles-mcp": {
  "command": "D:\\path\\to\\unifiles-mcp\\.venv\\Scripts\\python.exe",
  "args": ["-m", "unifiles_mcp.main"]
}
```

#### Claude Desktop / 其他 MCP 客户端

在客户端的 MCP 配置文件中添加上述 `command` 与 `args`（或对应客户端的等价配置），指向 `unifiles-mcp` 或 `python -m unifiles_mcp.main` 即可。具体配置路径请参考各客户端的 MCP 文档。

### 使用示例

#### Excel 文件操作

```python
# 1. 检查 Excel 文件结构
result = await excel_inspect_file(
    file_path="data.xlsx",
    include_preview=True,
    preview_rows=3
)
# 返回：文件信息，包括所有工作表名称、列名和预览数据

# 2. 读取工作表内容
result = await excel_read_sheet(
    file_path="data.xlsx",
    sheet_name="Sheet1"
)
# 返回：JSON 格式的工作表数据
```

#### SQLite 数据库操作

```python
# 1. 检查数据库结构
result = await sqlite_inspect_database(
    db_path="database.db",
    include_preview=True
)
# 返回：数据库信息，包括所有表的结构和数据预览

# 2. 获取表结构
result = await sqlite_get_schema(
    db_path="database.db",
    table_name="users"
)
# 返回：字段名到类型的映射

# 3. 执行查询
result = await sqlite_query(
    db_path="database.db",
    sql="SELECT * FROM users WHERE age > :age",
    params={"age": 18}
)
# 返回：JSON 格式的查询结果
```

#### PDF 文本提取

```python
# 提取所有页面
result = await pdf_extract_text(
    file_path="document.pdf"
)

# 提取指定页面范围
result = await pdf_extract_text(
    file_path="document.pdf",
    page_range=(1, 5)  # 第 1 到第 5 页
)
```

#### Word 文档操作

```python
# 1. 检查文档结构（上帝视角）
result = await word_inspect_document(
    file_path="document.docx",
    extract_images=False
)
# 返回：段落数、表格数、图片数等统计信息

# 2. 提取完整文本
result = await word_extract_text(
    file_path="document.docx"
)
# 返回：文档完整文本（表格转为 Markdown）

# 3. 提取表格
result = await word_extract_tables(
    file_path="document.docx",
    output_format="md"
)
# 返回：Markdown 格式的表格

# 4. 写入文档
result = await word_write_document(
    content="文档内容",
    file_path="output.docx",
    title="文档标题"
)
```

## 核心工具（v0.1.3）

### Excel 工具
- `excel_inspect_file` - 检查 Excel 文件结构（"上帝视角"）
- `excel_read_sheet` - 读取 Excel 工作表内容

### PDF 工具
- `pdf_extract_text` - 提取 PDF 文本内容

### Word 工具
- `word_inspect_document` - 综合检查文档元素（"上帝视角"）
- `word_extract_text` - 提取文档完整文本
- `word_extract_tables` - 提取文档中的表格
- `word_extract_images` - 提取文档中的图片
- `word_write_document` - 写入 Word 文档

### SQLite 工具
- `sqlite_inspect_database` - 检查 SQLite 数据库（"上帝视角"）
- `sqlite_get_schema` - 获取表结构
- `sqlite_query` - 执行 SQL 查询

### 通用工具
- `ping` - 健康检查，返回 `pong` 表示服务运行中

## 开发

### 代码格式化与静态检查

```powershell
# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 使用 black 格式化代码
black src/

# 使用 ruff 检查代码
ruff check src/
```

### 类型检查

```powershell
# 使用 mypy 进行类型检查
mypy src/unifiles_mcp/
```

## 项目结构

```
unifiles-mcp/
├── src/
│   └── unifiles_mcp/
│       ├── __init__.py
│       ├── main.py              # MCP 服务器入口
│       ├── tools/               # MCP 工具
│       │   ├── __init__.py
│       │   ├── excel.py
│       │   ├── pdf.py
│       │   ├── word/            # Word 工具包
│       │   │   ├── __init__.py
│       │   │   ├── inspect.py
│       │   │   ├── extract.py
│       │   │   └── write.py
│       │   └── sqlite.py
│       └── utils/               # 工具函数
│           ├── __init__.py
│           ├── async_wrapper.py
│           └── validators.py
├── docs/                       # 文档
│   ├── 01-API.md              # API 文档
│   ├── 02-PYPI_RELEASE_CHECKLIST.md
│   └── 03-TESTING.md
├── .opencode/                  # OpenCode 配置
│   └── rules/                  # 项目规则
├── .cursor/                    # Cursor IDE 配置（可选）
│   ├── commands/               # Cursor 命令
│   ├── rules/                  # 项目规则
│   ├── skills/                 # Cursor Skills
│   └── mcp.json                # MCP 配置
├── LICENSE                     # MIT 许可证
├── publish_pypi.bat            # Windows 发布脚本
├── publish_pypi.sh             # Linux/macOS 发布脚本
├── requirements.txt            # 生产依赖
├── requirements-dev.txt        # 开发依赖（可选）
├── pyproject.toml              # 项目配置
├── CHANGELOG.md                # 更新日志
├── HISTORY.md                  # 对话与变更历史
├── AGENTS.md                   # AI Agent 开发规范
└── README.md                   # 本文档
```

## 文档

| 序号 | 文档 | 说明 |
|------|------|------|
| 01 | [API.md](./docs/01-API.md) | 详细的工具 API 说明和使用示例 |
| 02 | [PYPI_RELEASE_CHECKLIST.md](./docs/02-PYPI_RELEASE_CHECKLIST.md) | 发布到 PyPI 前的检查与步骤 |
| 03 | [TESTING.md](./docs/03-TESTING.md) | 测试指南（单元测试与集成测试） |

其他文档：
- [技术需求文档](./TRD.md) - 项目技术需求
- [开发规范](./AGENTS.md) - AI Agent 开发规范
- [更新日志](./CHANGELOG.md) - 版本变更记录
- [历史记录](./HISTORY.md) - 对话与变更历史

## 作者与维护者

- **作者**：Asheng (`w62745@qq.com`)
- **仓库**：[https://github.com/Asheng008/unifiles-mcp](https://github.com/Asheng008/unifiles-mcp)
- 欢迎通过 Issues 或 Pull Request 参与贡献。

## 许可证

本项目采用 [MIT License](./LICENSE)。

## 相关项目

- [unifiles](https://github.com/Asheng008/unifiles) - 统一的文件操作库
- [MCP Python SDK](https://pypi.org/project/mcp/) - Model Context Protocol 官方 Python SDK
- [MCP 官方文档](https://modelcontextprotocol.github.io/python-sdk/) - MCP Python SDK 完整文档