文档管理MCP服务器

由Glenn Mossy创建\ \*博思艾伦汉密尔顿 *高级AI软件开发与数据科学家*\ 2024年11月27日

![Python 3.13+](https://www.python.org/downloads/) ![MCP](https://modelcontextprotocol.io/) ![License: MIT](https://opensource.org/licenses/MIT)

概述

一个生产就绪的企业级模型上下文协议（MCP）服务器，为AI助手提供全面的文档管理功能。该服务器采用现代Python 3.13构建，展示了先进的软件工程实践，包括干净的架构、全面的测试和多格式文档处理。

主要亮点

13个生产就绪的MCP工具 实现完整的文档生命周期管理
多格式支持：Word（.docx）、PDF、Excel（.xlsx）、Markdown和纯文本
高级搜索：使用FTS5索引和语义过滤进行全文搜索
版本控制：使用差异比较完成文档历史记录
企业功能：批量操作、分析和导出功能
稳健的体系结构：带FTS5的SQLite，异步操作，全面的错误处理

特性

核心文档操作

创建带有标题、内容、标签、元数据和状态的文档
阅读具有可选版本历史记录的文档
更新具有自动版本控制的文档
删除或安全地归档文档

高性能

全文搜索 FTS5对标题和内容进行索引
基于标签的过滤 使用AND逻辑获得精确结果
版本控制 具有完整的历史和比较工具
内容分析 包括字数统计、阅读时间和关键字提取
多格式导出 （Markdown、HTML、JSON、TXT、Word、PDF、Excel）
批量操作 用于高效的标签管理
综合统计 和系统监控

文档格式支持

微软Word （.docx）-使用元数据提取进行读写
PDF -支持多页阅读和创建
微软Excel （.xlsx）-多页提取和创建
微软幻灯片 （.pptx）-幻灯片提取和演示文稿创建
标记语言 （.md）-完全支持格式化
纯文本 （.txt）-通用兼容性

技术架构

技术栈

Python 3.13 -性能改进的最新Python
FastMCP -支持异步的现代MCP服务器框架
带FTS5的SQLite -全文搜索索引以提高性能
Pydantic v2 -类型安全数据验证和序列化
openpyxl -Excel文件处理
python docx -Word文档操作
python pptx -PowerPoint演示文稿处理
pypdf和报告实验室 -PDF阅读和生成

设计模式

清洁建筑 -明确界限的关注点分离
异步/等待 -无阻塞I/O可扩展性
类型安全 -全面的类型提示和Pydantic模型
错误处理 -优雅的降级，带有详细的错误消息
版本控制 -具有完整审计跟踪的自动版本控制

代码质量

综合测试 -所有主要部件的单元测试
文档 -详细的文档字符串和用户指南
类型检查 -完全兼容mypy
代码格式化 -黑色和褶边，保持一致性
最佳实践 -遵循PEP 8和现代Python标准

快速开始

安装

使用紫外线（推荐）：

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Navigate to MCP document server subproject
cd backend/mcp_document_server

# Install Python 3.13 and sync dependencies
uv python install 3.13
uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

使用pip：

cd backend/mcp_document_server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .[dev]

运行服务器

服务器使用stdio传输进行MCP通信：

cd backend/mcp_document_server
source .venv/bin/activate  # or source venv/bin/activate
python document_mcp_server.py

服务器将启动并等待stdin/stdout上的MCP协议消息。它旨在与Claude Desktop或MCP Inspector等MCP客户端一起使用。

测试服务器

选项1:MCP检查员（推荐）

MCP检查器提供了一个与服务器交互的web UI。使用以下选项之一：

选项A——直接（无配置，最简单）

cd /Users/glennmossy/dpg-ai-projects/claude_document_mcp_server
npx @modelcontextprotocol/inspector python backend/mcp_document_server/document_mcp_server.py

选项B——使用检查器配置文件

创建 inspector.config.json 在repo根目录中：

{
  "mcpServers": {
    "document-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "backend/mcp_document_server",
        "python",
        "document_mcp_server.py"
      ]
    }
  }
}

使用该服务器启动检查器：

cd /Users/glennmossy/dpg-ai-projects/claude_document_mcp_server
npx @modelcontextprotocol/inspector --config inspector.config.json --server document-mcp

然后：

