Python Alfresco Mcp Server

笔记 Python

🚀 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 快得多。

# 安装UV（提供uv和uvx命令）
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者通过pip安装
pip install uv

# 验证安装（两个命令都应正常工作）
uv --version
uvx --version

UV参考链接：

UV安装指南 - 官方安装说明和特定平台选项
UV文档 - 完整的UV文档、指南和高级用法

安装方式选择

选项A：UVX - 现代工具运行器（推荐给用户）

UVX 是UV的工具运行器，类似于 pipx，但更快、更现代。它会自动处理隔离和全局可用性：

# 使用uvx安装python-alfresco-mcp-server（在完成上述UV/UVX设置后）
uvx python-alfresco-mcp-server --help

# 这将测试安装是否成功 - UVX会在首次使用时自动安装包！

为什么选择UVX：UVX结合了 pipx（隔离环境 + 全局可用性）的优点，以及UV基于Rust的速度和现代依赖解析能力。它会在首次使用时自动安装包。

选项B：UV - 现代包管理器（推荐用于开发）

UV 是用 Rust 编写的现代Python包管理器，能自动处理一切。由于其编译性质和优化的依赖解析，它比 pip 快得多。

# 从PyPI安装并运行（对用户来说最快）
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客户端设置和使用部分。

源代码安装（用于开发）

若要进行开发或访问最新功能：

# 1. 克隆仓库
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server

# 2. UV会自动处理一切 - 立即运行！
uv run python-alfresco-mcp-server --help  # 测试安装是否成功

# 或者为开发显式安装依赖项
uv sync                    # 基本依赖项
uv sync --extra dev        # 包含开发工具  
uv sync --extra test       # 包含测试工具
uv sync --extra all        # 包含所有内容

配置Alfresco连接

选项1：环境变量

# Linux/Mac
export ALFRESCO_URL="http://localhost:8080"
export ALFRESCO_USERNAME="admin"
export ALFRESCO_PASSWORD="admin"
export ALFRESCO_VERIFY_SSL="false"

# Windows PowerShell
$env:ALFRESCO_URL="http://localhost:8080"
$env:ALFRESCO_USERNAME="admin"
$env:ALFRESCO_PASSWORD="admin"
$env:ALFRESCO_VERIFY_SSL="false"

# Windows Command Prompt
set ALFRESCO_URL=http://localhost:8080
set ALFRESCO_USERNAME=admin
set ALFRESCO_PASSWORD=admin
set ALFRESCO_VERIFY_SSL=false

选项2：.env文件（推荐 - 跨平台）

# 复制sample-dot-env.txt到.env并进行自定义
# Linux/macOS
cp sample-dot-env.txt .env

# Windows
copy sample-dot-env.txt .env

# 编辑.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" # Web控制台
#- "5672:5672" # AMQP
#- "61616:61616" # OpenWire
#- "61613:61613" # STOMP

使用Docker Compose启动Alfresco

docker-compose -f community-compose.yaml up

MCP服务器启动

使用UVX（推荐 - 自动隔离和全局可用）

# 使用STDIO传输运行MCP服务器（默认）
uvx python-alfresco-mcp-server

# 使用HTTP传输进行Web服务（与MCP Inspector匹配）
uvx python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003

# 使用SSE传输进行实时流
uvx python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001

使用UV（用于开发或源代码安装）

# 使用STDIO传输运行MCP服务器（默认）
uv run python-alfresco-mcp-server

# 使用HTTP传输进行Web服务（与MCP Inspector匹配）
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003

# 使用SSE传输进行实时流
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"]
}

示例配置文件：
- Windows:
- macOS:
UVX会自动处理隔离和全局可用性
最快、最现代的方法

2. UV（开发或源代码安装）

{
"command": "uv",
"args": ["run", "python-alfresco-mcp-server", "--transport", "stdio"],
"cwd": "C:\\path\\to\\python-alfresco-mcp-server"
}

示例配置文件：
- Windows:
- macOS:
使用 uv run 并将 cwd 指向你的 项目目录
UV会自动找到并使用项目目录中的 .venv
适用于源代码安装和 uv tool install 之后

3. 传统方法（pipx/pip） 有关传统安装方法，请参阅 使用pip和pipx安装，其中涵盖：

pipx： /
pip：手动配置虚拟环境路径

🔐 逐个工具的权限系统 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（推荐）
uvx python-alfresco-mcp-server --transport http --port 8003

# 使用UV（开发）
uv run python-alfresco-mcp-server --transport http --port 8003

# 传统方法 - 请参阅传统安装指南

2. 使用配置启动MCP Inspector UVX安装（推荐）

# 使用stdio传输启动
npx @modelcontextprotocol/inspector --config mcp-inspector-stdio-uvx-config.json --server python-alfresco-mcp-server

# 使用http传输启动
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  # stdio传输
npx @modelcontextprotocol/inspector --config mcp-inspector-http-uv-config.json --server python-alfresco-mcp-server   # http传输

传统方法（pipx/pip） 有关pipx和pip的配置选项，请参阅 使用pip和pipx安装。

3. 使用预填充的令牌打开浏览器

使用输出中提供的URL（包含身份验证令牌）
示例：http://localhost:6274/?MCP_PROXY_AUTH_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"        # 运行FastMCP 2.0测试
pytest -m "integration"    # 运行集成测试（需要Alfresco）

🧪 有关详细的测试策略，请参阅测试指南

测试类别和执行

项目包括 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 文件。

🔗 相关项目和参考

Hyland Alfresco - 内容管理平台（企业版和社区版）
python-alfresco-api - 底层的Alfresco API库
FastMCP 2.0 - 用于构建MCP服务器的现代框架
FastMCP文档 - 完整的FastMCP框架文档和指南
模型上下文协议 - 官方MCP规范和文档
Playbooks.com MCP列表 - Python Alfresco MCP Server列表
PulseMCP.com MCP列表 - Python Alfresco MCP Server列表
Glama.ai MCP列表 - Glama Alfresco列表，包括Python Alfresco MCP Server列表
MCPMarket.com MCP列表 - Python Alfresco MCP Server列表

🙋‍♂️ 支持

📚 文档：中的完整指南
💡 示例：中的实现模式
🧪 测试：中的质量保证
🔍 MCP Inspector：中的开发测试
🛠️ 故障排除：中的问题解决
🐛 问题反馈：GitHub问题

🚀 本MCP服务器使用 python-alfresco-api 和 FastMCP 2.0 构建

0 条评论
分类：笔记

Python Alfresco Mcp Server