Python Alfresco MCP Server

🚀 Python Alfresco MCP Server v1.1 🚀

Alfresco Content Services向けのModel Context Protocolサーバーで、コンテンツ管理と検索機能を提供します。

🚀 クイックスタート

このPython Alfresco MCP Serverは、Alfresco Content Servicesにおける検索とコンテンツ管理の分野で、機能豊富なMCPサーバーを提供します。以下のツールを備えています：全文検索（コンテンツとプロパティ）、高度な検索、メタデータ検索、CMIS SQLのような検索、アップロード、ダウンロード、チェックイン、チェックアウト、チェックアウトのキャンセル、フォルダの作成、フォルダの閲覧、ノードの削除、およびプロパティの取得/設定。また、リポジトリのステータス/設定を取得するツールもあります。

✨ 主な機能

コンテンツ管理と検索ツール

• 検索ツール：
  • 全文検索：ワイルドカードをサポートする基本的なコンテンツ検索 (search_content)
  • 高度な検索：日付フィルター、ソート、フィールドターゲティングを備えたAFTSクエリ言語
  • メタデータ検索：演算子（等しい、含む、日付範囲）を使用したプロパティベースのクエリ
  • CMIS検索：複雑なコンテンツの発見のためのSQLのようなクエリ
• ドキュメントのライフサイクル：アップロード、ダウンロード、チェックイン、チェックアウト、チェックアウトのキャンセル
• バージョン管理：コメント付きでメジャー/マイナーバージョンを作成
• フォルダ操作：フォルダの作成、フォルダノードの削除
• プロパティ管理：ドキュメント/フォルダのプロパティと名前の取得と設定
• ノード操作：ノード（ドキュメントとフォルダ）の削除（ゴミ箱または永久削除）
• リポジトリ情報：（ツールとリソース）リポジトリのステータス、バージョン、コミュニティ版またはエンタープライズ版かどうか、およびモジュール構成を返す

MCPアーキテクチャ

• FastMCP 2.0フレームワーク：最新の高性能MCPサーバー実装
• 複数のトランスポート：
  • STDIO（直接MCPプロトコル） - デフォルトで最速
  • HTTP（RESTful API） - Webサービスとテスト
  • SSE（Server-Sent Events） - リアルタイムストリーミング更新
• エンタープライズセキュリティ：OAuth 2.1（オプション）
• 型安全性：完全なPydantic v2モデル
• メモリ内テスト：高速実行でのクライアントテスト
• 構成：環境変数、.envファイル

Alfresco統合

Alfresco Community版（テスト済み）およびエンタープライズ版と互換性があります。

📦 インストール

Pythonのインストール

以下のセクションでは、Python 3.10以上がインストールされている必要があります。インストールされていない場合は、以下のリンクから最新の3.13.xバージョンをダウンロードしてください： Python.org Downloads

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に似ていますが、より高速で最新の機能を備えています。自動的に分離とグローバルな可用性を処理します：

# UV/UVXのセットアップ後、uvxを使用してpython-alfresco-mcp-serverをインストール
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 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 Console
   #- "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

# Webサービス用のHTTPトランスポート（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

# Webサービス用のHTTPトランスポート（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 for Windows（テスト済み）とMacOS（未テスト）

📖 完全なセットアップガイド：Claude Desktopセットアップガイド

📥 Claude Desktopのダウンロード（無料版とPro版）：

• Claude Desktopをダウンロード - 公式のAnthropicダウンロードページ
• WindowsとmacOSのみで利用可能（Linux版はありません）
• 無料版には、完全なMCPサポートと制限付きのClaude Sonnet 4アクセス、古いClaudeモデルが含まれています（Pro版でのみ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：手動でのvenvパス構成

🔐 ツールごとの権限システム： Claude Desktopは、初回使用時に各ツールについて個別にポップアップで確認します。このMCPサーバーには15のツールがあるため、すべての機能を使用する場合、最大15の権限ポップアップが表示されることがあります。各ツールについて、以下のオプションを選択できます：

• "一度だけ許可" - この単一のツールの使用のみを承認
• "常に許可" - この特定のツールの将来のすべての使用を自動的に承認（定期的に使用する場合は推奨）

このツールごとのセキュリティ機能により、外部ツールの実行に対して細かいコントロールを維持できます。

