python阿尔法克索MCP服务器

Name: python阿尔法克索MCP服务器
Author: stevereiner

作者：stevereiner10 星标更新：2025-08-03

安装使用来源：spider==github.com

项目介绍

Python Alfresco MCP Server v1.1 🚀

模型上下文协议服务器用于 Alfresco 内容服务

这是一个针对 Alfresco 的全功能 MCP 服务器，在搜索和内容管理领域提供以下工具：全文搜索（内容和属性）、高级搜索、元数据搜索、类似 CMIS SQL 的搜索、上传、下载、检入、检出、取消检出、创建文件夹、浏览文件夹、删除节点以及获取/设置属性。还提供了一个获取存储库状态/配置的工具（也是一个资源）。包含一个示例提示。使用 FastMCP 2.0 构建。具有完整的文档、示例和各种 MCP 客户端（Claude Desktop、MCP Inspector、配置其他客户端的参考）的配置。

🌟 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 包

📚 完整文档

文档与示例

📚 完整文档: 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 参考 - 工具和资源的完整文档
⚙️ 配置指南 - 从开发到部署
🧪 测试指南 - 质量保证和测试开发
🛠️ 故障排除指南 - 问题诊断和解决

🚀 功能

内容管理和搜索工具

搜索工具：
- 全文搜索: 基础内容搜索，支持通配符（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 3.10+
Alfresco 内容服务（社区版或企业版）

注意: python-alfresco-api >= 1.1.1 依赖项会随着 python-alfresco-mcp-server 自动安装

🛠️ 安装

安装 Python

你需要安装 Python 3.10+ 才能继续下面的部分。如果没有，请从以下链接下载最新版本 3.13.x：

Python.org 下载

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        # 一切

4. 配置 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 命令提示符
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 客户端。Python-Alfresco-MCP-Server 也已经使用 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: claude-desktop-config-uvx-windows.json
- macOS: claude-desktop-config-uvx-macos.json
UVX 自动处理隔离和全局可用性
最快和最现代的方法

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

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

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

3. 传统方法（pipx/pip）:

对于传统安装方法，请参阅 使用 pip 和 pipx 安装，其中涵盖：

pipx: claude-desktop-config-pipx-windows.json / claude-desktop-config-pipx-macos.json
pip: 手动配置 venv 路径

🔐 工具级权限系统: Claude Desktop 会在首次使用时逐个工具地提示你。由于这个 MCP 服务器有 15 个工具，如果你使用所有功能，可能会看到多达 15 个权限提示。对于每个工具，你可以选择：

"允许一次" - 仅批准此单次工具使用
"始终允许" - 自动批准该特定工具的所有未来使用（建议用于常规使用）

这种工具级的安全功能确保你能够