llm-wiki-kiss

Un wiki KISS self-hosted per agenti AI — file Markdown su filesystem, accesso uniforme via MCP (stdio) e fallback REST/HTTP opzionale. Stesso contenuto, qualunque sia l'agente: Claude Code, Open Cloud, Perplexity, script Python, browser.

Perché

Le conoscenze condivise tra agenti AI oggi vivono sparse: in tool, in notebook, in conversazioni che si perdono. Questo progetto offre una base di conoscenza persistente, portabile e controllabile al 100%:

• 📁 File .md o .html leggibili con qualsiasi editor

• 🧠 Un server MCP standardizzato che qualunque agente può usare

• 🌐 Una REST API minimale come fallback per i client che non supportano MCP

• 🪶 Nessun database, nessun CMS, versionamento con Git

• 🔌 Funziona ovunque: locale, server privato, container, Codespace

Related MCP server: kiwiki

Indice

• Caratteristiche

• Architettura

• Quick start (5 minuti)

• Installazione manuale

• I 5 tool MCP

• API REST

• Configurazione del client MCP

• Skill per agenti

• Script di gestione

• Test e qualità

• Struttura del wiki

• Filosofia

• Licenza

Caratteristiche

• Storage filesystem: una cartella con file Markdown e link relativi.

• Server MCP stdio con cinque tool: list_pages, read_page, search, write_page, append_note.

• Server MCP Streamable HTTP (MCP 2025) per client cloud con autenticazione Bearer.

• API REST FastAPI specchio dei tool MCP, con OpenAPI su /docs.

• Sicurezza base: validazione percorsi (no .., no NUL), limite 2 MiB per pagina, scope limitato alla root del wiki.

• Skill SKILL.md pronte per essere caricate da agenti compatibili (TRAE, Claude Code, …).

• Script shell che gestiscono venv, dipendenze, port checking, pid e log.

Architettura

llm-wiki-kiss/
├── wiki/                  # dati Markdown (il tuo wiki)
│   ├── index.md
│   ├── projects/  notes/  decisions/  references/  assets/  logs/
├── wiki_core/             # logica filesystem (WikiStorage, validazione, search)
├── mcp_server/            # server MCP stdio + Streamable HTTP (5 tool)
├── rest_api.py            # fallback HTTP FastAPI
├── scripts/               # wrapper shell (setup, start, stop, status, deploy)
├── tests/                 # pytest + smoke test MCP via stdio e HTTP
├── .trae/skills/          # SKILL.md per agenti AI
├── pyproject.toml, requirements*.txt, .env.example, .gitignore
├── LICENSE                # MIT
└── README.md

Quick start (5 minuti)

Prerequisito: Python 3.10+.

# 1. Clona e configura
git clone https://github.com/hor-net/llm-wiki-kiss.git
cd llm-wiki-kiss

# 2. Crea venv e installa dipendenze (+ dev)
scripts/setup.sh --with-dev

# 3. Avvia la REST API (default: 127.0.0.1:8765)
scripts/start-rest.sh

# 4. Verifica
scripts/status.sh
curl http://127.0.0.1:8765/health
open http://127.0.0.1:8765/docs

Per integrare con Claude Code / Claude Desktop / Open Cloud / Perplexity:

scripts/install-mcp-client.sh --client claude-code

Copia l'output nel file di configurazione del tuo client e riavvialo.

Installazione manuale

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt    # + requirements-dev.txt per dev

I 5 tool MCP

Tutti i percorsi sono relativi alla root del wiki e separati da /.

Esempi rapidi

// list_pages
{ "subdir": "notes" }

// read_page
{ "path": "notes/esempio-nota.md" }

// search
{ "query": "MCP", "max_results": 20 }

// write_page
{ "path": "notes/idea.md", "content": "# Idea\n\n...", "overwrite": false }

// append_note (path opzionale: default = log del giorno)
{ "content": "Refactor iniziato.", "heading": "Refactor" }

API REST

MCP Streamable HTTP (per client cloud)

Il server MCP è esposto anche via HTTPS con il nuovo trasporto Streamable HTTP (MCP 2025-06-18), così client MCP-aware in cloud (Open Cloud aggiornato, ecc.) possono usarlo senza lanciare un sottoprocesso.

