Alfresco Mcp Lab

Alfresco MCP Lab

> A reproducible lab to experiment with the Model Context Protocol (MCP) against Alfresco Community Edition using Docker.

Architecture

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
• [MCP SERVER](mcp-server) – Python Alfresco MCP Server by Steve Reiner, exposed at http://localhost:8003/mcp
• [MCP CLIENT – CLI](mcp-client-cmd) – MCP CLI
• Ollama – local LLM runtime (this lab uses the gpt-oss model)
• [MCP CLIENT – UI](mcp-client-ui) – Chainlit 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:

docker compose up --build

Once started:

• Alfresco Repository: http://localhost:8080/alfresco

(default credentials admin / admin)

• MCP Server: http://localhost:8003/mcp

About compose.yaml

This repo compose.yaml includes sub-stacks:

include:
  - mcp-server/compose.yaml
  - alfresco/compose.yaml

If your Compose version doesn’t support include, run with multiple files:

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 ``

1. Run the CLI:

``bash cd mcp-client-cmd docker compose run --rm mcp-client ``

1. 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

MCP client (UI)

1. Switch to the MCP Client UI folder

cd mcp-client-ui

1. 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) LITELLMAPIKEY=YOURAPIKEY LITELLMAPIBASE=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" > ``

1. Start the UI:

``bash docker compose up --build ``

1. Open 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 (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)
• Official SDKs: TypeScript, Python, Java, Go, Kotlin, Swift, C#, Ruby, Rust. Each supports building servers/clients with the same core semantics (Model Context Protocol)

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)

1. 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, Spring AI)

1. 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)

> 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) generates ACS Docker assets
• Python Alfresco MCP Server by Steve Reiner
• MCP CLI by chrishayuk
• Chainlit
• LiteLLM
• Ollama

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aborroy
• Source: aborroy/alfresco-mcp-lab
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.