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

pip install unifiles-mcp

unifiles-mcp

from unifiles_mcp.main import mcp

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

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

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

# 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 格式的工作表数据

# 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 格式的查询结果

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

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

# 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="文档标题"
)

# 激活虚拟环境
.\.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/            # 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                   # 本文档