{"id":31156103,"url":"https://github.com/aborroy/alfresco-mcp-lab","last_synced_at":"2026-02-16T17:04:34.477Z","repository":{"id":310486711,"uuid":"1040011098","full_name":"aborroy/alfresco-mcp-lab","owner":"aborroy","description":"Laboratory to use a MCP Server with Alfresco Community","archived":false,"fork":false,"pushed_at":"2025-08-22T06:09:52.000Z","size":1308,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-18T21:49:58.767Z","etag":null,"topics":["alfresco","docker","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aborroy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-18T10:21:24.000Z","updated_at":"2025-08-30T12:58:28.000Z","dependencies_parsed_at":"2025-08-18T13:23:43.923Z","dependency_job_id":"d921a2aa-d4e4-4bf7-b161-30b60b95150a","html_url":"https://github.com/aborroy/alfresco-mcp-lab","commit_stats":null,"previous_names":["aborroy/alfresco-mcp-lab"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aborroy/alfresco-mcp-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aborroy%2Falfresco-mcp-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aborroy%2Falfresco-mcp-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aborroy%2Falfresco-mcp-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aborroy%2Falfresco-mcp-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aborroy","download_url":"https://codeload.github.com/aborroy/alfresco-mcp-lab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aborroy%2Falfresco-mcp-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29513449,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T09:05:14.864Z","status":"ssl_error","status_checked_at":"2026-02-16T08:55:59.364Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alfresco","docker","mcp-server"],"created_at":"2025-09-18T20:54:47.341Z","updated_at":"2026-02-16T17:04:34.460Z","avatar_url":"https://github.com/aborroy.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alfresco MCP Lab\n\n\u003e A reproducible lab to experiment with the **Model Context Protocol (MCP)** against **Alfresco Community Edition** using Docker.\n\n## Architecture\n\n```mermaid                                                                                                          \nflowchart LR\n  O(\"`OLLAMA\n  local gpt-oss`\")\n  CIC(\"`CIC LiteLLM\n  service claude`\")\n  CMD(\"`MCP CLIENT \n  CMD`\")\n  UI(\"`MCP CLIENT \n  UI`\")\n  S(\"`MCP SERVER\n  community project`\")\n  A(\"`ALFRESCO\n  Community`\")\n\n  CMD -- \"8003\" --\u003e S\n  S   -- \"8080\" --\u003e A\n  UI  -- \"8003\" --\u003e S\n\n  O -. \"11434\" .-\u003e CMD\n  CIC -. \"443\" .-\u003e UI                                                                                                                 \n```\n\n## Components\n\n* [ALFRESCO](alfresco) – ACS Community Edition at [http://localhost:8080/alfresco](http://localhost:8080/alfresco)\n* [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)\n* [MCP CLIENT – CLI](mcp-client-cmd) – [MCP CLI](https://github.com/chrishayuk/mcp-cli)\n  * [Ollama](https://ollama.com/) – local LLM runtime (this lab uses the `gpt-oss` model)\n* [MCP CLIENT – UI](mcp-client-ui) – [Chainlit](https://chainlit.io) app using *LiteLLM* as the LLM gateway (defaults to Claude Sonnet; configurable)\n\n## Prerequisites\n\n* Docker \u0026 Docker Compose\n* For the MCP Client CMD\n  * Ollama running on the host with the `gpt-oss` model pulled (around 13 GB):\n\n    ```bash\n    brew install ollama   # macOS (or see ollama.com for your OS)\n    ollama pull gpt-oss\n    ```\n* For the MCP Client UI\n  * `LITELLM_API_KEY` in your environment (or in `.env`) for your chosen provider\n\n\u003e *Networking note*\n\u003e `host.docker.internal` works out-of-the-box on Docker Desktop (macOS/Windows)\n\u003e 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)\n\n## Quick start\n\nBring up Alfresco and MCP Server:\n\n```bash\ndocker compose up --build\n```\n\nOnce started:\n\n* Alfresco Repository: [http://localhost:8080/alfresco](http://localhost:8080/alfresco)\n  (default credentials `admin` / `admin`)\n* MCP Server: [http://localhost:8003/mcp](http://localhost:8003/mcp)\n\n### About `compose.yaml`\n\nThis repo `compose.yaml` includes sub-stacks:\n\n```yaml\ninclude:\n  - mcp-server/compose.yaml\n  - alfresco/compose.yaml\n```\n\nIf your Compose version doesn’t support `include`, run with multiple files:\n\n```bash\ndocker compose -f alfresco/compose.yaml -f mcp-server/compose.yaml up --build\n```\n\n## MCP client (CLI)\n\nThis client uses a local LLM (`gpt-oss`) via Ollama\n\n1. Verify Ollama and model:\n\n   ```bash\n   ollama list\n   # Expect something like:\n   # gpt-oss:latest   ...   13 GB\n   ```\n\n2. Run the CLI:\n\n   ```bash\n   cd mcp-client-cmd\n   docker compose run --rm mcp-client\n   ```\n\n3. Try a prompt:\n\n   ```\n   Search Alfresco for documents containing \"budget\", return at most 5 results.\n   ```\n\nHelpful prompts from Steve Reiner:\n[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)\n\n## MCP client (UI)\n\n1. Switch to the MCP Client UI folder\n\n```bash\ncd mcp-client-ui\n```\n\n2. Create your `.env` from the example and set LiteLLM + MCP/ACS endpoints.\n\n   * macOS/Linux:\n\n     ```bash\n     cp .env.example .env\n     ```\n   * Windows (PowerShell):\n\n     ```powershell\n     Copy-Item .env.example .env\n     ```\n\n   Example `.env`:\n\n   ```dotenv\n   # LiteLLM (replace with your provider/base/model)\n   LITELLM_API_KEY=YOUR_API_KEY\n   LITELLM_API_BASE=https://api.your-provider.example/v1\n   LITELLM_MODEL=anthropic/claude-3-5-sonnet\n\n   # MCP Server\n   MCP_URL=http://host.docker.internal:8003/mcp\n\n   # Logging\n   LOG_LEVEL=INFO\n   ```\n\n   \u003e On Linux, if the UI container can’t reach the host, add:\n   \u003e\n   \u003e ```yaml\n   \u003e extra_hosts:\n   \u003e   - \"host.docker.internal:host-gateway\"\n   \u003e ```\n\n3. Start the UI:\n\n   ```bash\n   docker compose up --build\n   ```\n\n4. Open [http://localhost:8000](http://localhost:8000) and chat\n\n![MCP UI Sample Prompt](docs/mcp-ui-sample.png)\n\nYou may try a more complex *prompt*, performing actions in Alfresco Repository and following a complete workflow:\n\n```\nLet's test a complete document management workflow:\n\n1. Create a folder called \"Project_Alpha\"\n2. Upload a document called \"requirements.md\" to that folder with some project requirements content\n3. Get the document properties to verify it was created correctly\n4. Update the document properties to add a title and description\n5. Checkout the document for editing\n6. Checkin the document as major version with appropriate comments\n7. Search for documents containing \"requirements\" using basic search (AFTS full-text)\n8. Try advanced search with date filters to find the same document (AFTS with filters)\n9. Use metadata search to find it by title property (AFTS property search)\n10. Use CMIS search with SQL query to find it by name (CMIS SQL)\n11. Download the document to verify content integrity\n\nWalk me through each step and confirm success before moving to the next.\n```\n\n## Ports summary\n\n* Alfresco (ACS): 8080 (`/alfresco`)\n* MCP Server: 8003 (`/mcp`)\n* MCP UI (Chainlit): 8000\n* Ollama: 11434\n* LiteLLM: 443\n\n## Building everything yourself\n\nSee [docs/instructions.md](docs/instructions.md) for from-scratch builds and deeper configuration\n\n## MCP Server tools for Alfresco\n\nThe `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)\n\n### Tools\n\n* Search Content: Full-text search over *content and properties*, basic wildcards\n* Advanced Search (AFTS): AFTS query language with date filters, sort, field targeting (tool name appears as the AFTS/“advanced search” tool in docs)\n* Metadata Search: Property predicates (equals/contains/ranges) over node metadata\n* CMIS (SQL-like) Search: CMIS query for complex discovery\n* Upload: Create a new document with content\n* Download: Fetch document content by id/path\n* Check-out / Check-in / Cancel check-out: Working-copy flow and new versions (major/minor with comments)\n* Create Folder: Create folder by parent id/path\n* Folder Browse: List children + basic metadata\n* Delete Node: Trash (or permanent) delete for documents/folders\n* Get / Set Properties: Read/update node properties (incl. name)\n* Repository Info *(also exposed as a Resource)*: Edition, version, status and module configuration\n\n## Model Context Protocol (MCP) — spec \u0026 SDKs\n\n* Spec \u0026 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))\n* 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))\n\n### Best ways to implement an Alfresco MCP server\n\n1. Python + FastMCP (used for this lab)\n   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))\n\n2. Java + Spring AI (MCP Java SDK + Spring Boot starters)\n   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))\n\n3. TypeScript (official SDK)\n   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))\n\n\u003e 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\n\n## Credits \u0026 acknowledgements\n\n* [Alfresco Installer (`alf-cli`)](https://github.com/aborroy/alf-cli) generates ACS Docker assets\n* [Python Alfresco MCP Server](https://github.com/stevereiner/python-alfresco-mcp-server) by *Steve Reiner*\n* [MCP CLI](https://github.com/chrishayuk/mcp-cli) by *chrishayuk*\n* [Chainlit](https://chainlit.io)\n* [LiteLLM](https://www.litellm.ai)\n* [Ollama](https://ollama.com/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faborroy%2Falfresco-mcp-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faborroy%2Falfresco-mcp-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faborroy%2Falfresco-mcp-lab/lists"}