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

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

6. Configuration (.env or shell)

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