# 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

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

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

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