# rigid-pipeline-mcp

**[English](#english) | [Polski](#polski)**

---

## English

A local MCP server exposing reusable, single-item "blocks" for file
operations, document metadata, folder analysis, local-LLM queries, and
SQLite CRUD — callable individually as normal MCP tools, or composed
into one call via `run_pipeline`.

### Architecture

`gateway.py` mounts five independent `FastMCP` sub-servers into one process:

| Sub-server | Tools | Namespace |
|---|---|---|
| file-ops | find/read/write/hash files, preview/execute delete & move | `files_*` |
| metadata | epub / audio+m4b / PDF / DOCX metadata | `meta_*` |
| analysis | folder extension breakdown + tree | `fs_*` |
| llm | local-model queries via LM Studio (OpenAI-compatible) | `llm_*` |
| sql | SQLite schema/query/execute | `db_*` |
| orchestrator | `run_pipeline` — compose any of the above in one call | — |

### Running it

```bash
uv sync
uv run fastmcp dev inspector gateway.py   # interactive testing
```

Point any MCP client at `gateway.py` over stdio for real use.

### Composing pipelines

A single `run_pipeline` call can chain steps, pass results between
them, and map a block over a list:

```json
[
  {"block": "find_files", "args": {"folder": "/path", "pattern": "*.epub"}, "save_as": "found"},
  {"block": "file_hash", "for_each": "@found.paths", "item_arg": "path"}
]
```

See `.claude/skills/rigid-pipeline/SKILL.md` for the full tool catalog
and pipeline mechanics (`save_as`/`for_each`/`item_arg`/`@refs`).

### Safety

Anything that writes or deletes (`write_file`, `execute_op`,
`db_execute`) requires `confirm="EXECUTE"` and logs what it did.
Nothing runs destructively by default.

### Status

Personal project, evolving. No license file yet — ask before reusing
outside personal/reference purposes.

---

## Polski

Lokalny serwer MCP z wielokrotnego użytku "klockami" do operacji na
plikach, metadanych dokumentów, analizy folderów, zapytań do lokalnego
modelu i CRUD na SQLite — wołanymi pojedynczo jako zwykłe narzędzia
MCP, albo składanymi w jedno wywołanie przez `run_pipeline`.

### Architektura

`gateway.py` montuje pięć niezależnych sub-serwerów `FastMCP` w jednym
procesie:

| Sub-serwer | Narzędzia | Namespace |
|---|---|---|
| file-ops | find/read/write/hash plików, preview/execute delete i move | `files_*` |
| metadata | metadane epub / audio+m4b / PDF / DOCX | `meta_*` |
| analysis | skład folderu wg rozszerzeń + drzewo | `fs_*` |
| llm | zapytania do lokalnego modelu przez LM Studio (OpenAI-compatible) | `llm_*` |
| sql | schema/query/execute na SQLite | `db_*` |
| orchestrator | `run_pipeline` — składa dowolne z powyższych w jednym wywołaniu | — |

### Uruchomienie

```bash
uv sync
uv run fastmcp dev inspector gateway.py   # test interaktywny
```

Podłącz dowolnego klienta MCP do `gateway.py` przez stdio do realnego użytku.

### Składanie pipeline'ów

Jedno wywołanie `run_pipeline` może połączyć kroki, przekazać wyniki
między nimi, i zmapować klocek po liście:

```json
[
  {"block": "find_files", "args": {"folder": "/sciezka", "pattern": "*.epub"}, "save_as": "found"},
  {"block": "file_hash", "for_each": "@found.paths", "item_arg": "path"}
]
```

Pełny katalog narzędzi i mechanika pipeline'u (`save_as`/`for_each`/
`item_arg`/`@refs`) — w `.claude/skills/rigid-pipeline/SKILL.md`.

### Bezpieczeństwo

Wszystko co zapisuje albo usuwa (`write_file`, `execute_op`,
`db_execute`) wymaga `confirm="EXECUTE"` i loguje co zrobiło. Nic nie
działa destrukcyjnie domyślnie.

### Status

Projekt osobisty, w rozwoju. Brak jeszcze pliku licencji — zapytaj
przed użyciem poza celami osobistymi/referencyjnymi.

### Historia

Powstało jako port istniejących skryptów (`rigid-pipeline/pipeline/`,
`mcp_cleaning_tool`) na architekturę MCP — logika ekstrakcji metadanych,
hashowania i czyszczenia sidecarów pochodzi stamtąd 1:1, zmieniła się
tylko warstwa podłączenia.