python-alfresco-mcp-server 1.2.0__tar.gz → 1.2.1__tar.gz

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/CHANGELOG.md

@@ -1,162 +1,173 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [1.2.0] - 2026-08-05
-
-### Added
-- **Alfresco auth methods** (`ALFRESCO_AUTH_METHOD` = `basic` | `ticket` | `oauth2`): the server can now authenticate to Alfresco via HTTP Basic, a login ticket, or an OAuth2/OIDC bearer token (Alfresco `identity-service`), via `python-alfresco-api` 1.2.1+ `OAuth2AuthUtil`, configured with `ALFRESCO_OAUTH2_*` env vars. Documents the setup in the README **Authentication** section (addresses #2). Live-tested basic/ticket/oauth2 end-to-end.
-- **Optional MCP transport authentication** (`MCP_TRANSPORT_AUTH=true`): secures the MCP server itself — HTTP/SSE callers must present an OAuth2 bearer token, validated against an OIDC IdP's JWKS (FastMCP JWT verifier). Off by default; stdio unaffected. Env: `MCP_AUTH_JWKS_URI` / `MCP_AUTH_ISSUER` / `MCP_AUTH_AUDIENCE`.
-- **`download_document` `destination_dir`**: optional custom download folder (default `~/Downloads`). Thanks [@jeremie-lesage](https://github.com/jeremie-lesage) ([#1](https://github.com/stevereiner/python-alfresco-mcp-server/pull/1)).
-
-### Changed
-- **Version 1.2.0** of this package; requires **python-alfresco-api >= 1.2.1** (OAuth2/OIDC auth, `VersionsClient` fix, and OAuth2 service-account `displayName` handling — see below).
-- **Config layout**: moved Claude Desktop sample configs into [`claude-desktop-configs/`](./claude-desktop-configs/) and MCP Inspector samples into [`mcp-inspector-configs/`](./mcp-inspector-configs/); docs and README updated accordingly.
-- **FastMCP 3 upgrade**: bumped dependency from FastMCP 2.x to `fastmcp>=3.4.5,<4`. Server code is compatible with FastMCP 3's API (`list_tools()` / `list_resources()` / `list_prompts()`); JWT transport auth now uses `JWTVerifier` directly. See [FastMCP 2 → 3 upgrade guide](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2).
-- **Packaging**: switched build backend from setuptools to hatchling (same as python-alfresco-api) for quieter `uv build` output.
-
-### Fixed
-- **checkout_document**: local download filename puts the node ID before the extension (`name_<nodeId>.txt`) instead of after it (`name.txt_<nodeId>`), so editors keep the correct file type.
-- **OAuth2 service-account nodes** (via **python-alfresco-api 1.2.1**): Keycloak client-credentials authenticates as a JIT Alfresco user with no display name, so Alfresco returns `createdByUser` / `modifiedByUser` / `owner` without `displayName` and the generated `UserInfo.from_dict` raised `KeyError('displayName')` (breaking `download_document` and other `nodes.get` tools). Fixed upstream with a runtime shim (`python_alfresco_api/_compat.py`, applied at package import) that defaults missing `displayName` to `id` for core and search `UserInfo` — outside `raw_clients/` so it survives client re-generation. Basic/ticket and user-based OAuth2 tokens were unaffected.
-
-## [1.1.0] - 2025-01-25
-
-### Alfresco_MCP_Server dir code changes for v1.1
-- **Code Split**: Refactored from monolithic single file to modular structure with separate files
-- **Directory Structure**: Reorganized from flat to hierarchical structure
-  - `tools/search/` - 4 search-related tools
-  - `tools/core/` - 11 core management tools
-  - `resources/` - Repository information
-  - `prompts/` - AI templates
-  - `utils/` - Shared utilities  
-- fix: implement Windows UTF-8 encoding support (emoji character encoding)
-- get to work with python-alfresco-api 1.1.x
-- add imports and __all__ to get files included in packaging
-
-### UV Package Management Support
-- **Rust-based Performance**: UV provides faster dependency resolution and package management
-- **Automatic Environment Management**: UV handles virtual environment creation and activation
-- **Simplified Installation**: One-command setup replaces multi-step manual process
-- **Cross-platform Compatibility**: Consistent behavior across Windows, macOS, and Linux
-
-### PyPI Distribution
-- **Direct Installation**: Available via `pip install python-alfresco-mcp-server`
-- **UV Integration**: Compatible with `uv pip install python-alfresco-mcp-server`
-- **Immediate Usage**: Run server directly after installation without source code
-
-### Update Tests for v1.1
-- `test: transform test suite from 76+ failures to 143/143 passing`
-- `test: add comprehensive live integration testing with 21 Alfresco tests`
-- `test: implement cross-platform emoji handling for Windows compatibility`
-- `test: enhance coverage reporting with HTML output`
-- `test: add automated testing for all manual scenarios`
-- `test: implement strip_emojis() function for Windows compatibility`
-- `test: add comprehensive unit test coverage (122 tests)`
-- `test: fix test import paths for modular architecture`
-
-### MCP Clients: config files added for v1.1
--  Added Claude Desktop and MCP Inspector config files
-- `config: added claude-desktop-config-developer-windows.json with UV support`
-- `config: added claude-desktop-config-developer-macos.json with UV support`
-- `config: added claude-desktop-config-user-windows.json`
-- `config: added claude-desktop-config-user-macos.json`
-- `config: added Windows UTF-8 encoding variables to windows configs`
-- `config: added mcp-inspector-http-config.json for HTTP transport using uv`
-- `config: added mcp-inspector-stdio-config.json for STDIO transport using uv`
-- 'examples: prompts-for-claude.md has example prompt text to test tools
-
-### Update docs for v1.1
-- `docs: create comprehensive CHANGELOG.md for v1.0.0 and v1.1.0`
-- `docs: update quick start guide for UV approach`
-- 'docs: api_reference.md added details for all tools, etc
-- `docs: added claude_desktop_setup.md, mcp_inspector_setup.md, and client_configurations.md
-
-### Documentation Updates for v1.1
-- **Installation Instructions**: Added PyPI installation methods
-- **Configuration Examples**: Updated for UV approach
-- **Testing Procedures**: Comprehensive test execution guidance
-- **Troubleshooting**: Enhanced problem resolution guidance
-
-### Update Readme for v1.1
-- added install from PyPI 
-- added how to install UV package manager
-- added claude desktop and mcp inspector setup sections
-- reword technical sections for accuracy
-- add v1.1 list of changes, depend on python-alfresco 1.1.1, python 3.10+
-- added how to install Alfresco Community from github
-
-### Update project files and misc root dir files for v1.1
-- gitignore now ignores cursor memory and memory-bank dir, keep .vscode/mcp.json
-- config.yaml has changed alfresco_url to have base_url, added timeout, added
-  mcp server name and version confg
-- MANIFEST.in added for proper package distrubution config
-- pyproject.toml change to have v1.1.0 release, pypi distrib settings, remove
-  fastMCP version restriction, update to require python 3.10 or greater, add
-  pypi keyword and topic, settings, project urls for pypi, configure setuptools
-  for includes, excludes
-- run_server.py script added
-- .vscode/mcp.json  uses run_server.py for debugging mcp server
--  uv.lock add now that use uv, and uv lock --upgrade updated v0.12.5 from v0.12.4 of ruff
-
-### Fixes for pyproject.toml  for v1.1
- - require python-alfresco-api >= 1.1.1 not 1.0.0 in dependencies
- - have python 3.10 instead of 3.8 for tool.mypy, and py310 not py38 for tool.ruff and tool.black
- 
-### Example Code Updates for v1.1
-- `examples: update transport examples for UV approach`
-- `examples: enhance document lifecycle example`
-- `examples: add UV-specific installation examples`
-- `examples: update batch operations for improved performance`
-- `examples: refactor error handling patterns` 
-
-### Requirements
-- **Python Versions**: 3.10+ (unchanged)
-- **python-alfresco-api**: >= 1.1.1 (updated requirement)
-- **FastMCP**: Tested with v2.10.6
-
-### Tested
-- **Alfresco Versions**: Community 25.1 (tested), Enterprise (not tested in v1.1)
-- **Operating Systems**: 
-  - Windows (tested)
-  - macOS (needs testing)
-  - Linux (needs testing, note: no Claude Desktop support on Linux)
-- **MCP Clients**: 
-  - Claude Desktop (tested and validated)
-  - MCP Inspector (tested and validated)
-  - Cursor (configuration provided, not tested in v1.1)
-  - Claude Code (configuration provided, not tested in v1.1) 
-
-## [1.0.0] - 2024-06-24
-
-### Added
-- Initial FastMCP 2.0 server implementation
-- 15 content management tools across search and core operations
-- Full text search with wildcard support
-- Advanced search using AFTS query language
-- Metadata search with property-based queries
-- CMIS SQL search capabilities
-- Complete document lifecycle management (upload, download, checkout, checkin)
-- Version management with major/minor version support
-- Folder operations and repository browsing
-- Property management for documents and folders
-- Multiple transport protocols (STDIO, HTTP, SSE)
-- Configuration via environment variables and .env files
-- Claude Desktop integration with Windows and macOS configs
-- MCP Inspector support for development testing
-- Comprehensive documentation and examples
-- Testing framework with unit and integration tests
-- Error handling and recovery patterns
-- Repository discovery and status reporting
-
-### Technical Implementation
-- python-alfresco-api integration for content services access
-- Pydantic v2 models for type safety
-- Async support for concurrent operations
-- Connection pooling and authentication management
-- Progress reporting and context logging
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.1] - 2026-09-29
+
+### Added
+- **`ALFRESCO_TICKET`**: with `ALFRESCO_AUTH_METHOD=ticket`, a login ticket you already hold is used as-is instead of being fetched from a username and password — so the server can run with no Alfresco password configured at all. Leave it unset and ticket auth behaves as before (acquired from `ALFRESCO_USERNAME` / `ALFRESCO_PASSWORD`). A supplied ticket is never renewed, so it stops working when it expires.
+
+### Changed
+- Requires **python-alfresco-api >= 1.2.2** for the ticket pass-through above.
+
+### Fixed
+- **Integration test `test_search_shared_folder`**: now passes `node_type="cm:folder"`. `search_content` searches documents (`cm:content`) by default, so the search never matched the Shared folder and the test failed.
+
+## [1.2.0] - 2026-08-05
+
+### Added
+- **Alfresco auth methods** (`ALFRESCO_AUTH_METHOD` = `basic` | `ticket` | `oauth2`): the server can now authenticate to Alfresco via HTTP Basic, a login ticket, or an OAuth2/OIDC bearer token (Alfresco `identity-service`), via `python-alfresco-api` 1.2.1+ `OAuth2AuthUtil`, configured with `ALFRESCO_OAUTH2_*` env vars. Documents the setup in the README **Authentication** section (addresses #2). Live-tested basic/ticket/oauth2 end-to-end.
+- **Optional MCP transport authentication** (`MCP_TRANSPORT_AUTH=true`): secures the MCP server itself — HTTP/SSE callers must present an OAuth2 bearer token, validated against an OIDC IdP's JWKS (FastMCP JWT verifier). Off by default; stdio unaffected. Env: `MCP_AUTH_JWKS_URI` / `MCP_AUTH_ISSUER` / `MCP_AUTH_AUDIENCE`.
+- **`download_document` `destination_dir`**: optional custom download folder (default `~/Downloads`). Thanks [@jeremie-lesage](https://github.com/jeremie-lesage) ([#1](https://github.com/stevereiner/python-alfresco-mcp-server/pull/1)).
+
+### Changed
+- **Version 1.2.0** of this package; requires **python-alfresco-api >= 1.2.1** (OAuth2/OIDC auth, `VersionsClient` fix, and OAuth2 service-account `displayName` handling — see below).
+- **Config layout**: moved Claude Desktop sample configs into [`claude-desktop-configs/`](./claude-desktop-configs/) and MCP Inspector samples into [`mcp-inspector-configs/`](./mcp-inspector-configs/); docs and README updated accordingly.
+- **FastMCP 3 upgrade**: bumped dependency from FastMCP 2.x to `fastmcp>=3.4.5,<4`. Server code is compatible with FastMCP 3's API (`list_tools()` / `list_resources()` / `list_prompts()`); JWT transport auth now uses `JWTVerifier` directly. See [FastMCP 2 → 3 upgrade guide](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2).
+- **Packaging**: switched build backend from setuptools to hatchling (same as python-alfresco-api) for quieter `uv build` output.
+
+### Fixed
+- **checkout_document**: local download filename puts the node ID before the extension (`name_<nodeId>.txt`) instead of after it (`name.txt_<nodeId>`), so editors keep the correct file type.
+- **OAuth2 service-account nodes** (via **python-alfresco-api 1.2.1**): Keycloak client-credentials authenticates as a JIT Alfresco user with no display name, so Alfresco returns `createdByUser` / `modifiedByUser` / `owner` without `displayName` and the generated `UserInfo.from_dict` raised `KeyError('displayName')` (breaking `download_document` and other `nodes.get` tools). Fixed upstream with a runtime shim (`python_alfresco_api/_compat.py`, applied at package import) that defaults missing `displayName` to `id` for core and search `UserInfo` — outside `raw_clients/` so it survives client re-generation. Basic/ticket and user-based OAuth2 tokens were unaffected.
+
+## [1.1.0] - 2025-01-25
+
+### Alfresco_MCP_Server dir code changes for v1.1
+- **Code Split**: Refactored from monolithic single file to modular structure with separate files
+- **Directory Structure**: Reorganized from flat to hierarchical structure
+  - `tools/search/` - 4 search-related tools
+  - `tools/core/` - 11 core management tools
+  - `resources/` - Repository information
+  - `prompts/` - AI templates
+  - `utils/` - Shared utilities  
+- fix: implement Windows UTF-8 encoding support (emoji character encoding)
+- get to work with python-alfresco-api 1.1.x
+- add imports and __all__ to get files included in packaging
+
+### UV Package Management Support
+- **Rust-based Performance**: UV provides faster dependency resolution and package management
+- **Automatic Environment Management**: UV handles virtual environment creation and activation
+- **Simplified Installation**: One-command setup replaces multi-step manual process
+- **Cross-platform Compatibility**: Consistent behavior across Windows, macOS, and Linux
+
+### PyPI Distribution
+- **Direct Installation**: Available via `pip install python-alfresco-mcp-server`
+- **UV Integration**: Compatible with `uv pip install python-alfresco-mcp-server`
+- **Immediate Usage**: Run server directly after installation without source code
+
+### Update Tests for v1.1
+- `test: transform test suite from 76+ failures to 143/143 passing`
+- `test: add comprehensive live integration testing with 21 Alfresco tests`
+- `test: implement cross-platform emoji handling for Windows compatibility`
+- `test: enhance coverage reporting with HTML output`
+- `test: add automated testing for all manual scenarios`
+- `test: implement strip_emojis() function for Windows compatibility`
+- `test: add comprehensive unit test coverage (122 tests)`
+- `test: fix test import paths for modular architecture`
+
+### MCP Clients: config files added for v1.1
+-  Added Claude Desktop and MCP Inspector config files
+- `config: added claude-desktop-config-developer-windows.json with UV support`
+- `config: added claude-desktop-config-developer-macos.json with UV support`
+- `config: added claude-desktop-config-user-windows.json`
+- `config: added claude-desktop-config-user-macos.json`
+- `config: added Windows UTF-8 encoding variables to windows configs`
+- `config: added mcp-inspector-http-config.json for HTTP transport using uv`
+- `config: added mcp-inspector-stdio-config.json for STDIO transport using uv`
+- 'examples: prompts-for-claude.md has example prompt text to test tools
+
+### Update docs for v1.1
+- `docs: create comprehensive CHANGELOG.md for v1.0.0 and v1.1.0`
+- `docs: update quick start guide for UV approach`
+- 'docs: api_reference.md added details for all tools, etc
+- `docs: added claude_desktop_setup.md, mcp_inspector_setup.md, and client_configurations.md
+
+### Documentation Updates for v1.1
+- **Installation Instructions**: Added PyPI installation methods
+- **Configuration Examples**: Updated for UV approach
+- **Testing Procedures**: Comprehensive test execution guidance
+- **Troubleshooting**: Enhanced problem resolution guidance
+
+### Update Readme for v1.1
+- added install from PyPI 
+- added how to install UV package manager
+- added claude desktop and mcp inspector setup sections
+- reword technical sections for accuracy
+- add v1.1 list of changes, depend on python-alfresco 1.1.1, python 3.10+
+- added how to install Alfresco Community from github
+
+### Update project files and misc root dir files for v1.1
+- gitignore now ignores cursor memory and memory-bank dir, keep .vscode/mcp.json
+- config.yaml has changed alfresco_url to have base_url, added timeout, added
+  mcp server name and version confg
+- MANIFEST.in added for proper package distrubution config
+- pyproject.toml change to have v1.1.0 release, pypi distrib settings, remove
+  fastMCP version restriction, update to require python 3.10 or greater, add
+  pypi keyword and topic, settings, project urls for pypi, configure setuptools
+  for includes, excludes
+- run_server.py script added
+- .vscode/mcp.json  uses run_server.py for debugging mcp server
+-  uv.lock add now that use uv, and uv lock --upgrade updated v0.12.5 from v0.12.4 of ruff
+
+### Fixes for pyproject.toml  for v1.1
+ - require python-alfresco-api >= 1.1.1 not 1.0.0 in dependencies
+ - have python 3.10 instead of 3.8 for tool.mypy, and py310 not py38 for tool.ruff and tool.black
+ 
+### Example Code Updates for v1.1
+- `examples: update transport examples for UV approach`
+- `examples: enhance document lifecycle example`
+- `examples: add UV-specific installation examples`
+- `examples: update batch operations for improved performance`
+- `examples: refactor error handling patterns` 
+
+### Requirements
+- **Python Versions**: 3.10+ (unchanged)
+- **python-alfresco-api**: >= 1.1.1 (updated requirement)
+- **FastMCP**: Tested with v2.10.6
+
+### Tested
+- **Alfresco Versions**: Community 25.1 (tested), Enterprise (not tested in v1.1)
+- **Operating Systems**: 
+  - Windows (tested)
+  - macOS (needs testing)
+  - Linux (needs testing, note: no Claude Desktop support on Linux)
+- **MCP Clients**: 
+  - Claude Desktop (tested and validated)
+  - MCP Inspector (tested and validated)
+  - Cursor (configuration provided, not tested in v1.1)
+  - Claude Code (configuration provided, not tested in v1.1) 
+
+## [1.0.0] - 2024-06-24
+
+### Added
+- Initial FastMCP 2.0 server implementation
+- 15 content management tools across search and core operations
+- Full text search with wildcard support
+- Advanced search using AFTS query language
+- Metadata search with property-based queries
+- CMIS SQL search capabilities
+- Complete document lifecycle management (upload, download, checkout, checkin)
+- Version management with major/minor version support
+- Folder operations and repository browsing
+- Property management for documents and folders
+- Multiple transport protocols (STDIO, HTTP, SSE)
+- Configuration via environment variables and .env files
+- Claude Desktop integration with Windows and macOS configs
+- MCP Inspector support for development testing
+- Comprehensive documentation and examples
+- Testing framework with unit and integration tests
+- Error handling and recovery patterns
+- Repository discovery and status reporting
+
+### Technical Implementation
+- python-alfresco-api integration for content services access
+- Pydantic v2 models for type safety
+- Async support for concurrent operations
+- Connection pooling and authentication management
+- Progress reporting and context logging
 - Configuration validation and environment setup 

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-alfresco-mcp-server
-Version: 1.2.0
+Version: 1.2.1
 Summary: FastMCP 3 server for Alfresco Content Services integration
 Project-URL: Homepage, https://github.com/stevereiner/python-alfresco-mcp-server
 Project-URL: Repository, https://github.com/stevereiner/python-alfresco-mcp-server
@@ -27,7 +27,7 @@ Requires-Dist: fastmcp<4,>=3.4.5
 Requires-Dist: httpx>=0.24.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: python-alfresco-api>=1.2.1
+Requires-Dist: python-alfresco-api>=1.2.2
 Requires-Dist: python-multipart>=0.0.6
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
@@ -55,7 +55,7 @@ Requires-Dist: pytest-xdist>=3.0.0; extra == 'test'
 Requires-Dist: pytest>=7.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-# Python Alfresco MCP Server v1.1 🚀
+# Python Alfresco MCP Server v1.2 🚀
 
 [![PyPI version](https://img.shields.io/pypi/v/python-alfresco-mcp-server)](https://pypi.org/project/python-alfresco-mcp-server/)
 [![PyPI downloads](https://pepy.tech/badge/python-alfresco-mcp-server)](https://pepy.tech/project/python-alfresco-mcp-server)
@@ -70,6 +70,15 @@ Built with [FastMCP 3](https://github.com/PrefectHQ/fastmcp).
 Features complete documentation, examples, and 
 config for various MCP clients (Claude Desktop, MCP Inspector, references to configuring others).
 
+## 🌟 What's New in v1.2
+
+- **Alfresco authentication methods**: connect via **basic**, **ticket**, or **OAuth2/OIDC** (`ALFRESCO_AUTH_METHOD` + `ALFRESCO_OAUTH2_*`, backed by `python-alfresco-api` 1.2.1) — see [Authentication](#-authentication).
+- **Optional MCP transport authentication**: secure the MCP server itself with an OAuth2 bearer token (`MCP_TRANSPORT_AUTH=true`), validated against your IdP's JWKS (HTTP/SSE transports; stdio unaffected).
+- **FastMCP 3**: upgraded to `fastmcp>=3.4.5,<4` (transport auth uses `JWTVerifier`).
+- **`download_document` custom folder**: optional `destination_dir` (default `~/Downloads`) — thanks [@jeremie-lesage](https://github.com/jeremie-lesage) ([#1](https://github.com/stevereiner/python-alfresco-mcp-server/pull/1)).
+- **Packaging**: switched to the hatchling build backend.
+- Requires **python-alfresco-api ≥ 1.2.1** (OAuth2/OIDC auth + OAuth2 service-account `displayName` fix).
+
 ## 🌟 What's New in v1.1
 
 ### **Modular Architecture & Enhanced Testing**
@@ -228,10 +237,15 @@ uv sync                    # Basic dependencies
 uv sync --extra dev        # With development tools  
 uv sync --extra test       # With testing tools
 uv sync --extra all        # Everything
+
+# Or an editable install into the active virtual environment (pip-style):
+uv pip install -e .
 ```
 
 ### 4. Configure Alfresco Connection
 
+> The examples below use HTTP **Basic** auth. Alfresco also supports **ticket** and **OAuth2/OIDC** (`ALFRESCO_AUTH_METHOD` + `ALFRESCO_OAUTH2_*`), and you can optionally secure the MCP transport with an OAuth2 bearer (`MCP_TRANSPORT_AUTH`) — see the [Authentication](#-authentication) section for all methods.
+
 **Option 1: Environment Variables**
 ```bash
 # Linux/Mac

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/README.md

@@ -1,4 +1,4 @@
-# Python Alfresco MCP Server v1.1 🚀
+# Python Alfresco MCP Server v1.2 🚀
 
 [![PyPI version](https://img.shields.io/pypi/v/python-alfresco-mcp-server)](https://pypi.org/project/python-alfresco-mcp-server/)
 [![PyPI downloads](https://pepy.tech/badge/python-alfresco-mcp-server)](https://pepy.tech/project/python-alfresco-mcp-server)
@@ -13,6 +13,15 @@ Built with [FastMCP 3](https://github.com/PrefectHQ/fastmcp).
 Features complete documentation, examples, and 
 config for various MCP clients (Claude Desktop, MCP Inspector, references to configuring others).
 
+## 🌟 What's New in v1.2
+
+- **Alfresco authentication methods**: connect via **basic**, **ticket**, or **OAuth2/OIDC** (`ALFRESCO_AUTH_METHOD` + `ALFRESCO_OAUTH2_*`, backed by `python-alfresco-api` 1.2.1) — see [Authentication](#-authentication).
+- **Optional MCP transport authentication**: secure the MCP server itself with an OAuth2 bearer token (`MCP_TRANSPORT_AUTH=true`), validated against your IdP's JWKS (HTTP/SSE transports; stdio unaffected).
+- **FastMCP 3**: upgraded to `fastmcp>=3.4.5,<4` (transport auth uses `JWTVerifier`).
+- **`download_document` custom folder**: optional `destination_dir` (default `~/Downloads`) — thanks [@jeremie-lesage](https://github.com/jeremie-lesage) ([#1](https://github.com/stevereiner/python-alfresco-mcp-server/pull/1)).
+- **Packaging**: switched to the hatchling build backend.
+- Requires **python-alfresco-api ≥ 1.2.1** (OAuth2/OIDC auth + OAuth2 service-account `displayName` fix).
+
 ## 🌟 What's New in v1.1
 
 ### **Modular Architecture & Enhanced Testing**
@@ -171,10 +180,15 @@ uv sync                    # Basic dependencies
 uv sync --extra dev        # With development tools  
 uv sync --extra test       # With testing tools
 uv sync --extra all        # Everything
+
+# Or an editable install into the active virtual environment (pip-style):
+uv pip install -e .
 ```
 
 ### 4. Configure Alfresco Connection
 
+> The examples below use HTTP **Basic** auth. Alfresco also supports **ticket** and **OAuth2/OIDC** (`ALFRESCO_AUTH_METHOD` + `ALFRESCO_OAUTH2_*`), and you can optionally secure the MCP transport with an OAuth2 bearer (`MCP_TRANSPORT_AUTH`) — see the [Authentication](#-authentication) section for all methods.
+
 **Option 1: Environment Variables**
 ```bash
 # Linux/Mac

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/alfresco_mcp_server/config.py

@@ -1,140 +1,146 @@
-"""
-Configuration management for MCP Server for Alfresco.
-"""
-
-import os
-from typing import Optional
-from pydantic import BaseModel, Field
-
-
-class AlfrescoConfig(BaseModel):
-    """Configuration for MCP Server for Alfresco."""
-    
-    # Alfresco server connection
-    alfresco_url: str = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_URL", "http://localhost:8080"),
-        description="Alfresco server URL"
-    )
-    
-    # Authentication method: basic | ticket | oauth2
-    auth_method: str = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_AUTH_METHOD", "basic").lower(),
-        description="Alfresco auth method: basic | ticket | oauth2"
-    )
-
-    # Authentication (basic / ticket)
-    username: str = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_USERNAME", "admin"),
-        description="Alfresco username"
-    )
-
-    password: str = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_PASSWORD", "admin"),
-        description="Alfresco password"
-    )
-
-    # OAuth2 (auth_method=oauth2) — Alfresco Identity Service / any OIDC IdP
-    oauth2_client_id: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_CLIENT_ID"),
-        description="OAuth2 client id"
-    )
-    oauth2_client_secret: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_CLIENT_SECRET"),
-        description="OAuth2 client secret"
-    )
-    oauth2_token_endpoint: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_TOKEN_ENDPOINT"),
-        description="OAuth2 token endpoint URL"
-    )
-    oauth2_grant_type: str = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_GRANT_TYPE", "client_credentials"),
-        description="OAuth2 grant type: client_credentials | refresh_token"
-    )
-    oauth2_scope: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_SCOPE"),
-        description="OAuth2 scope"
-    )
-    oauth2_access_token: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_ACCESS_TOKEN"),
-        description="Pre-obtained OAuth2 access token (optional)"
-    )
-    oauth2_refresh_token: Optional[str] = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_REFRESH_TOKEN"),
-        description="OAuth2 refresh token (optional)"
-    )
-    
-    # Connection settings
-    verify_ssl: bool = Field(
-        default_factory=lambda: os.getenv("ALFRESCO_VERIFY_SSL", "false").lower() == "true",
-        description="Verify SSL certificates"
-    )
-    
-    timeout: int = Field(
-        default_factory=lambda: int(os.getenv("ALFRESCO_TIMEOUT", "30")),
-        description="Request timeout in seconds"
-    )
-    
-    # MCP Server settings
-    server_name: str = Field(
-        default="python-alfresco-mcp-server",
-        description="MCP server name"
-    )
-    
-    server_version: str = Field(
-        default="1.0.0",
-        description="MCP server version"
-    )
-    
-    # FastAPI settings (for HTTP transport)
-    fastapi_host: str = Field(
-        default_factory=lambda: os.getenv("FASTAPI_HOST", "localhost"),
-        description="FastAPI host"
-    )
-    
-    fastapi_port: int = Field(
-        default_factory=lambda: int(os.getenv("FASTAPI_PORT", "8000")),
-        description="FastAPI port"
-    )
-    
-    fastapi_prefix: str = Field(
-        default_factory=lambda: os.getenv("FASTAPI_PREFIX", "/mcp"),
-        description="FastAPI URL prefix"
-    )
-    
-    # Logging
-    log_level: str = Field(
-        default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"),
-        description="Logging level"
-    )
-    
-    # Content settings
-    max_file_size: int = Field(
-        default_factory=lambda: int(os.getenv("MAX_FILE_SIZE", "100000000")),  # 100MB
-        description="Maximum file size for uploads in bytes"
-    )
-    
-    allowed_extensions: list[str] = Field(
-        default_factory=lambda: [
-            ".txt", ".pdf", ".doc", ".docx", ".xls", ".xlsx", 
-            ".ppt", ".pptx", ".jpg", ".jpeg", ".png", ".gif", 
-            ".zip", ".xml", ".json", ".csv"
-        ],
-        description="Allowed file extensions for uploads"
-    )
-    
-    class Config:
-        env_prefix = "ALFRESCO_"
-        case_sensitive = False
-        
-    def model_post_init(self, __context) -> None:
-        """Normalize URLs after initialization."""
-        if self.alfresco_url.endswith("/"):
-            self.alfresco_url = self.alfresco_url.rstrip("/")
-
-
-def load_config() -> AlfrescoConfig:
-    """Load configuration from environment variables and defaults."""
-    return AlfrescoConfig()
-
-# Global config instance for import
+"""
+Configuration management for MCP Server for Alfresco.
+"""
+
+import os
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class AlfrescoConfig(BaseModel):
+    """Configuration for MCP Server for Alfresco."""
+    
+    # Alfresco server connection
+    alfresco_url: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_URL", "http://localhost:8080"),
+        description="Alfresco server URL"
+    )
+    
+    # Authentication method: basic | ticket | oauth2
+    auth_method: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_AUTH_METHOD", "basic").lower(),
+        description="Alfresco auth method: basic | ticket | oauth2"
+    )
+
+    # Authentication (basic / ticket)
+    username: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_USERNAME", "admin"),
+        description="Alfresco username"
+    )
+
+    password: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_PASSWORD", "admin"),
+        description="Alfresco password"
+    )
+
+    ticket: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_TICKET"),
+        description="Pre-obtained Alfresco login ticket; with auth_method=ticket it is "
+                    "used as-is instead of being fetched from username/password"
+    )
+
+    # OAuth2 (auth_method=oauth2) — Alfresco Identity Service / any OIDC IdP
+    oauth2_client_id: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_CLIENT_ID"),
+        description="OAuth2 client id"
+    )
+    oauth2_client_secret: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_CLIENT_SECRET"),
+        description="OAuth2 client secret"
+    )
+    oauth2_token_endpoint: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_TOKEN_ENDPOINT"),
+        description="OAuth2 token endpoint URL"
+    )
+    oauth2_grant_type: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_GRANT_TYPE", "client_credentials"),
+        description="OAuth2 grant type: client_credentials | refresh_token"
+    )
+    oauth2_scope: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_SCOPE"),
+        description="OAuth2 scope"
+    )
+    oauth2_access_token: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_ACCESS_TOKEN"),
+        description="Pre-obtained OAuth2 access token (optional)"
+    )
+    oauth2_refresh_token: Optional[str] = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_OAUTH2_REFRESH_TOKEN"),
+        description="OAuth2 refresh token (optional)"
+    )
+    
+    # Connection settings
+    verify_ssl: bool = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_VERIFY_SSL", "false").lower() == "true",
+        description="Verify SSL certificates"
+    )
+    
+    timeout: int = Field(
+        default_factory=lambda: int(os.getenv("ALFRESCO_TIMEOUT", "30")),
+        description="Request timeout in seconds"
+    )
+    
+    # MCP Server settings
+    server_name: str = Field(
+        default="python-alfresco-mcp-server",
+        description="MCP server name"
+    )
+    
+    server_version: str = Field(
+        default="1.0.0",
+        description="MCP server version"
+    )
+    
+    # FastAPI settings (for HTTP transport)
+    fastapi_host: str = Field(
+        default_factory=lambda: os.getenv("FASTAPI_HOST", "localhost"),
+        description="FastAPI host"
+    )
+    
+    fastapi_port: int = Field(
+        default_factory=lambda: int(os.getenv("FASTAPI_PORT", "8000")),
+        description="FastAPI port"
+    )
+    
+    fastapi_prefix: str = Field(
+        default_factory=lambda: os.getenv("FASTAPI_PREFIX", "/mcp"),
+        description="FastAPI URL prefix"
+    )
+    
+    # Logging
+    log_level: str = Field(
+        default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"),
+        description="Logging level"
+    )
+    
+    # Content settings
+    max_file_size: int = Field(
+        default_factory=lambda: int(os.getenv("MAX_FILE_SIZE", "100000000")),  # 100MB
+        description="Maximum file size for uploads in bytes"
+    )
+    
+    allowed_extensions: list[str] = Field(
+        default_factory=lambda: [
+            ".txt", ".pdf", ".doc", ".docx", ".xls", ".xlsx", 
+            ".ppt", ".pptx", ".jpg", ".jpeg", ".png", ".gif", 
+            ".zip", ".xml", ".json", ".csv"
+        ],
+        description="Allowed file extensions for uploads"
+    )
+    
+    class Config:
+        env_prefix = "ALFRESCO_"
+        case_sensitive = False
+        
+    def model_post_init(self, __context) -> None:
+        """Normalize URLs after initialization."""
+        if self.alfresco_url.endswith("/"):
+            self.alfresco_url = self.alfresco_url.rstrip("/")
+
+
+def load_config() -> AlfrescoConfig:
+    """Load configuration from environment variables and defaults."""
+    return AlfrescoConfig()
+
+# Global config instance for import
 config = load_config() 

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/alfresco_mcp_server/utils/connection.py