打开终端中打印的URL（包含MCP_PROXY_AUTH_TOKEN）。
在左侧面板中，传输类型应为STDIO。单击“连接”。
在侧栏中，选择服务器 document_mcp 看看工具。

故障排除：

如果在使用Streamable HTTP时看到HTTP 404或“连接错误”，请切换到STDIO并单击连接（此服务器不公开/sse）。
如果Inspector说找不到服务器，请确保您的配置使用密钥 mcpServers （不是 servers)你通过了 --config.
如果你不小心启动了裸机 npx 然后掉进了 sh-3.2$，类型 exit 并运行完整命令。

可以粘贴到MCP检查器中的JSON示例

所有工具都接受JSON。下面是常见任务的粘贴示例。

列出所有文档（分页，最新的优先）——使用工具 document_search

{
  "response_format": "json",
  "limit": 100,
  "offset": 0
}

按关键字和标签搜索——使用工具 document_search

{
  "query": "quarterly report",
  "tags": ["finance", "2024"],
  "status": "published",
  "limit": 20,
  "offset": 0,
  "response_format": "json"
}

创建文档--使用工具 document_create

{
  "title": "Q4 Report",
  "content": "Executive summary...\n\nHighlights...",
  "tags": ["finance", "2024"],
  "status": "draft",
  "metadata": { "author": "Glenn", "department": "Finance" }
}

获取文档（包含内容和版本）--使用工具 document_get

{
  "document_id": "doc_abc123def456",
  "include_content": true,
  "include_versions": true,
  "response_format": "json"
}

更新文档（如果内容更改，则创建版本）--使用工具 document_update

{
  "document_id": "doc_abc123def456",
  "content": "Updated body...",
  "tags": ["finance", "2024", "reviewed"],
  "version_comment": "Added CFO notes"
}

存档与永久删除——使用工具 document_delete

存档（默认）：

{ "document_id": "doc_abc123def456", "permanent": false }

永久删除：

{ "document_id": "doc_abc123def456", "permanent": true }

列出所有标签——使用工具 document_list_tags

{
  "sort_by_count": true,
  "min_count": 1,
  "response_format": "json"
}

系统统计——使用工具 document_statistics

{ "response_format": "json" }

选项2：使用Claude Desktop进行手动测试

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "document-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/backend/mcp_document_server/document_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/.venv/lib/python3.13/site-packages"
      }
    }
  }
}

然后重新启动Claude Desktop，工具将可用。

选项3：快速语法检查

# Verify Python syntax
python -m py_compile document_mcp_server.py

# Check for import errors
python -c "import document_mcp_server; print('✓ Server loads successfully')"

快速测试工作流程

在MCP Inspector中运行服务器后：

创建文档:

- 工具： document_create - 输入： {"title": "Test Doc", "content": "Hello world", "tags": ["test"]}

搜索它:

- 工具： document_search - 输入： {"query": "hello"}

获取统计数据:

- 工具： document_statistics - 输入： {}

分析内容:

- 工具： document_analyze - 输入： {"document_id": ""}

可用工具

记录CRUD操作

`document_create`

使用自动版本控制创建新文档。

{
  "title": "Q3 Financial Report",
  "content": "## Executive Summary\n\nThis quarter showed...",
  "tags": ["finance", "quarterly", "2024"],
  "status": "draft",
  "metadata": {
    "author": "Jane Smith",
    "department": "Finance"
  }
}

`document_get`

检索包含可选内容和版本历史记录的文档。

{
  "document_id": "doc_abc123def456",
  "include_content": true,
  "include_versions": true,
  "response_format": "markdown"
}

`document_update`

使用版本控制更新文档内容、标签或元数据。

{
  "document_id": "doc_abc123def456",
  "content": "Updated content...",
  "tags": ["finance", "quarterly", "2024", "reviewed"],
  "version_comment": "Added review notes from CFO"
}

`document_delete`

存档或永久删除文档。

{
  "document_id": "doc_abc123def456",
  "permanent": false
}

搜索和发现

`document_search`

具有全文、标签过滤和分页功能的强大搜索。

{
  "query": "financial report quarterly",
  "tags": ["finance"],
  "status": "published",
  "created_after": "2024-01-01T00:00:00Z",
  "sort_by": "updated_at",
  "sort_order": "desc",
  "limit": 20,
  "offset": 0,
  "response_format": "json"
}