# Avvio con autenticazione Bearer
WIKI_MCP_TOKEN='segreto-casuale-lungo' \
    scripts/start-mcp-http.sh --host 127.0.0.1 --port 8766

Il client si connette a http://127.0.0.1:8766/mcp con:

POST /mcp
Authorization: Bearer segreto-casuale-lungo
Accept: application/json, text/event-stream
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Esponi su HTTPS pubblico con un reverse proxy (Apache, nginx, Caddy) e Let's Encrypt. Lo script scripts/start-mcp-http.sh accetta --stateless/--stateful e --json-response/--no-json-response per modulare il comportamento.

Configurazione del client MCP

Esempio di frammento per Claude Code / Claude Desktop / Open Cloud / Perplexity (generato da scripts/install-mcp-client.sh):

{
  "mcpServers": {
    "wiki-kiss": {
      "command": "/percorso/al/progetto/.venv/bin/python",
      "args": ["-m", "mcp_server", "--root", "/percorso/al/progetto/wiki"],
      "cwd": "/percorso/al/progetto",
      "env": {
        "WIKI_ROOT": "/percorso/al/progetto/wiki",
        "WIKI_LOG_LEVEL": "INFO"
      }
    }
  }
}

Dopo la configurazione, riavvia il client perché ricarichi l'elenco dei server MCP.

Skill per agenti

In .trae/skills/ trovi due skill SKILL.md pronte per essere caricate da TRAE, Claude Code e altri agenti compatibili:

Copia le cartelle in ~/.claude/skills/ (o nel percorso previsto dal tuo client) per usarle localmente.

Script di gestione

Tutti accettano --help. I log vanno in var/log/, i PID in var/run/.

Variabili d'ambiente riconosciute: WIKI_ROOT, WIKI_LOG_LEVEL, DEFAULT_HOST, DEFAULT_PORT, NO_COLOR. Possono essere salvate in .env o .wiki-kiss.env (auto-caricati).

Test e qualità

scripts/run-tests.sh -q
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_mcp.py       # smoke test MCP stdio
.venv/bin/python tests/smoke_mcp_http.py  # smoke test MCP Streamable HTTP
.venv/bin/ruff check wiki_core mcp_server rest_api.py tests

Struttura del wiki

Esempio di organizzazione della cartella wiki/:

wiki/
├── index.md
├── projects/         # documentazione di progetto
├── notes/            # appunti, idee, osservazioni
├── decisions/        # ADR (NNNN-titolo.md)
├── references/       # link e fonti esterne
├── assets/           # immagini, allegati
└── logs/             # log append-only (YYYY-MM-DD.md)

Convenzioni:

• File in Markdown puro, UTF-8.

• Nomi in kebab-case.

• Ogni pagina inizia con un titolo di primo livello (# Titolo).

• Link interni relativi: [altra pagina](../notes/idea.md).

• Nessun frontmatter obbligatorio: solo se serve metadata reale.

Filosofia

KISS prima di tutto.

• Il wiki conserva conoscenza stabile: decisioni, progetti, riferimenti.

• La memoria conversazionale è gestita a parte (es. QMD): serve per il contesto dinamico e di breve durata, non per la conoscenza di lungo periodo.

• MCP rende quella conoscenza accessibile a tutti gli agenti: un solo contratto, infinite integrazioni.

• Niente database: tar czf wiki-$(date +%F).tgz wiki/ è il backup.

• Niente lock-in: tutto è testo, tutto è versionabile con Git.

Vantaggi e limiti

Vantaggi: controllo totale, backup banale, migrazione immediata, debug semplice, compatibilità con più agenti AI, crescita per gradi.

Limiti: nessun backlink automatico, nessun database nativo, nessuna UI ricca. La qualità dipende dalla disciplina nella scrittura e nelle convenzioni di naming.

Contribuire

Issue e PR benvenuti. Linee guida:

• Codice in stile ruff (configurato in pyproject.toml).

• Test obbligatori per le modifiche al core (wiki_core).

• Stile del wiki: ADR in decisions/, regole di naming in wiki/decisions/0001-storage-filesystem.md.

Licenza

MIT — Copyright (c) 2026 Hornet SRL.

Crediti

Progetto ispirato al paper del Model Context Protocol (https://modelcontextprotocol.io) e alla filosofia Unix "do one thing and do it well".