🛡️ ウイルススキャナの注意：Norton 360のようなウイルスチェッカーを使用している場合、pip、pipx、uv、uvx、またはpython-alfresco-mcp-server.exeについて一度だけ「チェック中」のメッセージが表示された場合は心配しないでください。これは通常のセキュリティスキャン動作です。

ツールの使用方法：

• 自然にチャットして、ドキュメントと検索についてやりたいことを話します
• "Alfresco"を言及して、MCPサーバーが使用されることを確認します（例："In Alfresco..."）
• ツール関連のキーワードを使用します - ツール名に近いものを言及します
• フォローアップのプロンプトは、前のコンテキストからドキュメントを認識します

例1：ドキュメント管理

1. 単純なテキストドキュメントをアップロードします："Please create a file called 'claude_test_doc-25 07 25 101 0 AM.txt' in the repository shared folder with this content: 'This is a test document created by Claude via MCP.' description 'Test document uploaded via Claude MCP'"
2. プロパティを更新します："Set the description property of this document to 'my desc'"
3. ドキュメントをチェックアウトします
4. チェックアウトをキャンセルします
5. 再度チェックアウトします
6. メジャーバージョンとしてチェックインします
7. ドキュメントをダウンロードします
8. "C:\1 sample files\cmispress.pdf"から2番目のドキュメントをアップロードします

注意：Claudeは、最初のアップロードについて、2回目の試行でbase64エンコーディングを使用することを判断します。

例2：検索操作 "With Alfresco please test all 3 search methods and CMIS query:"

• 基本的な検索で、"txt"ドキュメントを検索し、最大10件を返します
• 高度な検索で、2024-01-01以降に作成されたドキュメントを検索し、最大25件を返します
• メタデータ検索で、cm:titleに"test"が含まれるドキュメントを検索し、50件まで制限します
• CMIS検索で、すべてのtxtドキュメントを検索し、50件まで制限します

その他の例：フォルダの作成、フォルダの閲覧、リポジトリ情報の取得

• "Create a folder called '25 07 25 01 18 am' in shared folder"
• "List docs and folders in shared folder" (will use -shared-)
• "Can you show me what's in my Alfresco home directory?" (will use browse_repository -my-)
• "Get info on Alfresco" (will use repository_info tool)

チャットボックスのボタン

• チャットボックスの検索とツールボタン（円が付いた2本の水平線のアイコン）を使用して、"python-alfresco-mcp-server"を選択します。これにより、すべてのツールまたは個々のツールを有効/無効にすることができます。
• +ボタンをクリックして、"Add from alfresco"を選択すると、リソースとプロンプトにすばやくアクセスできます。

検索と分析プロンプト：

• 全文検索用のクエリフィールドを備えたインタラクティブなフォームを提供します
• 分析タイプ：要約、詳細、トレンド、またはコンプライアンス
• テンプレートテキストを生成して、チャットにコピーして編集できます

リポジトリ情報リソース（およびツール）：

• テキスト形式でステータス情報を提供し、表示またはコピーできます。

例：

• ツールのテスト例については、を参照してください。

🔍 MCP Inspector（開発/テスト用）

📖 セットアップガイド：MCP Inspectorセットアップガイドに完全なMCP Inspectorのセットアップと接続手順が記載されています。

📥 MCP Inspectorのインストール：

• 前提条件：Node.js 18以上が必要です - nodejs.org からダウンロードしてください。
• インストールコマンド：npm install -g @modelcontextprotocol/inspector
• または直接実行：npx @modelcontextprotocol/inspector（グローバルインストール不要）
• 目的：カスタムパラメータでMCPサーバーと個々のツールをテストするためのWebベースのツール

推奨される作業方法：

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=<token>
• この手順は、すべてのインストール方法（uv、uvx、pip、pipx）に適用されます。

このアプローチにより、プロキシ接続エラーを回避し、直接認証を行うことができます。

🔧 その他のMCPクライアント

Cursor、Claude Code、およびその他のMCPクライアントについては： 📖 完全なセットアップガイド：クライアント構成ガイド

🛠️ 利用可能なツール（合計15個）

🔍 検索ツール（4個）

🛠️ コアツール（11個）

📖 詳細なツールドキュメントについては、APIリファレンスを参照してください

📊 利用可能なリソース

リポジトリ情報

repository_infoリソースは以下を提供します：

• リポジトリ詳細：ID、エディション（コミュニティ版/エンタープライズ版）、バージョン情報
• ライセンス情報：発行/有効期限、残り日数、ライセンス保有者、権限
• システムステータス：読み取り専用モード、監査有効化、クイック共有、サムネイル生成
• インストールされたモジュール：ID、タイトル、バージョン、およびインストール状態を含む最大10のモジュール