`document_list_tags`

列出所有带有使用次数的标签。

{
  "sort_by_count": true,
  "min_count": 1,
  "response_format": "markdown"
}

版本控制

`document_get_version`

检索特定的历史版本。

{
  "document_id": "doc_abc123def456",
  "version_number": 2,
  "response_format": "json"
}

`document_compare_versions`

比较两个版本以查看更改。

{
  "document_id": "doc_abc123def456",
  "version_a": 1,
  "version_b": 3
}

分析和出口

`document_analyze`

获取内容统计数据并提取关键字。

{
  "document_id": "doc_abc123def456",
  "include_stats": true,
  "include_keywords": true,
  "response_format": "markdown"
}

输出包括：

字数、字符数
行数和段落数
平均字长
预计阅读时间
前15个关键词

`document_export`

导出为Markdown、HTML、JSON或纯文本。

{
  "document_id": "doc_abc123def456",
  "format": "html",
  "include_metadata": true
}

批量操作

`document_bulk_tag`

在多个文档中添加或删除标签。

{
  "document_ids": ["doc_abc123", "doc_def456", "doc_ghi789"],
  "add_tags": ["reviewed", "2024"],
  "remove_tags": ["draft"]
}

系统监控

`document_statistics`

获取全面的系统统计数据。

{
  "response_format": "markdown"
}

提供：

文档和存储使用总量
状态分发（草稿/发布/存档）
版本统计
近期活动
版本最多的文档

数据模型

文档结构

{
  "id": "doc_abc123def456",
  "title": "Document Title",
  "content": "Document content in markdown or plain text",
  "tags": ["tag1", "tag2"],
  "status": "draft|published|archived",
  "metadata": {"key": "value"},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T14:20:00Z",
  "size": 1234,
  "content_hash": "sha256_hash"
}

版本结构

{
  "document_id": "doc_abc123def456",
  "version_number": 1,
  "title": "Title at this version",
  "content": "Content at this version",
  "tags": ["tags", "at", "version"],
  "status": "status_at_version",
  "metadata": {},
  "created_at": "2024-01-15T10:30:00Z",
  "comment": "Version change description",
  "content_hash": "sha256_hash"
}

响应格式

所有数据返回工具都支持两种格式：

Markdown（默认）

具有标题、列表和格式的人类可读格式：

# Document Analysis

**Document**: Q3 Financial Report
**ID**: `doc_abc123def456`

## Statistics

- **Word Count**: 1,234
- **Estimated Reading Time**: 6 minutes
...

JSON

机器可读结构化数据：

{
  "document_id": "doc_abc123def456",
  "title": "Q3 Financial Report",
  "stats": {
    "word_count": 1234,
    "reading_time_minutes": 6
  }
}

数据库模式

服务器使用SQLite和下表：

文件 -主文件存储
文档_版本 -版本历史
文档_fts -全文搜索索引（FTS5）

数据库和文档存储在首次运行时会自动初始化。

配置

默认常数（可在源代码中配置）：

DATABASE_PATH: ./documents.db
DOCUMENTS_DIR: ./document_storage
MAX_CONTENT_SIZE：10 MB
MAX_TAGS：每份文件50
MAX_SEARCH_RESULTS: 100
DEFAULT_PAGE_SIZE: 20

最佳实践

工具注释

所有工具均包含MCP注释：

readOnlyHint：工具是否修改数据
destructiveHint：是否执行破坏性操作
idempotentHint：重复呼叫是否具有相同的效果
openWorldHint：是否与外部服务交互

错误处理

所有工具返回结构化错误响应，其中包含：

清除错误消息
具体解决建议
一致的JSON格式

分页

搜索工具支持分页：

limit：每页显示结果（1-100）
offset：跳过分页计数
响应包括 has_more 和 next_offset

集成示例

Claude桌面配置

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "document-mcp": {
      "command": "python",
      "args": ["/path/to/document_mcp_server.py"]
    }
  }
}

示例工作流

创建和发布报告：

document_create -创建初稿
document_update -添加内容修订
document_analyze -检查统计数据
document_update -将状态设置为“已发布”

组织文件：

document_search -查找相关文档
document_bulk_tag -应用一致的标签
document_list_tags -审查标签组织

审查变更：

document_get -获取包含历史记录的当前版本
document_compare_versions -看看有什么变化
document_get_version -检索特定版本

