🚀 Python Alfresco MCP Server v1.1
Python Alfresco MCP Server v1.1是一款用于Alfresco内容服务的模型上下文协议（MCP）服务器，具备丰富的工具和功能，可用于搜索和内容管理。它提供了完整的文档、示例以及针对各种MCP客户端的配置，能帮助用户高效地进行内容管理和搜索操作。
🚀 快速开始
安装Python
你需要安装Python 3.10+，若未安装，可从Python.org Downloads下载最新的3.13.x版本。
UV/UVX设置（推荐）
UV 是用 Rust 编写的现代Python包管理器，提供 uv（包管理器）和 uvx（工具运行器）。由于其编译性质和优化的依赖解析，它比 pip 快得多。
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
curl -LsSf https://astral.sh/uv/install.sh | sh
pip install uv
uv --version
uvx --version
UV参考链接：
安装方式选择
选项A：UVX - 现代工具运行器（推荐给用户）
UVX 是UV的工具运行器，类似于 pipx，但更快、更现代。它会自动处理隔离和全局可用性：
uvx python-alfresco-mcp-server --help
为什么选择UVX：UVX结合了 pipx（隔离环境 + 全局可用性）的优点，以及UV基于Rust的速度和现代依赖解析能力。它会在首次使用时自动安装包。
选项B：UV - 现代包管理器（推荐用于开发）
UV 是用 Rust 编写的现代Python包管理器，能自动处理一切。由于其编译性质和优化的依赖解析，它比 pip 快得多。
uv tool install python-alfresco-mcp-server
uv tool run python-alfresco-mcp-server --help
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server
uv run python-alfresco-mcp-server --help
选项C：传统方法（pip和pipx）
有关传统Python包管理方法，请参阅 使用pip和pipx安装。
注意：你仍然需要使用适当的配置来配置你的MCP客户端（Claude Desktop、MCP Inspector等）。有关客户端配置详细信息，请参阅下面的 MCP客户端设置和使用 部分。
源代码安装（用于开发）
若要进行开发或访问最新功能：
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server
uv run python-alfresco-mcp-server --help
uv sync
uv sync --extra dev
uv sync --extra test
uv sync --extra all
配置Alfresco连接
选项1：环境变量
export ALFRESCO_URL="http://localhost:8080"
export ALFRESCO_USERNAME="admin"
export ALFRESCO_PASSWORD="admin"
export ALFRESCO_VERIFY_SSL="false"
$env:ALFRESCO_URL="http://localhost:8080"
$env:ALFRESCO_USERNAME="admin"
$env:ALFRESCO_PASSWORD="admin"
$env:ALFRESCO_VERIFY_SSL="false"
set ALFRESCO_URL=http://localhost:8080
set ALFRESCO_USERNAME=admin
set ALFRESCO_PASSWORD=admin
set ALFRESCO_VERIFY_SSL=false
选项2：.env文件（推荐 - 跨平台）
cp sample-dot-env.txt .env
copy sample-dot-env.txt .env
ALFRESCO_URL=http://localhost:8080
ALFRESCO_USERNAME=admin
ALFRESCO_PASSWORD=admin
ALFRESCO_VERIFY_SSL=false
注意：出于安全考虑，.env 文件不会被提交到git。请使用 sample-dot-env.txt 作为模板。
📖 有关完整的设置选项，请参阅 配置指南
Alfresco安装
如果你还没有安装Alfresco服务器，可以从Github获取社区版的Docker镜像：
git clone https://github.com/Alfresco/acs-deployment.git
切换到Docker Compose目录
cd acs-deployment/docker-compose
编辑community-compose.yaml
- 注意：你可能需要注释掉除8161之外的activemq端口
ports:
- "8161:8161"
使用Docker Compose启动Alfresco
docker-compose -f community-compose.yaml up
MCP服务器启动
使用UVX（推荐 - 自动隔离和全局可用）
uvx python-alfresco-mcp-server
uvx python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003
uvx python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001
使用UV（用于开发或源代码安装）
uv run python-alfresco-mcp-server
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003
uv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001
使用传统方法（pip/pipx）
有关 pip 和 pipx 的使用说明，请参阅 使用pip和pipx安装。
MCP客户端设置和使用
Python-Alfresco-MCP-Server已在Claude Desktop上进行了测试，推荐将其作为最终用户的MCP客户端。同时，它也在MCP Inspector上进行了测试，推荐开发人员使用该工具来测试带有参数值的工具。
🤖 Claude Desktop（适用于Windows（已测试）和MacOS（未测试））
📖 完整设置指南：Claude Desktop设置指南
📥 下载Claude Desktop（免费版和专业版）
- 下载Claude Desktop - 官方Anthropic下载页面
- 仅适用于 Windows 和 macOS（无Linux版本）
- 免费层 包括完整的MCP支持和Claude Sonnet 4访问权限，但有一定限制，较旧的Claude模型（Claude Opus 4仅在专业版中可用）
🔧 根据安装方法进行Claude Desktop配置
Claude Desktop的配置因MCP服务器的安装方式而异：
1. UVX（推荐 - 现代工具运行器）
{
"command": "uvx",
"args": ["python-alfresco-mcp-server", "--transport", "stdio"]
}
- 示例配置文件：
- UVX会自动处理隔离和全局可用性
- 最快、最现代的方法
2. UV（开发或源代码安装）
{
"command": "uv",
"args": ["run", "python-alfresco-mcp-server", "--transport", "stdio"],
"cwd": "C:\\path\\to\\python-alfresco-mcp-server"
}
- 示例配置文件：
- 使用
uv run 并将 cwd 指向你的 项目目录
- UV会自动找到并使用项目目录中的
.venv
- 适用于源代码安装和
uv tool install 之后
3. 传统方法（pipx/pip）
有关传统安装方法，请参阅 使用pip和pipx安装，其中涵盖：
🔐 逐个工具的权限系统
Claude Desktop会在首次使用每个工具时单独提示你。由于此MCP服务器有15个工具，如果你使用所有功能，可能会看到多达15个权限提示。对于每个工具，你可以选择：
- "仅允许一次" - 仅批准本次使用该工具
- "始终允许" - 自动批准该特定工具的所有未来使用（推荐用于常规使用）
此逐个工具的安全功能可确保你对可执行的外部工具保持精细控制。
🛡️ 病毒扫描器注意事项：如果你使用Norton 360等病毒检查器，当你第一次看到pip、pipx、uv、uvx或python-alfresco-mcp-server.exe的 "检查中" 消息时，不要担心 - 这是正常的安全扫描行为。
使用工具：
- 自然聊天 表达你对文档和搜索的需求
- 提及 "Alfresco" 以确保使用MCP服务器（例如，"在Alfresco中..."）
- 使用与工具相关的关键词 - 提及与工具名称相近的内容
- 后续提示 会基于之前的上下文了解文档信息
示例1：文档管理
- 上传一个简单的文本文档："请在存储库共享文件夹中创建一个名为 'claude_test_doc-25 07 25 101 0 AM.txt' 的文件，内容为：'This is a test document created by Claude via MCP.'，描述为 'Test document uploaded via Claude MCP'"
- 更新属性："将此文档的描述属性设置为 'my desc'"
- 检出文档
- 取消检出
- 再次检出
- 作为主要版本检入
- 下载文档
- 从 "C:\1 sample files\cmispress.pdf" 上传第二个文档
注意：Claude会在第二次尝试时自动使用base64编码进行首次上传
示例2：搜索操作
"使用Alfresco，请测试所有3种搜索方法和CMIS查询"：
- 基本搜索 "txt" 文档，最多返回10个结果
- 高级搜索2024-01-01之后创建的文档，最多返回25个结果
- 元数据搜索cm:title包含 "test" 的文档，限制为50个结果
- CMIS搜索查找所有txt文档，限制为50个结果
更多示例：创建文件夹、浏览文件夹、获取存储库信息
- "在共享文件夹中创建一个名为 '25 07 25 01 18 am' 的文件夹"
- "列出共享文件夹中的文档和文件夹" （将使用 -shared-）
- "你能告诉我我的Alfresco主目录中有什么吗？" （将使用browse_repository -my-）
- "获取Alfresco的信息" （将使用repository_info工具）
聊天框按钮：
- 使用聊天框中的 搜索和工具按钮（两条水平线和圆形图标），选择 "python-alfresco-mcp-server" - 这允许你启用/禁用所有工具或单个工具
- 点击 + 按钮 → "从Alfresco添加" 以快速访问资源和提示
搜索和分析提示：
- 提供一个带有查询字段的表单，用于全文搜索
- 分析类型：摘要、详细、趋势 或 合规性
- 生成可复制的模板文本，以便复制到聊天中进行编辑
存储库信息资源（和工具）：
示例：
🔍 MCP Inspector（开发/测试）
📖 设置指南：完整的MCP Inspector设置和连接说明请参阅 MCP Inspector设置指南
📥 安装MCP Inspector：
- 先决条件：需要 Node.js 18+ - 从 nodejs.org 下载
- 安装命令：
npm install -g @modelcontextprotocol/inspector
- 或者直接运行：
npx @modelcontextprotocol/inspector（无需全局安装）
- 用途：基于Web的工具，用于使用自定义参数测试MCP服务器和单个工具
推荐的工作方法：
1. 使用HTTP传输启动MCP服务器
uvx python-alfresco-mcp-server --transport http --port 8003
uv run python-alfresco-mcp-server --transport http --port 8003
2. 使用配置启动MCP Inspector
UVX安装（推荐）
npx @modelcontextprotocol/inspector --config mcp-inspector-stdio-uvx-config.json --server python-alfresco-mcp-server
npx @modelcontextprotocol/inspector --config mcp-inspector-http-uvx-config.json --server python-alfresco-mcp-server
UV安装（开发）
npx @modelcontextprotocol/inspector --config mcp-inspector-stdio-uv-config.json --server python-alfresco-mcp-server
npx @modelcontextprotocol/inspector --config mcp-inspector-http-uv-config.json --server python-alfresco-mcp-server
传统方法（pipx/pip）
有关pipx和pip的配置选项，请参阅 使用pip和pipx安装。
3. 使用预填充的令牌打开浏览器
- 使用输出中提供的URL（包含身份验证令牌）
- 示例：
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>
- 此步骤适用于 所有安装方法（uv、uvx、pip、pipx）
这种方法可以避免代理连接错误，并提供直接身份验证。
🔧 其他MCP客户端
对于Cursor、Claude Code和其他MCP客户端：
📖 完整设置指南：客户端配置指南
✨ 主要特性
内容管理和搜索工具
- 搜索工具：
- 全文搜索：支持通配符的基本内容搜索 (
search_content)
- 高级搜索：使用AFTS查询语言，支持日期过滤、排序和字段定位
- 元数据搜索：基于属性的查询，支持多种比较运算符
- CMIS搜索：类似SQL的查询，用于复杂的内容发现
- 文档生命周期管理：上传、下载、签入、签出、取消签出
- 版本管理：创建主要/次要版本并添加注释
- 文件夹操作：创建文件夹、删除文件夹节点
- 属性管理：获取和设置文档/文件夹的属性和名称
- 节点操作：删除节点（文档和文件夹）（放入回收站或永久删除）
- 存储库信息：（工具和资源）返回存储库状态、版本、是否为社区版或企业版以及模块配置
MCP架构
- FastMCP 2.0框架：现代、高性能的MCP服务器实现
- 多种传输方式：
- STDIO（直接MCP协议） - 默认且最快
- HTTP（RESTful API） - 用于Web服务和测试
- SSE（服务器发送事件） - 实时流更新
- 企业级安全：OAuth 2.1（可选）
- 类型安全：完整的Pydantic v2模型
- 内存内测试：更快的客户端测试执行
- 配置：支持环境变量、.env文件
Alfresco集成
可与Alfresco社区版（已测试）和企业版配合使用
📦 安装指南
请参考上述快速开始部分的安装步骤，包括Python安装、UV/UVX设置、不同安装方式的选择以及Alfresco连接配置等内容。
💻 使用示例
基础用法
以下是使用UVX启动MCP服务器的基本示例：
uvx python-alfresco-mcp-server
高级用法
以下是使用HTTP传输启动MCP服务器的示例，适用于Web服务和测试：
uvx python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003
📚 详细文档
文档与示例
- 📚 完整文档：包含10篇指南，涵盖从设置到部署的各个方面
- 💡 示例：提供6个实际示例，从快速入门到实现模式
- 🔧 配置管理：支持环境变量、.env文件和命令行配置
- 🏗️ 与MCP客户端配合使用的设置说明
学习资源
- 🚀 快速入门指南：5分钟完成设置并进行首次操作
- 🤖 Claude Desktop设置：为用户和开发人员提供完整的Claude Desktop配置说明
- 🔧 客户端配置：为Cursor、Claude Code和其他MCP客户端提供设置指南
- 📖 示例库：包含实现模式和示例
涵盖设置、部署和使用的指南
- 📚 文档中心 - 完整的导航和概述
- 🚀 快速入门指南 - 5分钟完成设置并进行首次操作
- 📦 使用pip和pipx安装 - 传统的Python包安装方法
- 🤖 Claude Desktop设置 - 为用户和开发人员提供完整的Claude Desktop配置说明
- 🔧 客户端配置 - 为Cursor、Claude Code和其他MCP客户端提供设置指南
- 🔍 MCP Inspector设置 - 使用MCP Inspector进行开发和测试
- 🔍 API参考 - 完整的工具和资源文档
- ⚙️ 配置指南 - 从开发到部署的配置说明
- 🧪 测试指南 - 质量保证和测试开发
- 🛠️ 故障排除指南 - 问题诊断和解决
🔧 技术细节
v1.1版本的新特性
模块化架构与增强测试
- FastMCP：v1.0版本的FastMCP 2.0实现将所有工具的实现都放在
fastmcp_server.py 文件中
- v1.1版本的代码模块化：将单文件的整体结构拆分为有组织的模块化结构，使用单独的文件
- 目录组织：分为
tools/search/、tools/core/、resources/、prompts/、utils/ 目录
- 增强测试：完整的测试套件转换 - 143个测试，通过率100%
- 客户端配置文件：添加了专门的Claude Desktop和MCP Inspector配置文件
- 实时集成测试：21个Alfresco服务器验证测试，确保真实世界的功能正常
- Python-Alfresco-API：python-alfresco-mcp-server v1.1 需要v1.1.1版本的python-alfresco-api包
测试套件概述
- 共143个测试：100%通过 - 覆盖所有功能
- 122个单元测试：100%通过 - 使用模拟验证核心功能（FastMCP 2.0、工具、覆盖率）
- 21个集成测试：100%通过 - 实时服务器测试（搜索、上传、下载、文档生命周期）
- 集成测试：自动化的端到端测试，覆盖所有核心文档生命周期场景
- 性能验证：搜索时间 <1秒，支持并发操作和资源访问
覆盖率报告（清理后）
- 总体覆盖率：51%（测试了1,829条语句）
- FastMCP 2.0核心：经过充分测试，具有全面的单元覆盖率
- 配置模块：93%覆盖率 - 完全测试
- 包初始化：100%覆盖率（5/5行） - 完整
- 整个项目：对全面的代码库实现了51%的覆盖率
运行测试
pytest
pytest --cov=alfresco_mcp_server --cov-report=term-missing
pytest -m "unit"
pytest -m "fastmcp"
pytest -m "integration"
🧪 有关详细的测试策略，请参阅 测试指南
测试类别和执行
项目包括 4个级别的测试：
- 📋 单元测试（122个测试） - 快速、模拟、隔离的组件测试
- 🔗 集成测试（21个测试） - 实时Alfresco服务器测试
- 📝 综合测试 - 自动化的核心文档生命周期场景测试
- 📊 覆盖率测试 - 覆盖边缘情况和错误路径
🛠️ 可用工具（共15个）
🔍 搜索工具（4个）
| 工具 |
描述 |
参数 |
search_content |
搜索文档和文件夹 |
query (str), max_results (int), node_type (str) |
advanced_search |
带过滤器的高级搜索 |
query (str), content_type (str), created_after (str) 等 |
search_by_metadata |
按元数据属性搜索 |
property_name (str), property_value (str), comparison (str) |
cmis_search |
CMIS SQL查询 |
cmis_query (str), preset (str), max_results (int) |
🛠️ 核心工具（11个）
| 工具 |
描述 |
参数 |
browse_repository |
浏览存储库文件夹 |
node_id (str) |
repository_info |
获取存储库信息 |
无 |
upload_document |
上传新文档 |
filename (str), content_base64 (str), parent_id (str), description (str) |
download_document |
下载文档内容 |
node_id (str), save_to_disk (bool) |
create_folder |
创建新文件夹 |
folder_name (str), parent_id (str), description (str) |
get_node_properties |
获取节点元数据 |
node_id (str) |
update_node_properties |
更新节点元数据 |
node_id (str), name (str), title (str), description (str), author (str) |
delete_node |
删除文档/文件夹 |
node_id (str), permanent (bool) |
checkout_document |
签出文档进行编辑 |
node_id (str), download_for_editing (bool) |
checkin_document |
编辑后签入文档 |
node_id (str), comment (str), major_version (bool), file_path (str) |
cancel_checkout |
取消签出/解锁 |
node_id (str) |
📖 有关详细的工具文档，请参阅 API参考
📊 可用资源
存储库信息
| 资源 |
描述 |
访问方法 |
repository_info |
获取全面的存储库信息，包括版本、版本类型、许可证详细信息、安装的模块和系统状态 |
既可用作MCP资源，也可用作工具 |
repository_info 资源提供：
- 存储库详细信息：ID、版本类型（社区版/企业版）、版本信息
- 许可证信息：颁发/过期日期、剩余天数、许可证持有者、权限
- 系统状态：只读模式、审计启用、快速共享、缩略图生成
- 安装的模块：最多10个模块的ID、标题、版本和安装状态
📖 有关详细的资源文档，请参阅 API参考
🎯 可用提示
搜索和分析提示
| 提示 |
描述 |
参数 |
search_and_analyze |
交互式表单，用于引导式内容搜索和分析 |
query (搜索词), analysis_type (摘要/详细/趋势/合规性) |
搜索和分析提示提供：
- 交互式表单：用户友好的界面，带有查询输入字段
- 分析选项：可选择摘要、详细分析、趋势或合规性报告
- 模板生成：创建可复制的模板文本，用于聊天对话
- 查询辅助：帮助用户构建有效的搜索查询
- 多种搜索类型：集成了所有4种搜索工具（内容、高级、元数据、CMIS）
📖 有关详细的提示文档，请参阅 API参考
🔧 配置选项
| 环境变量 |
默认值 |
描述 |
ALFRESCO_URL |
http://localhost:8080 |
Alfresco服务器URL |
ALFRESCO_USERNAME |
admin |
用于身份验证的用户名 |
ALFRESCO_PASSWORD |
admin |
用于身份验证的密码 |
ALFRESCO_VERIFY_SSL |
false |
验证SSL证书 |
ALFRESCO_TIMEOUT |
30 |
请求超时时间（秒） |
FASTAPI_HOST |
localhost |
FastAPI主机 |
FASTAPI_PORT |
8000 |
FastAPI端口 |
LOG_LEVEL |
INFO |
日志级别 |
MAX_FILE_SIZE |
100000000 |
最大上传大小（字节） |
⚙️ 有关部署选项，请参阅 配置指南
🏗️ 架构
┌─────────────────────────────────────────────────────┐
│ MCP Clients │
│ Claude Desktop │ MCP Inspector │ Cursor │ Claude │
│ Code │ n8n │ LangFlow │ Custom MCP Client App │
└─────────────────┬───────────────────────────────────┘
│ stdio/HTTP/SSE
┌─────────────────▼───────────────────────────────────┐
│ FastMCP 2.0 MCP Server │
│ ┌─────────────┬─────────────┬─────────────────┐ │
│ │ MCP Tools │ MCP │ HTTP/SSE API │ │
│ │ (15 total) │ Resources │ │ │
│ │ │ MCP Prompts │ │ │
│ └─────────────┴─────────────┴─────────────────┘ │
└─────────────────┬───────────────────────────────────┘
│ python-alfresco-api
┌─────────────────▼───────────────────────────────────┐
│ Alfresco Content Services │
│ (Community/Enterprise Edition) │
└─────────────────────────────────────────────────────┘
📄 许可证
本项目采用Apache 2.0许可证 - 详情请参阅 LICENSE 文件。
🔗 相关项目和参考
🙋♂️ 支持
- 📚 文档： 中的完整指南
- 💡 示例： 中的实现模式
- 🧪 测试： 中的质量保证
- 🔍 MCP Inspector： 中的开发测试
- 🛠️ 故障排除： 中的问题解决
- 🐛 问题反馈：GitHub问题
🚀 本MCP服务器使用 python-alfresco-api 和 FastMCP 2.0 构建
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