@@ -20,6 +20,9 @@ def get_alfresco_config() -> dict:
         'auth_method': os.getenv('ALFRESCO_AUTH_METHOD', 'basic').lower(),  # basic | ticket | oauth2
         'username': os.getenv('ALFRESCO_USERNAME', 'admin'),
         'password': os.getenv('ALFRESCO_PASSWORD', 'admin'),
+        # A login ticket obtained elsewhere. With auth_method=ticket this replaces
+        # username/password entirely instead of being fetched from them.
+        'ticket': os.getenv('ALFRESCO_TICKET', ''),
         'verify_ssl': os.getenv('ALFRESCO_VERIFY_SSL', 'false').lower() == 'true',
         'timeout': int(os.getenv('ALFRESCO_TIMEOUT', '30')),
         'oauth2': {
@@ -38,14 +41,23 @@ def _build_auth_util(config: dict):
     """Build a python-alfresco-api auth util for the configured auth_method.
 
     Returns None for basic auth (ClientFactory builds its own from username/password).
-    - ticket: TicketAuthUtil self-fetches an Alfresco login ticket (Authorization: Basic base64(ticket)).
+    - ticket: either a caller-supplied login ticket (ALFRESCO_TICKET) used as-is, or one
+      TicketAuthUtil self-fetches from username/password. Either way the wire format is
+      Authorization: Basic base64(ticket).
     - oauth2: OAuth2AuthUtil (client_credentials/refresh, or a pre-obtained access_token → Bearer),
       e.g. against Alfresco Identity Service / Keycloak.
     """
     method = config.get('auth_method', 'basic')
     if method == 'ticket':
         from python_alfresco_api.auth_util import TicketAuthUtil
-        logger.info(">> Using Alfresco ticket authentication")
+        ticket = config.get('ticket')
+        if ticket:
+            logger.info(">> Using Alfresco ticket authentication (caller-supplied ticket)")
+            return TicketAuthUtil(
+                base_url=config['alfresco_url'], ticket=ticket,
+                verify_ssl=config['verify_ssl'], timeout=config['timeout'],
+            )
+        logger.info(">> Using Alfresco ticket authentication (acquired from username/password)")
         return TicketAuthUtil(
             config['username'], config['password'],
             base_url=config['alfresco_url'],

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/pyproject.toml

@@ -35,7 +35,7 @@ exclude = [
 
 [project]
 name = "python-alfresco-mcp-server"
-version = "1.2.0"
+version = "1.2.1"
 description = "FastMCP 3 server for Alfresco Content Services integration"
 authors = [{name = "Steve Reiner", email = "example@example.com"}]
 license = "Apache-2.0"
@@ -63,7 +63,7 @@ dependencies = [
     "fastmcp>=3.4.5,<4",
     
     # Alfresco integration
-    "python-alfresco-api>=1.2.1",
+    "python-alfresco-api>=1.2.2",
     
     # Configuration and utilities
     "pydantic>=2.0.0",

{python_alfresco_mcp_server-1.2.0 → python_alfresco_mcp_server-1.2.1}/sample-dot-env.txt

@@ -1,59 +1,64 @@
-# Alfresco MCP Server Configuration
-# Copy this file to .env and customize for your environment
-# The .env file will be ignored by git for security
-
-# === REQUIRED: Alfresco Connection ===
-ALFRESCO_URL=http://localhost:8080
-
-# === Authentication ===
-# ALFRESCO_AUTH_METHOD: basic | ticket | oauth2   (default: basic)
-#   basic  = HTTP Basic (username/password below)
-#   ticket = Alfresco login ticket (username/password below; a ticket is fetched and used
-#            as Authorization: Basic base64(ticket) — password isn't sent on every request)
-#   oauth2 = OIDC Bearer token via Alfresco Identity Service / Keycloak (see OAuth2 block)
-ALFRESCO_AUTH_METHOD=basic
-ALFRESCO_USERNAME=admin
-ALFRESCO_PASSWORD=admin
-
-# === OPTIONAL: OAuth2 (only when ALFRESCO_AUTH_METHOD=oauth2) ===
-# Requires Alfresco's identity-service subsystem configured against an OIDC IdP (Keycloak).
-# Either client_credentials (client id+secret+token endpoint) OR a pre-obtained access token.
-#ALFRESCO_OAUTH2_CLIENT_ID=flexible-graphrag
-#ALFRESCO_OAUTH2_CLIENT_SECRET=flexible-graphrag-secret
-#ALFRESCO_OAUTH2_TOKEN_ENDPOINT=http://localhost:8091/realms/alfresco/protocol/openid-connect/token
-#ALFRESCO_OAUTH2_GRANT_TYPE=client_credentials
-#ALFRESCO_OAUTH2_SCOPE=
-#ALFRESCO_OAUTH2_ACCESS_TOKEN=
-#ALFRESCO_OAUTH2_REFRESH_TOKEN=
-
-# === OPTIONAL: Connection Settings ===
-ALFRESCO_VERIFY_SSL=false
-ALFRESCO_TIMEOUT=30
-
-# === OPTIONAL: Server Settings ===
-LOG_LEVEL=INFO
-MAX_FILE_SIZE=100000000
-
-# === OPTIONAL: HTTP Transport Settings ===
-FASTAPI_HOST=localhost
-FASTAPI_PORT=8000
-
-# === OPTIONAL: MCP Transport Authentication (secures the MCP server itself) ===
-# Distinct from ALFRESCO_AUTH_METHOD (which is how the server authenticates TO Alfresco).
-# When enabled, HTTP/SSE clients (incl. MCP Inspector) must send Authorization: Bearer <token>.
-# stdio transport ignores this. RS256 bearer tokens are validated against the IdP's JWKS.
-MCP_TRANSPORT_AUTH=false
-# JWKS endpoint of your OIDC IdP (default = local Keycloak realm used for Alfresco identity-service)
-#MCP_AUTH_JWKS_URI=http://host.docker.internal:8091/realms/alfresco/protocol/openid-connect/certs
-# Optional strict issuer check. NOTE: the MCP SDK requires an HTTPS issuer URL (localhost excepted),
-# so leave unset for a local http Keycloak — the JWKS signature check still gates access.
-#MCP_AUTH_ISSUER=https://<your-idp>/realms/<realm>
-# Optional audience check (unset = don't validate aud)
-#MCP_AUTH_AUDIENCE=
-
-# === NOTES ===
-# - Environment variables take precedence over defaults
-# - python-alfresco-api may have its own configuration (check its docs)
-# - For production, use environment variables or secure secret management
-# - Boolean values: true/false (case insensitive)
+# Alfresco MCP Server Configuration
+# Copy this file to .env and customize for your environment
+# The .env file will be ignored by git for security
+
+# === REQUIRED: Alfresco Connection ===
+ALFRESCO_URL=http://localhost:8080
+
+# === Authentication ===
+# ALFRESCO_AUTH_METHOD: basic | ticket | oauth2   (default: basic)
+#   basic  = HTTP Basic (username/password below)
+#   ticket = Alfresco login ticket, sent as Authorization: Basic base64(ticket).
+#            Either set ALFRESCO_TICKET to a ticket you already have (no username or
+#            password needed at all), or leave it empty and a ticket is fetched from the
+#            username/password below so the password isn't sent on every request.
+#   oauth2 = OIDC Bearer token via Alfresco Identity Service / Keycloak (see OAuth2 block)
+ALFRESCO_AUTH_METHOD=basic
+ALFRESCO_USERNAME=admin
+ALFRESCO_PASSWORD=admin
+# A pre-obtained login ticket (only used when ALFRESCO_AUTH_METHOD=ticket). Set this and
+# username/password are ignored; it is never re-fetched, so it stops working when it expires.
+#ALFRESCO_TICKET=TICKET_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# === OPTIONAL: OAuth2 (only when ALFRESCO_AUTH_METHOD=oauth2) ===
+# Requires Alfresco's identity-service subsystem configured against an OIDC IdP (Keycloak).
+# Either client_credentials (client id+secret+token endpoint) OR a pre-obtained access token.
+#ALFRESCO_OAUTH2_CLIENT_ID=flexible-graphrag
+#ALFRESCO_OAUTH2_CLIENT_SECRET=flexible-graphrag-secret
+#ALFRESCO_OAUTH2_TOKEN_ENDPOINT=http://localhost:8091/realms/alfresco/protocol/openid-connect/token
+#ALFRESCO_OAUTH2_GRANT_TYPE=client_credentials
+#ALFRESCO_OAUTH2_SCOPE=
+#ALFRESCO_OAUTH2_ACCESS_TOKEN=
+#ALFRESCO_OAUTH2_REFRESH_TOKEN=
+
+# === OPTIONAL: Connection Settings ===
+ALFRESCO_VERIFY_SSL=false
+ALFRESCO_TIMEOUT=30
+
+# === OPTIONAL: Server Settings ===
+LOG_LEVEL=INFO
+MAX_FILE_SIZE=100000000
+
+# === OPTIONAL: HTTP Transport Settings ===
+FASTAPI_HOST=localhost
+FASTAPI_PORT=8000
+
+# === OPTIONAL: MCP Transport Authentication (secures the MCP server itself) ===
+# Distinct from ALFRESCO_AUTH_METHOD (which is how the server authenticates TO Alfresco).
+# When enabled, HTTP/SSE clients (incl. MCP Inspector) must send Authorization: Bearer <token>.
+# stdio transport ignores this. RS256 bearer tokens are validated against the IdP's JWKS.
+MCP_TRANSPORT_AUTH=false
+# JWKS endpoint of your OIDC IdP (default = local Keycloak realm used for Alfresco identity-service)
+#MCP_AUTH_JWKS_URI=http://host.docker.internal:8091/realms/alfresco/protocol/openid-connect/certs
+# Optional strict issuer check. NOTE: the MCP SDK requires an HTTPS issuer URL (localhost excepted),
+# so leave unset for a local http Keycloak — the JWKS signature check still gates access.
+#MCP_AUTH_ISSUER=https://<your-idp>/realms/<realm>
+# Optional audience check (unset = don't validate aud)
+#MCP_AUTH_AUDIENCE=
+
+# === NOTES ===
+# - Environment variables take precedence over defaults
+# - python-alfresco-api may have its own configuration (check its docs)
+# - For production, use environment variables or secure secret management
+# - Boolean values: true/false (case insensitive)
 # - File size in bytes (100000000 = 100MB)