发展

项目结构

backend/
  mcp_document_server/
    document_mcp_server.py    # Main MCP server implementation
    document_parsers.py       # Document parsing utilities (Word, PDF, Excel, PPTX, etc.)
    docs/                     # MCP/server docs
    document_storage/         # Storage directory (auto-created)
    documents.db              # SQLite database (auto-created)
    tests/                    # Test suite and sample office files
    pyproject.toml            # MCP server project configuration
    uv.lock                   # uv dependency lockfile
    Dockerfile                # Container image for this server
    README-mcp.md             # Subproject README

dist/
  document_mcp-*.whl, *.tar.gz # Built artifacts

代码质量

代码库如下：

PEP 8风格指南
全程键入提示
Pydantic v2用于验证
全面的文档字符串
共享公用设施的干燥原则

测试

# Install dev dependencies
pip install -e .[dev]

# Run linting
ruff check .
black --check .
mypy .

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请确保：

代码遵循现有模式
所有工具都有适当的注释
输入验证使用Pydantic
错误消息是可操作的
文档已更新

项目报告

代码行: 7,300+
测试覆盖率：综合单元和集成测试
文档：5个详细指南+内联文档
支持格式：5（Word、PDF、Excel、Markdown、文本）
MCP工具：13个生产就绪端点
依赖项：最小、维护良好的包装
演出：对大多数行动的反应低于秒

技能展示

该项目展示了以下方面的熟练程度：

软件工程

干净的代码架构 -模块化设计，关注点明确分离
API设计 -RESTful原则在MCP工具设计中的应用
数据库设计 -FTS5索引的高效模式
错误处理 -全面的异常处理和验证
文档 -专业级文件和示例

数据科学与人工智能

文档处理 -多格式解析和文本提取
搜索与检索 -使用排名算法进行全文搜索
内容分析 -统计分析和关键字提取
版本控制 -数据版本控制和差异算法
人工智能集成 -LLM工具使用的MCP协议

现代Python

Python 3.13 -最新语言功能和优化
异步编程 -异步的非阻塞I/O
类型安全 -全面的类型提示和Pydantic验证
包管理 -现代UV模具
测试 -单元测试和集成测试

DevOps和工具

Git -版本控制和存储库管理
虚拟环境 -依赖隔离
CI/CD就绪 -结构化以实现自动化部署
交叉平台的 -适用于macOS、Linux和Windows

关于创造者

格伦·莫西 是一名高级人工智能软件开发人员和数据科学家，在构建生产就绪的人工智能系统方面拥有专业知识。该项目展示了以下能力：

从头开始设计和实现复杂系统
编写干净、可维护且记录良好的代码
将多种技术集成到有凝聚力的解决方案中
遵循软件工程最佳实践
交付企业级应用程序

联系方式和链接

项目日期2024年11月26日
角色：创建者和首席开发人员

致谢

根据以下内容构建模型上下文协议规范和最佳实践。

______________________________________________________________________

*该项目是一个展示先进软件工程、人工智能集成和数据科学能力的投资组合。*

Claude Document

快速接入

详细介绍

文档管理MCP服务器

概述

主要亮点

特性

核心文档操作

高性能

文档格式支持

技术架构

技术栈

设计模式

代码质量

快速开始

安装

运行服务器

测试服务器

可以粘贴到MCP检查器中的JSON示例

快速测试工作流程

可用工具

记录CRUD操作

document_create

document_get

document_update

document_delete

搜索和发现

document_search

document_list_tags

版本控制

document_get_version

document_compare_versions

分析和出口

document_analyze

document_export

批量操作

document_bulk_tag

系统监控

document_statistics

数据模型

文档结构

版本结构

响应格式

Markdown（默认）

JSON

数据库模式

配置

最佳实践

工具注释

错误处理

分页

集成示例

Claude桌面配置

示例工作流

发展

项目结构

代码质量

测试

许可证

贡献

项目报告

技能展示

软件工程

数据科学与人工智能

现代Python

DevOps和工具

关于创造者

联系方式和链接

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`document_create`

`document_get`

`document_update`

`document_delete`

`document_search`

`document_list_tags`

`document_get_version`

`document_compare_versions`

`document_analyze`

`document_export`

`document_bulk_tag`

`document_statistics`