📖 詳細なリソースドキュメントについては、APIリファレンスを参照してください

🎯 利用可能なプロンプト

検索と分析プロンプト

検索と分析プロンプトは以下を提供します：

• インタラクティブなフォーム：クエリ入力フィールドを備えたユーザーフレンドリーなインターフェイス
• 分析オプション：要約、詳細分析、トレンド、またはコンプライアンスレポートから選択
• テンプレート生成：チャット会話用のコピー可能なテンプレートテキストを作成
• クエリ支援：ユーザーが効果的な検索クエリを構築するのを支援
• 複数の検索タイプ：すべての4つの検索ツール（コンテンツ、高度、メタデータ、CMIS）と統合

📖 詳細なプロンプトドキュメントについては、APIリファレンスを参照してください

🔧 構成オプション

⚙️ デプロイメントオプションについては、構成ガイドを参照してください

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────────┐
│                   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)              │
└─────────────────────────────────────────────────────┘

🧪 テストと品質

テストスイートの概要

• 合計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つのレベルのテストが含まれています：

1. 📋 単体テスト（122のテスト） - 高速でモッキングされた、分離されたコンポーネントのテスト
2. 🔗 統合テスト（21のテスト） - ライブAlfrescoサーバーでのテスト
3. 📝 包括的なテスト - 自動化されたコアドキュメントのライフサイクルシナリオ
4. 📊 カバレッジテスト - エッジケースとエラーパスのカバレッジ

🧪 開発

開発環境のセットアップ

git clone <repository>
cd python-alfresco-mcp-server

# UVはすべてを自動的に処理する - 手動でのvenvセットアップは必要ありません！
uv sync --extra dev        # 開発ツール付きでインストール
uv sync --extra test       # テストツール付き
uv sync --extra all        # すべて

# すぐに実行して、インストールが正常に機能したことをテスト
uv run python-alfresco-mcp-server --help

# 必要に応じて、ローカル開発用にpython-alfresco-apiをインストール
uv add --editable ../python-alfresco-api

従来の開発セットアップ： pipベースの開発セットアップについては、pipとpipxを使用したインストール を参照してください。

💡 例

初心者からエンタープライズまでの実世界の実装パターン：

• 💡 例のライブラリ - 完全なナビゲーションと学習パス
• 🏃 クイックスタート - 5分での導入と基本的な操作
• 📋 ドキュメントのライフサイクル - 完全なプロセスのデモンストレーション
• 🚀 トランスポートの例 - STDIO、HTTP、およびSSEプロトコル
• ⚡ バッチ操作 - 高性能なバルク処理
• 🛡️ エラーハンドリング - 回復力のあるパターン
• 📊 例の概要 - 概要と統計

🤝 コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/new-feature)。
3. 変更をコミットします (git commit -m 'Add new feature')。
4. ブランチにプッシュします (git push origin feature/new-feature)。
5. プルリクエストを開きます。

📄 ライセンス

このプロジェクトは、Apache 2.0ライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

🔗 関連プロジェクトと参照

• Hyland Alfresco - コンテンツ管理プラットフォーム（エンタープライズ版とコミュニティ版）
• python-alfresco-api - 基礎となるAlfresco APIライブラリ
• FastMCP 2.0 - MCPサーバーを構築するための最新のフレームワーク
• FastMCPドキュメント - 完全なFastMCPフレームワークのドキュメントとガイド
• Model Context Protocol - 公式のMCP仕様とドキュメント
• Playbooks.com MCP List - Python Alfresco MCP Serverのリスト
• PulseMCP.com MCP List - Python Alfresco MCP Serverのリスト
• Glama.ai MCP List - Glama Alfrescoのリスト（Python Alfresco MCP Serverのリストを含む）
• MCPMarket.com MCP List - Python Alfresco MCP Serverのリスト

🙋‍♂️ サポート

• 📚 ドキュメント：に完全なガイドがあります。
• 💡 例：に実装パターンがあります。
• 🧪 テスト：に品質保証があります。
• 🔍 MCP Inspector：に開発テストがあります。
• 🛠️ トラブルシューティング：に問題解決があります。
• 🐛 問題報告：GitHub Issues

🚀 python-alfresco-apiとFastMCP 2.0を使用して構築されたMCPサーバー