https://github.com/aborroy/alfresco-mcp-lab
Laboratory to use a MCP Server with Alfresco Community
https://github.com/aborroy/alfresco-mcp-lab
alfresco docker mcp-server
Last synced: 4 months ago
JSON representation
Laboratory to use a MCP Server with Alfresco Community
- Host: GitHub
- URL: https://github.com/aborroy/alfresco-mcp-lab
- Owner: aborroy
- License: apache-2.0
- Created: 2025-08-18T10:21:24.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-22T06:09:52.000Z (10 months ago)
- Last Synced: 2025-09-18T21:49:58.767Z (9 months ago)
- Topics: alfresco, docker, mcp-server
- Language: Dockerfile
- Homepage:
- Size: 1.25 MB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Alfresco MCP Lab
> A reproducible lab to experiment with the **Model Context Protocol (MCP)** against **Alfresco Community Edition** using Docker.
## Architecture
```mermaid
flowchart LR
O("`OLLAMA
local gpt-oss`")
CIC("`CIC LiteLLM
service claude`")
CMD("`MCP CLIENT
CMD`")
UI("`MCP CLIENT
UI`")
S("`MCP SERVER
community project`")
A("`ALFRESCO
Community`")
CMD -- "8003" --> S
S -- "8080" --> A
UI -- "8003" --> S
O -. "11434" .-> CMD
CIC -. "443" .-> UI
```
## Components
* [ALFRESCO](alfresco) – ACS Community Edition at [http://localhost:8080/alfresco](http://localhost:8080/alfresco)
* [MCP SERVER](mcp-server) – [Python Alfresco MCP Server](https://github.com/stevereiner/python-alfresco-mcp-server) by *Steve Reiner*, exposed at [http://localhost:8003/mcp](http://localhost:8003/mcp)
* [MCP CLIENT – CLI](mcp-client-cmd) – [MCP CLI](https://github.com/chrishayuk/mcp-cli)
* [Ollama](https://ollama.com/) – local LLM runtime (this lab uses the `gpt-oss` model)
* [MCP CLIENT – UI](mcp-client-ui) – [Chainlit](https://chainlit.io) app using *LiteLLM* as the LLM gateway (defaults to Claude Sonnet; configurable)
## Prerequisites
* Docker & Docker Compose
* For the MCP Client CMD
* Ollama running on the host with the `gpt-oss` model pulled (around 13 GB):
```bash
brew install ollama # macOS (or see ollama.com for your OS)
ollama pull gpt-oss
```
* For the MCP Client UI
* `LITELLM_API_KEY` in your environment (or in `.env`) for your chosen provider
> *Networking note*
> `host.docker.internal` works out-of-the-box on Docker Desktop (macOS/Windows)
> On Linux, add `extra_hosts: ["host.docker.internal:host-gateway"]` to services that must reach the host (e.g., to call Ollama running on the host)
## Quick start
Bring up Alfresco and MCP Server:
```bash
docker compose up --build
```
Once started:
* Alfresco Repository: [http://localhost:8080/alfresco](http://localhost:8080/alfresco)
(default credentials `admin` / `admin`)
* MCP Server: [http://localhost:8003/mcp](http://localhost:8003/mcp)
### About `compose.yaml`
This repo `compose.yaml` includes sub-stacks:
```yaml
include:
- mcp-server/compose.yaml
- alfresco/compose.yaml
```
If your Compose version doesn’t support `include`, run with multiple files:
```bash
docker compose -f alfresco/compose.yaml -f mcp-server/compose.yaml up --build
```
## MCP client (CLI)
This client uses a local LLM (`gpt-oss`) via Ollama
1. Verify Ollama and model:
```bash
ollama list
# Expect something like:
# gpt-oss:latest ... 13 GB
```
2. Run the CLI:
```bash
cd mcp-client-cmd
docker compose run --rm mcp-client
```
3. Try a prompt:
```
Search Alfresco for documents containing "budget", return at most 5 results.
```
Helpful prompts from Steve Reiner:
[https://github.com/stevereiner/python-alfresco-mcp-server/blob/main/prompts-for-claude.md](https://github.com/stevereiner/python-alfresco-mcp-server/blob/main/prompts-for-claude.md)
## MCP client (UI)
1. Switch to the MCP Client UI folder
```bash
cd mcp-client-ui
```
2. Create your `.env` from the example and set LiteLLM + MCP/ACS endpoints.
* macOS/Linux:
```bash
cp .env.example .env
```
* Windows (PowerShell):
```powershell
Copy-Item .env.example .env
```
Example `.env`:
```dotenv
# LiteLLM (replace with your provider/base/model)
LITELLM_API_KEY=YOUR_API_KEY
LITELLM_API_BASE=https://api.your-provider.example/v1
LITELLM_MODEL=anthropic/claude-3-5-sonnet
# MCP Server
MCP_URL=http://host.docker.internal:8003/mcp
# Logging
LOG_LEVEL=INFO
```
> On Linux, if the UI container can’t reach the host, add:
>
> ```yaml
> extra_hosts:
> - "host.docker.internal:host-gateway"
> ```
3. Start the UI:
```bash
docker compose up --build
```
4. Open [http://localhost:8000](http://localhost:8000) and chat
You may try a more complex *prompt*, performing actions in Alfresco Repository and following a complete workflow:
```
Let's test a complete document management workflow:
1. Create a folder called "Project_Alpha"
2. Upload a document called "requirements.md" to that folder with some project requirements content
3. Get the document properties to verify it was created correctly
4. Update the document properties to add a title and description
5. Checkout the document for editing
6. Checkin the document as major version with appropriate comments
7. Search for documents containing "requirements" using basic search (AFTS full-text)
8. Try advanced search with date filters to find the same document (AFTS with filters)
9. Use metadata search to find it by title property (AFTS property search)
10. Use CMIS search with SQL query to find it by name (CMIS SQL)
11. Download the document to verify content integrity
Walk me through each step and confirm success before moving to the next.
```
## Ports summary
* Alfresco (ACS): 8080 (`/alfresco`)
* MCP Server: 8003 (`/mcp`)
* MCP UI (Chainlit): 8000
* Ollama: 11434
* LiteLLM: 443
## Building everything yourself
See [docs/instructions.md](docs/instructions.md) for from-scratch builds and deeper configuration
## MCP Server tools for Alfresco
The `mcp-server/` folder wires the lab to [python-alfresco-mcp-server](https://github.com/stevereiner/python-alfresco-mcp-server) (built on FastMCP 2.0). It exposes a focused toolset for content search + document lifecycle against Alfresco. In the latest 1.1 line, the server documents the following capabilities and transports (STDIO, HTTP, SSE)
### Tools
* Search Content: Full-text search over *content and properties*, basic wildcards
* Advanced Search (AFTS): AFTS query language with date filters, sort, field targeting (tool name appears as the AFTS/“advanced search” tool in docs)
* Metadata Search: Property predicates (equals/contains/ranges) over node metadata
* CMIS (SQL-like) Search: CMIS query for complex discovery
* Upload: Create a new document with content
* Download: Fetch document content by id/path
* Check-out / Check-in / Cancel check-out: Working-copy flow and new versions (major/minor with comments)
* Create Folder: Create folder by parent id/path
* Folder Browse: List children + basic metadata
* Delete Node: Trash (or permanent) delete for documents/folders
* Get / Set Properties: Read/update node properties (incl. name)
* Repository Info *(also exposed as a Resource)*: Edition, version, status and module configuration
## Model Context Protocol (MCP) — spec & SDKs
* Spec & Concepts: Tools, Resources, Prompts, transports, and protocol revisions are covered in the official docs/spec. Start here for how tools are defined and invoked ([Model Context Protocol](https://modelcontextprotocol.io/docs/concepts/tools))
* Official SDKs: TypeScript, Python, **Java**, Go, Kotlin, Swift, C#, Ruby, Rust. Each supports building servers/clients with the same core semantics ([Model Context Protocol](https://modelcontextprotocol.io/docs/sdk))
### Best ways to implement an Alfresco MCP server
1. Python + FastMCP (used for this lab)
Fast to stand up, battle-tested with Alfresco via `python-alfresco-mcp-server`, and supports STDIO/HTTP/SSE out of the box. Ideal for demos and production pilots. ([GitHub](https://github.com/stevereiner/python-alfresco-mcp-server))
2. Java + Spring AI (MCP Java SDK + Spring Boot starters)
First-class Java SDK maintained with Spring; Spring AI adds auto-config, starters, and both client/server support. Best fit for teams standardizing on JVM/Spring. ([MCP](https://github.com/modelcontextprotocol/java-sdk), [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html))
3. TypeScript (official SDK)
Great if your stack is Node/TS or you want to align with Claude Desktop/TS examples. Same protocol model, rich Zod schemas. ([Model Context Protocol](https://modelcontextprotocol.io/docs/sdk))
> You can also target Go/Kotlin/Swift/C#/Ruby/Rust via the official SDKs when platform constraints or existing services make those a better fit
## Credits & acknowledgements
* [Alfresco Installer (`alf-cli`)](https://github.com/aborroy/alf-cli) generates ACS Docker assets
* [Python Alfresco MCP Server](https://github.com/stevereiner/python-alfresco-mcp-server) by *Steve Reiner*
* [MCP CLI](https://github.com/chrishayuk/mcp-cli) by *chrishayuk*
* [Chainlit](https://chainlit.io)
* [LiteLLM](https://www.litellm.ai)
* [Ollama](https://ollama.com/)