Alfresco MCP Chat (hyland-mcp-gen)

Status: early-stage proof-of-concept

Turns hundreds Alfresco MCP REST endpoints into a 20-50-tool control plane a local LLM can handle. Everything runs on a laptop: FastAPI server + FastMCP + Ollama (default model mistral). The key is a lightweight router that selects only the relevant tools for each user query.

1. Why it exists

• Shrink the API surface, so the LLM never sees the full MCP spec
• Stay local-first, no cloud calls, perfect for local development
• Be hackable: flat repo, single-file entry points, Make targets

---

2. Quick start

git clone https://github.com/your-org/hyland-mcp-gen.git
cd hyland-mcp-gen

make venv            # python -m venv .venv && pip install -U pip uv
make deps            # uv pip sync requirements.lock
make server          # FastAPI server on :3333
ollama run mistral   # start the model in another terminal
make client          # Rich CLI chat

Assumes

• Ollama 0.4+ with model mistral
• Port 3333 free
• Alfresco 25.x at http://localhost:8080 (override via .env)

3. Requirements

Layer	Version	Why
Python	3.10–3.13	async + pattern-matching
make	any	convenience, optional
Ollama	0.4+	local LLM
FastMCP	pinned	agent framework
Rich	13.x	streaming CLI
Alfresco MCP	25.x	back-end
uv	installed by make venv	fast resolver

No extra system libraries.

4. Project layout

hyland-mcp-gen/
* Makefile               # venv, lock, deps, server, client
* pyproject.toml         # top-level deps
* requirements.lock      # fully pinned set
* server.py              # FastAPI + FastMCP
* chat_service.py        # Rich CLI
* generate_mcp_tools.py  # Swagger/OpenAPI > JSON tools
* alfresco_*_tools.json  # sample tool sets

5. Everyday commands

Target	Action
make venv	create .venv + install uv
make lock	regenerate requirements.lock
make deps	install exact lockfile versions
make server	run FastAPI server
make client	run Rich CLI
make clean	remove venv, lockfile, byte-code

6. Configuration (.env or shell)

Var	Default	Purpose
MCP_URL	http://localhost:3333/mcp	client > server URL
OLLAMA_MODEL	mistral	model name/tag
PORT	3333	server port override
ALFRESCO_URL	http://localhost:8080	MCP back-end
ALFRESCO_USER	admin	username
ALFRESCO_PASS	admin	password

7. How it works

User > Router > 20 tool specs > LLM > HTTP call > Alfresco

7.1 Tool generation (generate_mcp_tools.py)

• Accepts Swagger 2 / OpenAPI 3 URL or file.
• Resolves $ref, drops noise, adds examples.
• Emits OpenAI-style JSON tools.

7.2 Router (RouterBuilder)

• Counts path segments, removes stop-words, promotes frequent nouns (case, rendition, ...) to entities.
• Clusters endpoints per entity; each cluster = agent.
• Scores agents against query terms; top agents donate tools (hard-capped < 20).
• Typical reduction: hundreds > 15-35 tools in < 50 ms.

7.3 Executor (FastMCP + httpx)

• Fills path/query/body params, keeps connections hot, streams JSON or text.
• Errors surface directly in CLI for fast debugging.

8. Regenerate tool sets

python generate_mcp_tools.py \
  --input https://api-explorer.alfresco.com/api-explorer/definitions/alfresco-core.yaml \
  --output alfresco_core_tools.json

9. Dependency workflow

1. Edit pyproject.toml.
2. make lock to rewrite requirements.lock.
3. make deps to install. CI/prod install from the lock file only.

Clever routing beats massive context: Alfresco MCP Chat keeps the model fast, local, and secure while still exposing the full power of Alfresco’s API surface