Metadata-Version: 2.4
Name: office4ai
Version: 0.1.3
Summary: A powerful Office document management environment designed for AI agents to interact with Office documents
Project-URL: Homepage, https://github.com/JQQ/office4ai
Project-URL: Repository, https://github.com/JQQ/office4ai
Project-URL: Documentation, https://github.com/JQQ/office4ai#readme
Project-URL: Issues, https://github.com/JQQ/office4ai/issues
Author-email: JQQ <jqq1716@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,ai-agent,document-management,docx,libreoffice,office,pptx,xlsx
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: cachetools>=5.3.2
Requires-Dist: confz>=2.1.0
Requires-Dist: cryptography>=42.0
Requires-Dist: docker>=7.0.0
Requires-Dist: emoji>=2.11.1
Requires-Dist: gymnasium>=0.29.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: loguru>=0.7.2
Requires-Dist: mcp>=1.19.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: paramiko>=3.4.0
Requires-Dist: pexpect>=4.9.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic<3.0.0,>=2.11.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-pptx>=0.6.23
Requires-Dist: python-socketio>=5.11.0
Requires-Dist: regex>=2025.10.23
Requires-Dist: simple-parsing>=0.1.5
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: websockets>=12.0
Description-Content-Type: text/markdown

# Office4AI

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/version-0.1.1rc1-green.svg)](https://github.com/JQQ/office4ai)

**Office4AI** 是一个 MCP Server，让 AI Agent 通过 Office Add-In 实时读写 Office 文档。

> **当前状态：** Word（9 个工具）已实现，PowerPoint 和 Excel 开发中。

## 支持平台

| 平台        | 状态   | 工具数 |
|-------------|--------|--------|
| Word        | 已就绪 | 9      |
| PowerPoint  | 规划中 | —      |
| Excel       | 规划中 | —      |

## 快速开始

### 1. 安装证书（仅首次）

Office4AI 使用 HTTPS 与 Office Add-In 通信。运行 `setup` 生成并安装本地 CA 证书：

```bash
uvx office4ai-mcp setup
```

将生成本地 CA 和服务器证书，并将 CA 安装到系统信任存储（需要管理员权限）。

### 2. 启动服务

```bash
uvx office4ai-mcp serve
```

### 3. 配置 MCP 客户端

#### Claude Code（推荐）

```bash
claude mcp add office4ai -- uvx --from office4ai office4ai-mcp
```

#### Claude Desktop / Cursor 等 MCP 客户端

在 MCP 配置文件中添加：

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

### 4. 安装 Office Add-In

Office Add-In 通过 Socket.IO 连接 Microsoft Office 与 MCP Server。

> Add-In 安装说明将另行提供，敬请关注。

## 可用工具

### Word 工具（9 个）

| 工具 | 说明 |
|------|------|
| `word_get_selected_content` | 获取当前选中内容——文本、元素及元数据 |
| `word_get_visible_content` | 获取当前视口中可见的内容 |
| `word_insert_text` | 在光标处插入文本，支持格式（粗体、斜体、字体、颜色、样式） |
| `word_append_text` | 在文档开头或末尾追加文本 |
| `word_replace_text` | 查找并替换文本（等同 Ctrl+H），支持大小写敏感和全词匹配 |
| `word_insert_image` | 插入 base64 编码的图片，支持尺寸和替代文字 |
| `word_insert_table` | 插入表格，指定行列数、数据和样式 |
| `word_insert_equation` | 插入 LaTeX 公式（默认为行内公式） |
| `word_insert_toc` | 插入目录（可配置标题级别） |

所有工具均需要 `document_uri` 参数来标识目标文档。

## CLI 命令参考

```
office4ai-mcp <command>
```

| 命令      | 说明 |
|-----------|------|
| `serve`   | 启动 MCP Server（未指定命令时的默认行为） |
| `setup`   | 生成证书并将 CA 安装到系统信任存储 |
| `cleanup` | 从信任存储移除 CA 并删除证书文件 |

### 服务器选项

可通过 CLI 参数或环境变量设置：

| 选项 | 环境变量 | 默认值 | 说明 |
|------|---------|--------|------|
| `--transport` | `TRANSPORT` | `stdio` | MCP 传输方式：`stdio`、`sse` 或 `streamable-http` |
| `--host` | `HOST` | `127.0.0.1` | 服务器绑定地址 |
| `--port` | `PORT` | `8000` | MCP HTTP 端口（用于 `sse`/`streamable-http`） |
| `--socketio-port` | `SOCKETIO_PORT` | `3000` | Socket.IO 端口（Add-In 连接） |

### 证书位置

证书默认存储在 `~/.office4ai/certs/`，可通过 `OFFICE4AI_CERT_DIR` 环境变量覆盖。

### 日志位置

日志默认存储在平台标准目录，可通过 `OFFICE4AI_LOG_DIR` 环境变量覆盖：

| 平台    | 默认路径                                         |
|---------|--------------------------------------------------|
| macOS   | `~/Library/Logs/office4ai`                       |
| Linux   | `~/.local/state/office4ai/log`                   |
| Windows | `C:\Users\<user>\AppData\Local\office4ai\Logs`   |

设置 `OFFICE4AI_LOG_DIR=""` 可禁用文件日志。

## 系统要求

- Python 3.10+
- macOS 或 Windows
- 支持 Add-In 的 Microsoft Office（Word 桌面版或 Word Online）

## 开发

开发环境配置、常用命令、代码规范和贡献指南请参考 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)。

## 许可证

MIT 许可证 - 详见 [LICENSE](LICENSE)。

## 联系方式

- 作者：JQQ
- 邮箱：jqq1716@gmail.com
- GitHub：[@JQQ](https://github.com/JQQ)
