unifiles-mcp 0.1.3

MCP server for unifiles - unified file operations library. Provides Excel, PDF, Word, and SQLite file operations through Model Context Protocol.

unifiles-mcp

MCP server for unifiles - unified file operations library.

简介

unifiles-mcp 是一个基于 MCP Python SDK 官方 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+

安装

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

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

仅安装运行依赖：

pip install -e .

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

pip install -r requirements.txt

若已发布到 PyPI：

pip install unifiles-mcp

快速开始

启动服务器

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

unifiles-mcp

或从代码启动：

from unifiles_mcp.main import mcp

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

使用 MCP 客户端连接

服务器启动后，可以通过 MCP 客户端（如 Claude Desktop）连接使用。

使用示例

Excel 文件操作

# 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 数据库操作

# 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 文本提取

# 提取所有页面
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 文档读取

result = await word_read_document({
    "file_path": "document.docx"
})
# 返回：文档的文本内容

核心工具（v0.1.2）

Excel 工具

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

PDF 工具

• pdf_extract_text - 提取 PDF 文本内容

Word 工具

• word_read_document - 读取 Word 文档内容

SQLite 工具

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

通用工具

• ping - 健康检查，返回 pong 表示服务运行中

开发

代码格式化与静态检查

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

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

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

类型检查

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

项目结构

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

文档

• API 文档 - 详细的工具 API 说明和使用示例
• PyPI 发布清单 - 发布到 PyPI 前的检查与步骤
• 技术需求文档 - 项目技术需求
• API 设计文档 - API 设计方案
• API 设计评审 - API 设计评审文档
• 开发规范 - AI Agent 开发规范
• 更新日志 - 版本变更记录
• 历史记录 - 对话与变更历史

作者与维护者

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

许可证

本项目采用 MIT License。

相关项目

• unifiles - 统一的文件操作库
• MCP Python SDK - Model Context Protocol 官方 Python SDK
• MCP 官方文档 - MCP Python SDK 完整文档