doc-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个 Word 文档编辑 MCP 服务器，用于与 Claude Code CLI 集成，提供完整的 Word 文档操作能力。基于 MCP (Model Context Protocol) 协议，通过 python-docx 库实现 Word 文档的创建、编辑、格式化等功能。

核心架构

MCP 服务器架构

• 服务入口: src/server.py - MCP 服务器主入口，注册所有工具并处理工具调用
• 工具模块: src/tools/ - 按功能分类的工具实现
• 辅助工具: src/utils/ - 文档管理和错误处理

工具模块分类

工具按功能分为以下模块：

1. document_basic.py - 文档基础操作（创建、读取、复制、获取信息）
2. content_edit.py - 内容编辑（段落、标题、查找替换）
3. table_ops.py - 表格操作（创建、编辑、格式化、读取）
4. style_format.py - 样式格式（分页符、页边距）
5. image_ops.py - 图片操作（插入图片）
6. list_ops.py - 列表操作（有序/无序列表）
7. advanced.py - 高级功能（脚注、页眉页脚、大纲）
8. interface_doc.py - 接口文档生成（标准格式的接口文档表格）

文档管理机制

重要: DocumentManager 类采用无缓存设计，每次操作都重新加载文档：

• get_or_open() - 每次都从磁盘重新加载文档
• save() - 保存文档到磁盘
• 这种设计确保多个操作之间的数据一致性，避免缓存导致的数据丢失

常用命令

安装依赖

pip install -r requirements.txt

运行 MCP 服务器

# 方式1: 直接运行
python -m src.server

# 方式2: 使用批处理脚本（Windows）
start_mcp.bat

# 方式3: 使用 Python 脚本
python run_server.py

开发工具

# 代码格式化
black src/ --line-length 100

# 代码检查
ruff check src/

添加新工具的步骤

1. 在对应的工具模块中实现函数

   • 例如在 src/tools/content_edit.py 中添加新的内容编辑功能
   • 函数必须是 async 函数
   • 使用 DocumentManager 进行文档操作
   • 返回格式: {"success": True/False, "message": "...", ...}

2. 在 src/server.py 中注册工具

   • 在 list_tools() 函数中添加 Tool 定义
   • 定义工具名称、描述和 inputSchema

3. 在 call_tool() 函数中添加调用处理

   • 添加 elif name == "your_tool_name": 分支
   • 调用对应的工具函数

关键设计模式

错误处理

• 所有工具函数使用统一的错误处理机制
• 返回 JSON 格式: {"success": bool, "error": str, "message": str}
• 使用 error_handler.py 中的 DocxError 自定义异常

文档操作流程

# 标准操作流程
doc_manager = DocumentManager()
doc = doc_manager.get_or_open(filename)  # 加载文档
# ... 执行操作 ...
doc_manager.save(filename, doc)  # 保存文档

索引约定

• 段落索引: 从 0 开始
• 表格索引: 从 0 开始
• 行/列索引: 从 0 开始
• 范围操作使用 start_index 和 end_index，均为包含边界