⚠️ Notă:
✨ Proiect 100% AI‑powered 🪄 — concept, analiză, cod, testare, documentație — cu omul 👨‍💻 în buclă ca big boss 👨‍💼 pentru control, fine‑tuning și decizii 🤔😉🤫.

Manual de Utilizare și Referință Tehnică: Fossil SCM MCP (FossilSoloMCP)

Server Model Context Protocol (MCP) de nivel profesional pentru integrarea completă a sistemului de control al versiunilor Fossil SCM cu asistenți AI și medii moderne de dezvoltare.

1. Introducere & Filosofia Proiectului

Ce este Fossil SCM?

Fossil este un sistem distribuit de control al versiunilor creat de D. Richard Hipp (autorul bazei de date SQLite). Spre deosebire de alte sisteme (precum Git), Fossil include nativ într-un singur executabil compact și autonom:

Controlul versiunilor arborelui de fișiere (Version Control).
Sistem integrat de urmărire a sarcinilor și erorilor (Bug & Task Ticketing).
Enciclopedie de proiect distribuită (Sistem Wiki încorporat).
Interfață web grafică completă (fossil ui / fossil server), accesibilă instantaneu din browser.
Format unic de stocare: Întregul depozit, istoricul complet, tichetele și paginile wiki sunt stocate fizic într-un singur fișier bază de date SQLite (.fossil).

De ce Fossil pentru dezvoltarea solo Om + AI?

În mediile de lucru moderne în care un dezvoltator colaborează strâns cu asistenți AI (cum ar fi agenții din Google Antigravity, Claude Desktop, Cursor, Continue etc.), Fossil oferă avantaje decisive:

Zero dependențe de infrastructură externă: Nu este nevoie de conturi cloud, chei API pentru servicii terțe, token-uri externe sau servere de baze de date. Totul este 100% local, privat și autonom pe calculatorul tău.
Memorie persistentă nativă pentru AI: Sistemul Wiki și Ticketing-ul integrate direct în depozit permit agentului AI să citească și să consemneze starea proiectului, deciziile arhitecturale și istoricul problemelor fără a polua directorul de cod sursă.
Integritate tranzacțională atomică: Datorită motorului SQLite intern, tranzacțiile sunt atomice, consistente și sigure împotriva întreruperilor accidentale de alimentare sau crash-urilor de proces.

Ideal și pentru Echipe Mici (Fără Complexitatea Git-ului)

Deși este optimizat pentru lucrul solo asistat de AI, Fossil este o alegere excepțională și pentru echipe mici (2–10 colaboratori) care își doresc simplitate, claritate și vor să evite birocrația și complexitatea adesea copleșitoare a Git-ului:

Soluție completă „All-in-One”: Într-o echipă mică, configurarea și întreținerea separată a unor servicii precum GitHub/GitLab, Jira/Trello (task tracking), Confluence/Notion (documentație wiki) sau servere de forum consumă timp și resurse nejustificate. Fossil include toate aceste unelte nativ, legate organic de fiecare commit și stocate în același depozit SQLite.
Eliminarea „ceremoniilor” complexe din Git: Concepte precum detached HEAD, zona de staging (index) separată, rezolvări confuze de rebase interactiv, comenzi periculoase de force push sau pierderea commit-urilor orfane sunt absente sau simplificate radical în Fossil. Istoricul în Fossil este conceput pentru a fi trasabil, curat și fără surprize.
Mecanismul nativ de Autosync: Fossil dispune de modul autosync activat implicit. La fiecare commit sau update, depozitul se sincronizează automat cu depozitul central dacă acesta este configurat, eliminând rutina clasică repetitivă de git fetch -> git stash -> git rebase -> git stash pop -> git push.
Server Web încorporat fără configurare: Orice membru al echipei poate lansa instantaneu fossil server pe o mașină din rețeaua locală sau pe un VPS modest. Întreaga echipă beneficiază pe loc de o interfață web completă și securizată (cu utilizatori, permisiuni pe roluri, code review, tichete și pagini wiki), fără să fie nevoie de Nginx, Docker sau baze de date externe.

Rolul serverului FossilSoloMCP

Acest server MCP acționează ca o punte de comunicație de mare viteză între modelele LLM și depozitele Fossil, expunând 29 de unelte specializate prin protocolul standardizat MCP (Model Context Protocol).

2. Istoric, Origine și Comparație cu `agent-vc-mcp`

Punctul de Plecare: `agent-vc-mcp`

Dezvoltarea acestui server a pornit inițial de la explorarea proiectului open-source agent-vc-mcp (creat de ManBotHQ pe GitHub), o primă încercare de a oferi un server MCP pentru Fossil scris în TypeScript / Node.js.

Deși conceptul de a oferi asistenților AI control asupra unui sistem de versionare a fost excelent, analiza codului sursă a scos la iveală limitări arhitecturale majore:

Limitări Majore ale `agent-vc-mcp`:

Model Sandbox Forțat și Rigid:
- agent-vc-mcp impunea un spațiu de lucru unic fix în ~/.agent-vc/workspace/ și o singură bază de date ~/.agent-vc/version_control.fossil.
- Proiectele erau tratate forțat doar ca subfoldere (workspace/proiect-1/, workspace/proiect-2/) în interiorul aceluiași repository masiv. Nu exista posibilitatea de a gestiona depozite independente pentru proiectele reale deja existente pe disc.
Duplicarea Inutilă a Operațiunilor pe Fișiere:
- agent-vc-mcp amesteca versionarea cu operațiuni elementare de sistem de fișiere (write_file, read_file, list_files). Acestea erau redundante și intrau adesea în conflict cu uneltele native și avansate de fișiere deja puse la dispoziție de IDE-uri și asistenți AI.
Set Foarte Limitat de Unelte (Exact 10 unelte):
- Oferă doar funcționalități rudimentare: vc_init_project, vc_commit, vc_status, vc_diff, cele 3 unelte de fișiere și un modul simplist de task-uri (task_create, task_update, task_list).
- Lipsuri critice: Fără suport de ramuri (branch), fără etichete (tag), fără stash, fără inspecție granulară a istoricului pe fișiere (finfo), fără posibilitatea de a citi conținut istoric (cat), fără anulare sigură (undo, revert), fără configurare depozit (settings) și fără niciun suport pentru sistemul Wiki!
Instabilitate și Blocaje Frecvente pe Windows:
- Funcția de lansare a proceselor folosea spawn fără timeout și fără închiderea/redirecționarea intrării standard (stdin). Dacă fossil.exe solicita vreo confirmare interactivă (de exemplu pentru fișiere binare noi sau avertismente CRLF), procesul se bloca la infinit (hang).
- Comanda de configurare a crlf-glob * eșua din cauza expandării wildcard-urilor de către runtime-ul Windows.
Lipsa Flexibilității CWD Dinamic:
- Calea spațiului de lucru era determinată static la lansarea serverului (prin variabila de mediu AGENT_VC_WORKSPACE). Nicio unealtă nu accepta un parametru de cale, astfel încât serverul nu putea opera dinamic pe multiple proiecte.
Ecosistemul Node.js / TypeScript:
- Necesita Node.js, npx și pachete node_modules voluminoase, complicând integrarea într-un mediu bazat pe Python și automatizări AI.

Trecerea la `FossilSoloMCP`: Rescriere și Maturizare

S-a luat decizia strategică de a rescrie serverul complet de la zero în Python, folosind framework-ul performant FastMCP.

Caracteristică	`agent-vc-mcp` (Original)	`FossilSoloMCP` (Proiectul Curent)
Limbaj & Runtime	TypeScript / Node.js (`npx`)	Python 3.14+ (FastMCP) gestionat ultrarapid prin `uv`
Număr Unelte Expuse	Exact 10 unelte	29 de unelte complete și specializate
Gestiune Directoare (CWD)	Static, fixat la pornire via env vars	Dinamic per apel (`cwd`) pe toate cele 29 de unelte
Organizare Depozite	Un singur repo comun în `~/.agent-vc/`	Repozitorii independente, stocate curat în `.fossil_repositories/`
Operațiuni pe Fișiere	Forța wrapper-e rigide (`write_file`, etc.)	Decuplat total: se bazează pe uneltele native ale agentului
Inspecție Istorică Avansată	Niciuna (doar `vc_diff` global)	`fossil_timeline` (cu filtre), `fossil_finfo`, `fossil_cat` istoric
Ramuri & Etichete	Inexistente	Suport complet (`fossil_branch`, `fossil_tag`)
Stashing & Revert	Inexistente	Gestiune completă (`fossil_stash`, `fossil_revert`, `fossil_undo`)
Sistem Wiki (Memorie AI)	Inexistent	Integrat (`fossil_wiki_ls`, `wiki_read`, `wiki_write`)
Sistem Ticketing	Modul proprietar simplist	Integrat nativ Fossil cu fallback inteligent SQL
Reziliență Windows & Anti-Hang	Blocaje frecvente în consolă	`stdin=DEVNULL`, auto-răspuns `a` la prompturi, timeout 30s
Gestiune CRLF / LF	Erori la comanda de setare	Injecție SQL directă în SQLite + auto-generare `.editorconfig`

3. Prerechizite și Instalare

1. Prerechizite Sistem

Utilitarul Fossil SCM:
- Descărcați executabilul oficial pentru sistemul dvs. de operare (Windows, Linux sau macOS) de la https://fossil-scm.org/.
- Amplasați executabilul într-un director din sistem (de exemplu C:\Program Files\Fossil\ pe Windows sau /usr/local/bin/ pe Linux/macOS).
- Asigurați-vă că directorul respectiv este inclus în variabila de mediu PATH.
- Verificați disponibilitatea în consolă:
```
fossil version
```
Python & uv:
- Se recomandă Python 3.14 sau mai nou.
- Managerul modern de medii și pachete uv instalat în sistem (sau mediul Python standard).

2. Configurare în Clienți MCP

Configurarea se realizează prin adăugarea definiției serverului în fișierul de configurare al clientului MCP dorit (mcp_config.json, claude_desktop_config.json, etc.).

Exemplu Universal pentru Windows:

{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Cale/Catre/FossilSoloMCP",
        "fossil-scm-mcp"
      ]
    }
  }
}

Exemplu Universal pentru Linux / macOS:

{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/utilizator/proiecte/FossilSoloMCP",
        "fossil-scm-mcp"
      ]
    }
  }
}

Tip

Înlocuiți calea: Înlocuiți "C:/Cale/Catre/FossilSoloMCP" sau "/home/utilizator/proiecte/FossilSoloMCP" cu calea absolută reală unde ați clonat sau salvat proiectul pe calculatorul dvs.

Despre argumentul --repository: Serverul funcționează complet dinamic pe baza parametrului cwd transmis la fiecare apel de unealtă. Prin urmare, nu este necesar să specificați un depozit static la pornirea serverului.

4. Arhitectura și Organizarea Depozitelor

Convenția `.fossil_repositories`

Pentru a păstra rădăcina proiectelor curată și pentru a evita stocarea de baze de date voluminoase în interiorul directorului de lucru, serverul implementează automat o convenție curată:

Baza de Date a Depozitului (.fossil):
- Este salvată într-un director ascuns .fossil_repositories/ creat automat în folderul părinte al spațiului de lucru (de exemplu: ../.fossil_repositories/NumeProiect.fossil).
Directorul de Lucru (Checkout):
- Conține codul sursă, documentația și fișierul ascuns de legătură al Fossil denumit _FOSSIL_ (pe Windows) sau .fslckout (pe Linux/macOS).
- Acest fișier conține calea către baza de date SQLite a depozitului asociat.

Deschiderea Interfeței Grafice Web

Fossil include nativ un server HTTP și o interfață web completă. Pentru a explora depozitul vizual în browser, este suficient să rulați în terminalul deschis în directorul proiectului:

fossil ui

(Opțional, pe Windows, puteți rula scriptul utilitar open-ui-fossil.bat inclus în rădăcină).

Comanda deschide automat browserul implicit la adresa http://localhost:8080, oferind acces la:

Timeline: Arborele grafic al tuturor ramurilor, tag-urilor și commit-urilor.
Files: Navigare prin fișiere la orice revizie istorică, cu diff-uri și adnotare (blame).
Tickets: Vizualizarea și editarea sarcinilor și bug-urilor.
Wiki: Navigarea prin articolele și documentația proiectului.

5. Ghid de Lucru pentru Agenți AI (Fluxuri Universale Recomandate)

Important

Regula de Aur pentru Agenți: La apelarea oricărui tool din serverul fossil-scm, includeți întotdeauna parametrul cwd setat explicit la calea absolută a directorului pe care operați (de exemplu: cwd="C:/Proiecte/AplicatiaMea").

Regulă Recomandată pentru Agentul AI (System Prompt / Reguli de lucru)

Dacă doriți ca asistentul dvs. AI să folosească automat și corect serverul Fossil în orice client (Claude Desktop, Cursor, Antigravity etc.), puteți adăuga următoarea regulă în instrucțiunile de sistem:

Pentru versionare, tichete și documentație internă, folosește uneltele serverului MCP fossil-scm.
La orice apel, transmite întotdeauna parametrul 'cwd' setat la calea directorului proiectului curent.
Înainte de a face modificări, verifică starea cu fossil_status. La finalul fiecărei sarcini rezolvate,
înregistrează fișierele cu fossil_add și comite modificările cu fossil_commit oferind un mesaj clar.

Fluxul 1: Inițializarea unui Proiect Nou

Când utilizatorul cere începerea unui proiect nou cu versionare Fossil:

Agentul apelează fossil_init:
```
{
  "project_name": "AplicatiaMea",
  "cwd": "C:/Proiecte/AplicatiaMea"
}
```
Ce face serverul automat:
- Creează directorul .fossil_repositories/ în folderul părinte dacă nu există.
- Inițializează AplicatiaMea.fossil.
- Deschide depozitul în folderul de lucru (fossil open).
- Aplică setările automate anti-CRLF direct în SQL (crlf-glob = *).
- Generează automat fișierul .editorconfig (end_of_line = lf) și îl adaugă în versionare.

Fluxul 2: Ciclul Standard de Modificare și Commit

Pe parcursul dezvoltării sau depanării, agentul urmează un ciclu standard:

Verifică starea fișierelor: fossil_status(cwd="...")
Inspectează modificările concrete (diff): fossil_diff(cwd="...")
Înregistrează fișierele noi:
- Pentru fișiere punctuale: fossil_add(files=["src/main.py"], cwd="...")
- Pentru sincronizare automată (fișiere noi și șterse): fossil_addremove(cwd="...")
Comiterea în depozit: fossil_commit(message="Implementare modul autentificare", cwd="...") (Serverul rezolvă automat fără blocaje orice prompt de confirmare).

Fluxul 3: Explorare Istorică și Investigare Fără Risc

Spre deosebire de alte sisteme unde agentul riscă să suprascrie spațiul de lucru când vrea să consulte codul din trecut:

fossil_timeline: Afișează istoricul recent al evenimentelor. Suportă filtrarea doar pe un anumit fișier (path="src/main.py").
fossil_finfo: Afișează toate modificările suferite de-a lungul timpului de un singur fișier specificat.
fossil_cat (Arma secretă): Permite citirea conținutului unui fișier direct dintr-o revizie istorică sau tag, fără a atinge sau deranja fișierele de pe disc din spațiul de lucru curent:
```
{
  "file": "src/main.py",
  "revision": "f731ad3851",
  "cwd": "..."
}
```

Fluxul 4: Gestiunea Sarcinilor (Ticketing)

Fossil are un sistem complet de ticketing stocat în baza de date:

Listare tichete existente: fossil_ticket_list(cwd="...")

Creare sarcină nouă / raport de bug:

{
  "title": "Remediere eroare de timeout la apeluri asincrone",
  "status": "open",
  "additional_fields": {
    "type": "Code_Defect",
    "severity": "High"
  },
  "cwd": "..."
}

Închidere sau actualizare tichet:

{
  "ticket_id": "a1b2c3d4",
  "field_name": "status",
  "field_value": "closed",
  "cwd": "..."
}

Fluxul 5: Documentație ca Memorie Persistentă (Wiki)

Paginile Wiki din Fossil sunt stocate direct în depozit și nu depind de fișiere de pe disc:

Listare pagini existente: fossil_wiki_ls(cwd="...")
Citire documentație: fossil_wiki_read(page_name="ArhitecturaSistemului", cwd="...")
Salvare decizii tehnice pentru sesiunile viitoare: fossil_wiki_write(page_name="DeciziiDesign", content="# Decizii...", cwd="...")

6. Referința Completă a Celor 29 de Instrumente MCP

A. Version Control (20 Instrumente)

1. `fossil_status`

Descriere: Afișează starea curentă a fișierelor din spațiul de lucru (modificate, adăugate, lipsă, fișiere netrackuite).
Parametri:
- cwd (string, opțional): Calea directorului de lucru.
- dotfiles (boolean, default: false): Dacă include fișierele/folderele ascunse (care încep cu punct).
- brief (boolean, default: false): Afișare concisă doar cu cuvinte cheie.
- ignore (string, opțional): Tipare glob separate prin virgulă pentru fișiere de ignorat.

2. `fossil_diff`

Descriere: Afișează diferențele de cod (diff) între modificările din spațiul de lucru și depozit sau între revizii istorice.
Parametri:
- cwd (string, opțional): Directorul de lucru.
- files (array de string-uri, opțional): Listă specifică de fișiere de comparat.
- from_version (string, opțional): Revizia de pornire (--from).
- to_version (string, opțional): Revizia de destinație (--to).
- branch (string, opțional): Compară modificările ramurii specificate.
- brief (boolean, default: false): Listează doar numele fișierelor modificate fără diff-ul complet.
- ignore_whitespace (boolean, default: false): Ignoră modificările cauzate de spații/taburi (-w).

3. `fossil_cat`

Descriere: Extrage și returnează conținutul textual al unui fișier dintr-o revizie istorică specificată, fără a modifica spațiul de lucru local.
Parametri:
- file (string, obligatoriu): Calea relativă a fișierului.
- revision (string, obligatoriu): Hash-ul, eticheta sau ramura reviziei dorite.
- cwd (string, opțional): Directorul de lucru.

4. `fossil_finfo`

Descriere: Returnează istoricul detaliat de modificări pentru un singur fișier specificat. Traversează transparent evenimentele de redenumire efectuate cu fossil_mv.
Parametri:
- file (string, obligatoriu): Calea fișierului.
- limit (integer, opțional): Numărul maxim de revizii afișate (-n).
- cwd (string, opțional): Directorul de lucru.

5. `fossil_add`

Descriere: Programează adăugarea unuia sau mai multor fișiere/directoare în versionare.
Parametri:
- files (array de string-uri, obligatoriu): Lista de căi către fișiere sau directoare.
- force (boolean, default: true): Forțează adăugarea chiar dacă se potrivesc cu un tipar ignore-glob.
- dotfiles (boolean, default: false): Include fișiere ascunse la parcurgere recursivă.
- cwd (string, opțional): Directorul de lucru.

6. `fossil_rm`

Descriere: Elimină fișiere din controlul versiunilor.
Parametri:
- files (array de string-uri, obligatoriu): Lista fișierelor de eliminat.
- force (boolean, default: false): Forțează ștergerea fără avertismente.
- keep (boolean, default: false): Păstrează fișierele fizic pe disc, eliminându-le doar din versionare.
- cwd (string, opțional): Directorul de lucru.

7. `fossil_mv`

Descriere: Redenumește sau mută un fișier ori director în depozit și pe disc. Înregistrează explicit evenimentul RENAME în graful de versiuni (DAG), asigurând trasabilitatea completă a istoricului prin fossil_finfo.
Parametri:
- old_name (string, obligatoriu): Calea sursă a fișierului sau directorului.
- new_name (string, obligatoriu): Calea destinație a fișierului sau directorului.
- hard (boolean, default: true): Dacă mută/redenumește fișierul fizic pe disc (--hard). Dacă este False, înregistrează doar intenția în manifest (--soft).
- case_sensitive (boolean, opțional): Forțează respectarea majusculelor/minusculelor (--case-sensitive 1/0).
- cwd (string, opțional): Directorul de lucru.

8. `fossil_addremove`

Descriere: Scanează spațiul de lucru și adaugă automat fișierele noi, eliminându-le pe cele șterse de pe disc.
Parametri:
- dotfiles (boolean, default: false): Include dotfiles.
- ignore (string, opțional): Tipare glob de ignorat.
- clean (boolean, default: false): Șterge fișierele suplimentare netrackuite.
- reset (boolean, default: false): Resetează starea add/remove.
- cwd (string, opțional): Directorul de lucru.

9. `fossil_extras`

Descriere: Listează toate fișierele din directorul curent care nu sunt sub controlul versiunilor.
Parametri:
- dotfiles (boolean, default: false): Include fișierele ascunse.
- ignore (string, opțional): Filtru glob suplimentar.
- cwd (string, opțional): Directorul de lucru.

10. `fossil_clean`

Descriere: Șterge fișierele netrackate și temporare din arborele de lucru (fossil clean).
Parametri:
- all_files (boolean, default: false): Forțează ștergerea fără confirmare interactivă (-f).
- dry_run (boolean, default: false): Simulare fără ștergere; afișează lista fișierelor care ar fi eliminate (-n).
- cwd (string, opțional): Directorul de lucru.

11. `fossil_revert`

Descriere: Anulează modificările nesalvate dintr-unul sau mai multe fișiere, readucându-le la starea din depozit.
Parametri:
- files (array de string-uri, obligatoriu): Fișierele de readus la starea inițială.
- revision (string, opțional): Revizia la care să fie readuse (implicit checkout-ul curent).
- cwd (string, opțional): Directorul de lucru.

12. `fossil_stash`

Descriere: Salvează temporar modificările locale nesalvate pentru a lăsa spațiul curat, permițând reaplicarea lor ulterioară.
Parametri:
- action (string, default: "save"): Acțiunea dorită: "save", "snapshot", "list", "pop", "apply", "drop", "diff".
- comment (string, opțional): Notiță pentru stash.
- stash_id (integer, opțional): Numărul de identificare al stash-ului.
- cwd (string, opțional): Directorul de lucru.

13. `fossil_tag`

Descriere: Gestionează etichete simbolice asociate anumitor revizii (check-in-uri).
Parametri:
- action (string, default: "list"): "add", "cancel", "list".
- tag_name (string, opțional): Numele etichetei (ex: "v1.0.0").
- checkin (string, opțional): Revizia căreia i se atașează tag-ul.
- cwd (string, opțional): Directorul de lucru.

14. `fossil_commit`

Descriere: Înregistrează definitiv modificările într-un nou check-in în depozit.
Parametri:
- message (string, obligatoriu): Mesajul de commit.
- files (array de string-uri, opțional): Fișiere specifice de inclus în commit.
- branch (string, opțional): Numele unei ramuri noi pe care să fie plasat commit-ul (--branch).
- no_warnings (boolean, default: true): Omite avertismentele de conținut și CRLF.
- allow_empty (boolean, default: false): Permite commit chiar dacă nu există modificări.
- user_override (string, opțional): Înregistrează un alt nume de autor.
- cwd (string, opțional): Directorul de lucru.

15. `fossil_timeline`

Descriere: Afișează istoricul cronologic al acțiunilor și commit-urilor din proiect.
Parametri:
- limit (integer, default: 20): Numărul de evenimente afișate.
- path (string, opțional): Filtrează timeline-ul doar pentru un anumit fișier/director (-p).
- type_filter (string, opțional): Filtru de tip: "ci" (checkins), "w" (wiki), "t" (tickets), "e" (events) (-t).
- cwd (string, opțional): Directorul de lucru.

16. `fossil_info`

Descriere: Afișează informații detaliate despre depozit, checkout-ul activ sau o revizie anume.
Parametri:
- target (string, opțional): Hash-ul, eticheta sau fișierul de inspectat.
- cwd (string, opțional): Directorul de lucru.

17. `fossil_branch`

Descriere: Gestionează ramurile de dezvoltare paralele.
Parametri:
- action (string, default: "list"): "list" sau "new".
- branch_name (string, opțional): Numele noii ramuri la action="new".
- basis (string, opțional): Punctul de plecare (check-in de bază).
- cwd (string, opțional): Directorul de lucru.

18. `fossil_merge`

Descriere: Fuzionează o altă ramură sau un commit specific în spațiul de lucru curent (fossil merge).
Parametri:
- branch_or_version (string, obligatoriu): Numele ramurii sau hash-ul commit-ului de integrat.
- integrate (boolean, default: false): Dacă este True (--integrate), închide automat ramura sursă după fuziune la următorul commit.
- dry_run (boolean, default: false): Simulează fuziunea fără a modifica fișierele locale (-n).
- cwd (string, opțional): Directorul de lucru.

19. `fossil_update`

Descriere: Actualizează fișierele din spațiul de lucru la cea mai recentă revizie sau comută pe o altă ramură/versiune.
Parametri:
- target (string, opțional): Versiunea, ramura sau eticheta către care se comută.
- cwd (string, opțional): Directorul de lucru.

20. `fossil_undo`

Descriere: Anulează ultima operațiune de update, revert sau merge efectuată în spațiul de lucru.
Parametri:
- dry_run (boolean, default: false): Afișează ce ar fi anulat fără a executa operațiunea.
- cwd (string, opțional): Directorul de lucru.

B. Administrare & Depozit (3 Instrumente)

21. `fossil_init`

Descriere: Creează și configurează o nouă bază de date Fossil și o deschide automat în directorul indicat.
Parametri:
- db_name (string, opțional): Numele fișierului depozitului (implicit numele folderului curent).
- project_name (string, opțional): Numele logic al proiectului.
- cwd (string, opțional): Directorul de lucru.

22. `fossil_open`

Descriere: Deschide un depozit Fossil existent în directorul specificat.
Parametri:
- db_name (string, obligatoriu): Numele sau calea depozitului .fossil.
- force (boolean, default: false): Forțează deschiderea chiar dacă directorul nu e gol (-f).
- keep (boolean, default: false): Păstrează fișierele locale existente (-k).
- cwd (string, opțional): Directorul de lucru.

23. `fossil_settings`

Descriere: Consultă sau modifică proprietățile și setările depozitului (crlf-glob, binary-glob, ignore-glob, autosync etc.).
Parametri:
- name (string, opțional): Numele proprietății (dacă lipsește, listează toate setările).
- value (string, opțional): Noua valoare de configurat.
- cwd (string, opțional): Directorul de lucru.

C. Sistemul de Ticketing (3 Instrumente)

24. `fossil_ticket_list`

Descriere: Listează tichetele existente în depozit (cu fallback automat pe interogare directă SQLite dacă rapoartele Fossil nu sunt configurate).
Parametri:
- report (integer, default: 1): Numărul raportului standard Fossil.
- cwd (string, opțional): Directorul de lucru.

25. `fossil_ticket_create`

Descriere: Deschide un tichet nou în sistemul de tracking al depozitului.
Parametri:
- title (string, obligatoriu): Titlul sau rezumatul sarcinii/erorii.
- status (string, default: "open"): Starea inițială ("open", "in_progress", "closed" etc.).
- additional_fields (dicționar / obiect JSON, opțional): Câmpuri adiționale (ex: type, severity, subsystem, description).
- cwd (string, opțional): Directorul de lucru.

26. `fossil_ticket_update`

Descriere: Modifică un câmp sau statusul unui tichet existent.
Parametri:
- ticket_id (string, obligatoriu): Identificatorul UUID al tichetului (sau primele caractere).
- field_name (string, obligatoriu): Numele câmpului de modificat (ex: "status", "comment").
- field_value (string, obligatoriu): Noua valoare atribuită câmpului.
- cwd (string, opțional): Directorul de lucru.

D. Sistemul Wiki (3 Instrumente)

27. `fossil_wiki_ls`

Descriere: Returnează lista tuturor paginilor wiki existente în depozit.
Parametri:
- cwd (string, opțional): Directorul de lucru.

28. `fossil_wiki_read`

Descriere: Citește și returnează conținutul complet în format text/markdown al paginii wiki solicitate.
Parametri:
- page_name (string, obligatoriu): Numele paginii wiki.
- cwd (string, opțional): Directorul de lucru.

29. `fossil_wiki_write`

Descriere: Creează o pagină wiki nouă sau actualizează conținutul unei pagini existente în depozit.
Parametri:
- page_name (string, obligatoriu): Numele paginii wiki.
- content (string, obligatoriu): Conținutul Markdown sau text al paginii.
- cwd (string, opțional): Directorul de lucru.

7. Particularități Windows & Soluții Tehnice Încorporate

Dezvoltarea pe sisteme de operare Windows ridică provocări particulare pentru utilitare portate din lumea UNIX. Serverul FossilSoloMCP include măsuri de reziliență construite special:

1. Problema Expandării Wildcard-urilor la `crlf-glob "*"`

Fenomenul: Pe Windows, runtime-ul MSVC/MinGW al fossil.exe expandează automat caracterele * înainte de funcția main(). Comanda fossil settings crlf-glob "*" ajungea la Fossil ca o listă cu toate fișierele din folder, declanșând erori de sintaxă.
Soluția: Serverul aplică setarea direct în baza de date a depozitului prin SQL nativ:
```
REPLACE INTO config(name,value) VALUES('crlf-glob','*')
```
Ocolind complet CLI-ul, configurarea este 100% sigură și atomică.

2. Păstrarea Standardului LF prin `.editorconfig`

Deși setarea crlf-glob = * dezactivează blocajele de commit, fișierele cu terminatori Windows (CRLF) pot genera diff-uri artificiale.
Serverul generează automat la fossil_open un fișier .editorconfig cu regula end_of_line = lf, asigurând ca editoarele de cod să salveze curat cu terminatori standardizați UNIX.

3. Protecție Anti-Hang și Timeout de Siguranță

Orice proces CLI apelat are stdin redirecționat către subprocess.DEVNULL când nu primește date explicite, prevenind blocarea la prompturi interactive.
La fossil_commit, serverul trimite automat răspunsul a\n pe intrarea standard pentru a valida prompturile legate de fișiere binare sau avertismente.
Toate apelurile de proces au timeout fixat la 30 de secunde, cu capturare completă de stderr și cod de retur pentru diagnosticare imediată.

8. Bune Practici & Sfaturi de Lucru

Commit-uri Atomice și Explicite:
- Efectuați commit-uri frecvente și concentrate după fiecare pas funcțional sau eroare remediată. Astfel, prin fossil_undo sau fossil_revert, puteți reveni oricând la un punct de stabilitate verificat.
Păstrarea Istoricului de Proiect în Wiki:
- Folosiți paginile Wiki (fossil_wiki_write) pentru a consemna concluzii de arhitectură sau instrucțiuni de deployment. Fiind stocate în baza .fossil, ele nu se pierd și sunt accesibile direct în browser prin fossil ui.
Optimizare Avansată: Lucrul pe RAM Disk (Opțional):
- Pentru dezvoltatorii care efectuează teste de anduranță, generare masivă de fișiere temporare sau rulare intensivă de scripturi scratch automate cu AI, utilizarea unui RAM Disk temporar este o modalitate excelentă de a proteja ciclurile de scriere ale SSD-urilor și de a obține viteze maxime de I/O. La finalizarea sesiunilor de lucru, modificările de cod validate pot fi sincronizate în directorul permanent al proiectului și salvate în depozit.
Automatizări Avansate cu Agenți AI:
- În funcție de clientul sau IDE-ul utilizat (de exemplu reguli de lucru în Google Antigravity, .cursorrules în Cursor sau System Prompts în Claude Desktop), puteți defini instrucțiuni standardizate pentru ca agentul să versioneze automat fiecare modificare importantă fără intervenție manuală repetată.

9. Licență & Declinarea Responsabilității (No Warranty)

📄 Licență

Acest proiect este licențiat sub termenii licenței MIT. Consultă fișierul LICENSE pentru detalii complete.

📝 Garanție

Nu se oferă absolut niciun fel de garanție!

⚠️ Note:
✨ 100% AI‑powered project 🪄 — concept, analysis, code, testing, documentation — with the human 👨‍💻 in the loop as the big boss 👨‍💼 for control, fine‑tuning, and decisions 🤔😉🤫.

User Manual & Technical Reference: Fossil SCM MCP (FossilSoloMCP)

Professional-grade Model Context Protocol (MCP) server for comprehensive integration of the Fossil SCM version control system with AI assistants and modern development environments.

1. Introduction & Project Philosophy

What is Fossil SCM?

Fossil is a distributed version control system created by D. Richard Hipp (author of the SQLite database engine). Unlike other systems (such as Git), Fossil includes natively within a single compact and self-contained executable:

File tree version control (Version Control).
Integrated bug and task tracking (Bug & Task Ticketing).
Distributed project encyclopedia (Built-in Wiki system).
Full-featured graphical web interface (fossil ui / fossil server), instantly accessible from any browser.
Single-file storage format: The entire repository, complete commit history, tickets, and wiki articles are stored physically inside a single SQLite database file (.fossil).

Why Fossil for Solo Human + AI Development?

In modern development workflows where a developer collaborates closely with AI assistants (such as agents in Google Antigravity, Claude Desktop, Cursor, Continue, etc.), Fossil provides decisive advantages:

Zero External Infrastructure Dependencies: No need for cloud accounts, third-party API keys, external tokens, or database servers. Everything is 100% local, private, and autonomous on your machine.
Native Persistent Memory for AI: The Wiki and Ticketing systems embedded directly inside the repository database allow the AI agent to read and record project status, architectural decisions, and bug history without polluting the source code directory.
Atomic Transactional Integrity: Powered by the SQLite engine, all operations are atomic, consistent, and resilient against accidental power failures or process crashes.

Ideal for Small Teams (Without Git's Complexity)

While optimized for solo AI-assisted development, Fossil is also an outstanding choice for small teams (2–10 collaborators) seeking simplicity, clarity, and the elimination of Git's frequently overwhelming bureaucracy:

Complete "All-in-One" Solution: In a small team, configuring and maintaining separate services such as GitHub/GitLab, Jira/Trello (task tracking), Confluence/Notion (wiki documentation), or forum servers consumes unnecessary time and resources. Fossil bundles all these tools natively, organically tied to each commit and stored in the same SQLite repository.
Elimination of Git's Complex "Ceremonies": Concepts like detached HEAD, a separate staging index, confusing interactive rebase conflicts, hazardous force push operations, or lost orphaned commits are either absent or radically simplified in Fossil. Fossil's history is designed to be traceable, clean, and free of surprises.
Native Autosync Mechanism: Fossil features autosync enabled by default. On every commit or update, the repository automatically synchronizes with the central repository if configured, eliminating the repetitive routine of git fetch -> git stash -> git rebase -> git stash pop -> git push.
Zero-Configuration Built-in Web Server: Any team member can instantly launch fossil server on a local network machine or a modest VPS. The entire team instantly benefits from a full, secure web interface (with users, role-based permissions, code review, ticketing, and wiki pages) without needing Nginx, Docker, or external databases.

The Role of the FossilSoloMCP Server

This MCP server acts as a high-speed communication bridge between Large Language Models (LLMs) and Fossil repositories, exposing 29 specialized tools via the standardized Model Context Protocol (MCP).

2. History, Origin, and Comparison with `agent-vc-mcp`

The Starting Point: `agent-vc-mcp`

The development of this server originally began with exploring the open-source project agent-vc-mcp (created by ManBotHQ on GitHub), an early attempt to provide an MCP server for Fossil written in TypeScript / Node.js.

While the concept of giving AI assistants control over a version control system was sound, source code analysis revealed severe architectural limitations:

Major Limitations of `agent-vc-mcp`:

Rigid, Enforced Sandbox Model:
- agent-vc-mcp forced a single fixed workspace at ~/.agent-vc/workspace/ and a single database at ~/.agent-vc/version_control.fossil.
- Projects were forcibly treated as mere subfolders (workspace/project-1/, workspace/project-2/) inside the same massive repository. There was no ability to manage independent repositories for actual projects already residing across the disk.
Redundant Duplication of Filesystem Operations:
- agent-vc-mcp intermingled version control with basic filesystem operations (write_file, read_file, list_files). These were redundant and frequently conflicted with native, advanced file tools already provided by IDEs and AI assistants.
Severely Limited Toolset (Exactly 10 Tools):
- It only offered rudimentary capabilities: vc_init_project, vc_commit, vc_status, vc_diff, 3 file tools, and a simplistic task module (task_create, task_update, task_list).
- Critical Omissions: No branch support (branch), no tags (tag), no stash, no granular per-file history inspection (finfo), no historical content extraction (cat), no safe undo (undo, revert), no repository configuration (settings), and zero support for the Wiki system!
Instability and Frequent Freezes on Windows:
- Process spawning used spawn without timeouts and without closing/redirecting standard input (stdin). Whenever fossil.exe requested interactive confirmation (e.g., for new binary files or CRLF line ending warnings), the process froze indefinitely (hung).
- The command setting crlf-glob * failed due to wildcard expansion by the Windows runtime.
Lack of Dynamic CWD Flexibility:
- The workspace path was determined statically at server startup (via the AGENT_VC_WORKSPACE environment variable). No tool accepted a path parameter, preventing the server from dynamically managing multiple projects.
Node.js / TypeScript Ecosystem Overhead:
- It required Node.js, npx, and bulky node_modules packages, complicating integration in environments built around Python and modern AI automation.

Transition to `FossilSoloMCP`: Complete Rewrite & Maturation

The strategic decision was made to rewrite the server entirely from scratch in Python, utilizing the high-performance FastMCP framework.

Feature / Aspect	`agent-vc-mcp` (Original)	`FossilSoloMCP` (Current Project)
Language & Runtime	TypeScript / Node.js (`npx`)	Python 3.14+ (FastMCP) managed ultrarapidly via `uv`
Number of Tools Exposed	Exactly 10 tools	29 complete, specialized tools
Directory Management (CWD)	Static, fixed at startup via env vars	Dynamic per call (`cwd`) across all 29 tools
Repository Organization	Single shared repo in `~/.agent-vc/`	Independent repositories, cleanly stored in `.fossil_repositories/`
File Operations	Forced rigid wrappers (`write_file`, etc.)	Completely decoupled: relies on agent's native file tools
Advanced History Inspection	None (only global `vc_diff`)	`fossil_timeline` (with filters), `fossil_finfo`, historical `fossil_cat`
Branches & Tags	Non-existent	Full support (`fossil_branch`, `fossil_tag`)
Stashing & Revert	Non-existent	Full management (`fossil_stash`, `fossil_revert`, `fossil_undo`)
Wiki System (AI Memory)	Non-existent	Fully integrated (`fossil_wiki_ls`, `wiki_read`, `wiki_write`)
Ticketing System	Simplistic proprietary module	Natively integrated Fossil ticketing with smart SQL fallback
Windows Resilience & Anti-Hang	Frequent console hangs/freezes	`stdin=DEVNULL`, auto-response `a` on prompts, 30s timeout
CRLF / LF Line Endings	Errors on setting command	Direct SQLite SQL injection + auto-generated `.editorconfig`

3. Prerequisites and Installation

1. System Prerequisites

Fossil SCM CLI Utility:
- Download the official precompiled binary for your operating system (Windows, Linux, or macOS) from https://fossil-scm.org/.
- Place the executable in a directory on your machine (e.g., C:\Program Files\Fossil\ on Windows or /usr/local/bin/ on Linux/macOS).
- Ensure the directory is added to your system's PATH environment variable.
- Verify availability in your terminal:
```
fossil version
```
Python & uv:
- Python 3.14 or newer is recommended.
- The modern Python package and project manager uv installed on your system (or standard Python).

2. Configuration in MCP Clients

Configuration is performed by adding the server definition to your MCP client's configuration file (mcp_config.json, claude_desktop_config.json, etc.).

Universal Configuration for Windows:

{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Path/To/FossilSoloMCP",
        "fossil-scm-mcp"
      ]
    }
  }
}

Universal Configuration for Linux / macOS:

{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/user/projects/FossilSoloMCP",
        "fossil-scm-mcp"
      ]
    }
  }
}

Tip

Path Replacement: Replace "C:/Path/To/FossilSoloMCP" or "/home/user/projects/FossilSoloMCP" with the actual absolute path where this repository is located on your machine.

Regarding the --repository Argument: The server operates fully dynamically based on the cwd parameter passed to each tool call. Therefore, specifying a static fallback repository at startup is optional.

4. Repository Architecture and Organization

The `.fossil_repositories` Convention

To keep project root directories tidy and prevent large database files from cluttering the working tree, the server automatically enforces a clean convention:

Repository Database (.fossil):
- Saved in a hidden directory .fossil_repositories/ automatically created in the parent folder of the workspace (e.g., ../.fossil_repositories/ProjectName.fossil).
Working Directory (Checkout):
- Contains source code, documentation, and Fossil's hidden checkout tracking file named _FOSSIL_ (on Windows) or .fslckout (on Linux/macOS).
- This file links the working directory to its associated SQLite repository database.

Opening the Graphical Web Interface

Fossil natively bundles an HTTP server and a rich web interface. To visually explore the repository in your browser, simply execute in your terminal inside the project directory:

fossil ui

(Optionally, on Windows, you can launch the convenience script open-ui-fossil.bat included in the root directory).

The command automatically opens your default browser at http://localhost:8080, providing instant visual access to:

Timeline: Interactive graphical DAG tree of all branches, tags, and commits.
Files: Historical file browser at any revision, with visual diffs and annotation (blame).
Tickets: Viewing, searching, and editing bug reports and tasks.
Wiki: Rich navigation and authoring of project articles and documentation.

5. AI Agent Workflow Guide (Recommended Universal Flows)

Important

Golden Rule for Agents: When calling any tool in the fossil-scm server, always provide the cwd parameter explicitly set to the absolute path of the directory you are operating on (e.g., cwd="C:/Projects/MyApp").

Recommended AI Agent Rule (System Prompt / Custom Instructions)

To enable your AI assistant to automatically and correctly utilize the Fossil MCP server across any client (Claude Desktop, Cursor, Antigravity, etc.), add the following instruction to your system prompt:

For version control, issue ticketing, and persistent documentation, use the fossil-scm MCP tools.
On every call, always pass the 'cwd' parameter set to the current project's absolute working directory.
Before making changes, verify status with fossil_status. Upon completing any task,
stage files with fossil_add and commit the changes with fossil_commit using a clear message.

Flow 1: Initializing a New Project

When a user requests creating a new project with Fossil version control:

The agent calls fossil_init:
```
{
  "project_name": "MyApp",
  "cwd": "C:/Projects/MyApp"
}
```
What the server does automatically:
- Creates the .fossil_repositories/ directory in the parent folder if not present.
- Initializes MyApp.fossil.
- Opens the repository in the working directory (fossil open).
- Applies anti-CRLF settings directly into SQLite SQL (crlf-glob = *).
- Automatically generates .editorconfig (end_of_line = lf) and tracks it in version control.

Flow 2: Standard Edit and Commit Cycle

During development or debugging, the agent follows a standard cycle:

Check file status: fossil_status(cwd="...")
Inspect exact modifications (diff): fossil_diff(cwd="...")
Stage new files:
- Specific files: fossil_add(files=["src/main.py"], cwd="...")
- Automatic sync (new files and deletions): fossil_addremove(cwd="...")
Commit to the repository: fossil_commit(message="Implement authentication module", cwd="...") (The server resolves any interactive prompts automatically without hanging).

Flow 3: Risk-Free Historical Exploration & Investigation

Unlike other VCS setups where an agent risks overwriting the active workspace when inspecting past code:

fossil_timeline: Displays the chronological event history. Supports filtering by specific file (path="src/main.py").
fossil_finfo: Displays the complete historical evolution of a single specified file.
fossil_cat (The Secret Weapon): Reads the exact content of any file directly from a historical revision, branch, or tag without touching or modifying local files in the active working directory:
```
{
  "file": "src/main.py",
  "revision": "f731ad3851",
  "cwd": "..."
}
```

Flow 4: Task & Bug Tracking (Ticketing)

Fossil provides a full ticketing system stored directly in the repository database:

List existing tickets: fossil_ticket_list(cwd="...")

Create a new task / bug report:

{
  "title": "Fix async timeout issue during remote calls",
  "status": "open",
  "additional_fields": {
    "type": "Code_Defect",
    "severity": "High"
  },
  "cwd": "..."
}

Close or update an existing ticket:

{
  "ticket_id": "a1b2c3d4",
  "field_name": "status",
  "field_value": "closed",
  "cwd": "..."
}

Flow 5: Documentation as Persistent AI Memory (Wiki)

Fossil Wiki pages are stored directly in the repository and do not depend on loose disk files:

List existing wiki pages: fossil_wiki_ls(cwd="...")
Read documentation: fossil_wiki_read(page_name="SystemArchitecture", cwd="...")
Store architectural decisions for future sessions: fossil_wiki_write(page_name="DesignDecisions", content="# Architecture...", cwd="...")

6. Complete Reference of the 29 MCP Tools

A. Version Control (20 Tools)

1. `fossil_status`

Description: Displays current workspace file status (modified, added, missing, untracked files).
Parameters:
- cwd (string, optional): Working directory path.
- dotfiles (boolean, default: false): Whether to include hidden files/folders (starting with dot).
- brief (boolean, default: false): Brief output showing only status keywords.
- ignore (string, optional): Comma-separated glob patterns of files to ignore.

2. `fossil_diff`

Description: Shows code diffs between workspace changes and repository, or between historical revisions.
Parameters:
- cwd (string, optional): Working directory path.
- files (array of strings, optional): Specific list of files to compare.
- from_version (string, optional): Starting revision (--from).
- to_version (string, optional): Destination revision (--to).
- branch (string, optional): Compares changes on specified branch.
- brief (boolean, default: false): Lists only modified filenames without full diff.
- ignore_whitespace (boolean, default: false): Ignores whitespace changes (-w).

3. `fossil_cat`

Description: Extracts and returns textual content of a file from a specified historical revision without altering the local workspace.
Parameters:
- file (string, required): Relative file path.
- revision (string, required): Commit hash, tag, or branch name.
- cwd (string, optional): Working directory path.

4. `fossil_finfo`

Description: Returns detailed modification history for a single specified file. Transparently follows rename events performed with fossil_mv.
Parameters:
- file (string, required): File path.
- limit (integer, optional): Maximum number of revisions to display (-n).
- cwd (string, optional): Working directory path.

5. `fossil_add`

Description: Schedules addition of one or more files/directories into version control.
Parameters:
- files (array of strings, required): List of file or directory paths.
- force (boolean, default: true): Forces addition even if matching ignore-glob patterns.
- dotfiles (boolean, default: false): Includes hidden files in recursive scan.
- cwd (string, optional): Working directory path.

6. `fossil_rm`

Description: Removes files from version control.
Parameters:
- files (array of strings, required): List of files to remove.
- force (boolean, default: false): Forces deletion without warnings.
- keep (boolean, default: false): Retains files physically on disk, removing them only from VCS.
- cwd (string, optional): Working directory path.

7. `fossil_mv`

Description: Renames or moves a file or directory in both repository and disk. Explicitly records the RENAME event in the version DAG, ensuring unbroken history tracking via fossil_finfo.
Parameters:
- old_name (string, required): Source file or directory path.
- new_name (string, required): Destination file or directory path.
- hard (boolean, default: true): Physically moves/renames the file on disk (--hard). If False, only records rename intention in manifest (--soft).
- case_sensitive (boolean, optional): Enforces case sensitivity (--case-sensitive 1/0).
- cwd (string, optional): Working directory path.

8. `fossil_addremove`

Description: Scans workspace and automatically adds newly created files while removing files deleted from disk.
Parameters:
- dotfiles (boolean, default: false): Includes dotfiles.
- ignore (string, optional): Glob patterns to ignore.
- clean (boolean, default: false): Deletes untracked extra files.
- reset (boolean, default: false): Resets add/remove state.
- cwd (string, optional): Working directory path.

9. `fossil_extras`

Description: Lists all files in the current working directory that are not tracked under version control.
Parameters:
- dotfiles (boolean, default: false): Includes hidden files.
- ignore (string, optional): Additional glob filter.
- cwd (string, optional): Working directory path.

10. `fossil_clean`

Description: Cleans untracked and temporary files from the working tree (fossil clean).
Parameters:
- all_files (boolean, default: false): Forces removal without interactive prompts (-f).
- dry_run (boolean, default: false): Simulation mode; lists files that would be removed without deleting (-n).
- cwd (string, optional): Working directory path.

11. `fossil_revert`

Description: Reverts uncommitted modifications in specified files back to their repository state.
Parameters:
- files (array of strings, required): Files to revert.
- revision (string, optional): Revision to revert to (defaults to current checkout).
- cwd (string, optional): Working directory path.

12. `fossil_stash`

Description: Temporarily saves uncommitted local changes to clear the workspace, allowing subsequent reapplication.
Parameters:
- action (string, default: "save"): Stash action: "save", "snapshot", "list", "pop", "apply", "drop", "diff".
- comment (string, optional): Comment describing the stash.
- stash_id (integer, optional): Identification number of the stash.
- cwd (string, optional): Working directory path.

13. `fossil_tag`

Description: Manages symbolic tags attached to specific check-ins.
Parameters:
- action (string, default: "list"): "add", "cancel", "list".
- tag_name (string, optional): Tag name (e.g., "v1.0.0").
- checkin (string, optional): Revision check-in to tag.
- cwd (string, optional): Working directory path.

14. `fossil_commit`

Description: Permanently commits staged changes as a new check-in in the repository.
Parameters:
- message (string, required): Commit message.
- files (array of strings, optional): Specific files to commit.
- branch (string, optional): New branch name to place the commit on (--branch).
- no_warnings (boolean, default: true): Suppresses CRLF and binary warnings.
- allow_empty (boolean, default: false): Allows commit even if there are no changes.
- user_override (string, optional): Overrides author username.
- cwd (string, optional): Working directory path.

15. `fossil_timeline`

Description: Displays chronological history of check-ins, wiki edits, and project activity.
Parameters:
- limit (integer, default: 20): Maximum number of events to show.
- path (string, optional): Filters timeline to a specific file or folder (-p).
- type_filter (string, optional): Type filter: "ci" (checkins), "w" (wiki), "t" (tickets), "e" (events) (-t).
- cwd (string, optional): Working directory path.

16. `fossil_info`

Description: Shows detailed information about the repository, current checkout, or a specific revision.
Parameters:
- target (string, optional): Revision hash, tag, or filename to inspect.
- cwd (string, optional): Working directory path.

17. `fossil_branch`

Description: Manages parallel development branches.
Parameters:
- action (string, default: "list"): "list" or "new".
- branch_name (string, optional): Name of the new branch when action="new".
- basis (string, optional): Basis check-in point.
- cwd (string, optional): Working directory path.

18. `fossil_merge`

Description: Merges another branch or specific check-in into the current workspace (fossil merge).
Parameters:
- branch_or_version (string, required): Branch name or check-in hash to merge.
- integrate (boolean, default: false): If True (--integrate), automatically closes the source branch upon subsequent commit.
- dry_run (boolean, default: false): Simulates merge without altering local files (-n).
- cwd (string, optional): Working directory path.

19. `fossil_update`

Description: Updates workspace files to the latest revision or switches checkout to another branch/version.
Parameters:
- target (string, optional): Version, branch, or tag to switch to.
- cwd (string, optional): Working directory path.

20. `fossil_undo`

Description: Reverses the last update, revert, or merge operation executed in the workspace.
Parameters:
- dry_run (boolean, default: false): Shows what would be reversed without performing action.
- cwd (string, optional): Working directory path.

B. Repository Administration & Setup (3 Tools)

21. `fossil_init`

Description: Creates and initializes a new Fossil repository database and automatically opens it in the specified directory.
Parameters:
- db_name (string, optional): Repository database filename (defaults to current folder name).
- project_name (string, optional): Logical project name.
- cwd (string, optional): Working directory path.

22. `fossil_open`

Description: Opens an existing Fossil repository database in the specified directory.
Parameters:
- db_name (string, required): Repository .fossil filename or path.
- force (boolean, default: false): Forces open even if directory is non-empty (-f).
- keep (boolean, default: false): Preserves existing local files (-k).
- cwd (string, optional): Working directory path.

23. `fossil_settings`

Description: Inspects or modifies repository configuration properties (crlf-glob, binary-glob, ignore-glob, autosync, etc.).
Parameters:
- name (string, optional): Property name (if omitted, lists all settings).
- value (string, optional): New value to set.
- cwd (string, optional): Working directory path.

C. Ticketing System (3 Tools)

24. `fossil_ticket_list`

Description: Lists existing tickets in the repository (includes automatic fallback to direct SQLite querying if standard Fossil ticket reports are not configured).
Parameters:
- report (integer, default: 1): Standard Fossil report number.
- cwd (string, optional): Working directory path.

25. `fossil_ticket_create`

Description: Opens a new ticket in the repository's tracking database.
Parameters:
- title (string, required): Title or summary of the task/defect.
- status (string, default: "open"): Initial status ("open", "in_progress", "closed", etc.).
- additional_fields (JSON dictionary/object, optional): Additional fields (e.g., type, severity, subsystem, description).
- cwd (string, optional): Working directory path.

26. `fossil_ticket_update`

Description: Modifies a field or status of an existing ticket.
Parameters:
- ticket_id (string, required): Ticket UUID identifier (or prefix).
- field_name (string, required): Field name to update (e.g., "status", "comment").
- field_value (string, required): New value assigned to field.
- cwd (string, optional): Working directory path.

D. Wiki System (3 Tools)

27. `fossil_wiki_ls`

Description: Returns a list of all wiki pages present in the repository.
Parameters:
- cwd (string, optional): Working directory path.

28. `fossil_wiki_read`

Description: Reads and returns complete text/markdown content of requested wiki page.
Parameters:
- page_name (string, required): Wiki page name.
- cwd (string, optional): Working directory path.

29. `fossil_wiki_write`

Description: Creates a new wiki page or updates content of an existing wiki page in the repository.
Parameters:
- page_name (string, required): Wiki page name.
- content (string, required): Markdown or text content.
- cwd (string, optional): Working directory path.

7. Windows Specifics & Built-in Technical Solutions

Running tools ported from UNIX on Windows presents specific challenges. FossilSoloMCP incorporates dedicated resilience measures:

1. Wildcard Expansion Issue with `crlf-glob "*"`

The Problem: On Windows, the MSVC/MinGW runtime of fossil.exe automatically expands * wildcards before entering main(). A command like fossil settings crlf-glob "*" reached Fossil as a raw list of all filenames in the directory, causing syntax errors.
The Solution: The server applies this setting directly to the repository database via native SQLite SQL:
```
REPLACE INTO config(name,value) VALUES('crlf-glob','*')
```
Bypassing the CLI entirely, this operation is 100% reliable, portable, and atomic.

2. Preserving the LF Standard via `.editorconfig`

Even though crlf-glob = * eliminates commit errors, Windows CRLF line endings can introduce artificial diffs across commits.
Upon fossil_open, the server automatically creates an .editorconfig file enforcing end_of_line = lf, ensuring code editors save clean UNIX-style line endings.

3. Anti-Hang Protection & Safety Timeout

Every spawned CLI process has stdin redirected to subprocess.DEVNULL when no explicit input is provided, preventing hangs on interactive prompts.
During fossil_commit, the server automatically supplies a\n on standard input to validate binary file and warning prompts.
All process calls are guarded by a strict 30-second timeout, with full capture of stderr and exit codes for immediate diagnosis.

8. Best Practices & Operational Tips

Atomic & Explicit Commits:
- Make frequent, focused commits after each working milestone or bug fix. Using fossil_undo or fossil_revert, you can always roll back cleanly to a verified stable state.
Preserving Project History in Wiki:
- Use Wiki pages (fossil_wiki_write) to document architectural conclusions, schema designs, or deployment instructions. Stored safely inside .fossil, they are never lost and remain directly viewable in your browser via fossil ui.
Advanced Optimization: Working on RAM Disk (Optional):
- For developers running endurance benchmarks, generating massive temporary scratch files, or running intensive AI automation scripts, using a temporary RAM Disk is an outstanding way to protect SSD write cycles and achieve maximum I/O throughput. Upon completing work sessions, validated changes can be synchronized to the permanent repository.
Advanced Automations with AI Agents:
- Depending on your client or IDE (e.g., agent rules in Google Antigravity, .cursorrules in Cursor, or System Prompts in Claude Desktop), configure clear instructions so the agent automatically versions important steps without requiring repetitive manual intervention.

9. License & Disclaimer (No Warranty)

📄 License

This project is licensed under the terms of the MIT License. See the LICENSE file for complete details.

📝 Warranty

No warranty of any kind is provided!

Manual de Utilizare și Referință Tehnică: Fossil SCM MCP (FossilSoloMCP)

1. Introducere & Filosofia Proiectului

Ce este Fossil SCM?

De ce Fossil pentru dezvoltarea solo Om + AI?

Ideal și pentru Echipe Mici (Fără Complexitatea Git-ului)

Rolul serverului FossilSoloMCP

2. Istoric, Origine și Comparație cu agent-vc-mcp

Punctul de Plecare: agent-vc-mcp

Limitări Majore ale agent-vc-mcp:

Trecerea la FossilSoloMCP: Rescriere și Maturizare

3. Prerechizite și Instalare

1. Prerechizite Sistem

2. Configurare în Clienți MCP

Exemplu Universal pentru Windows:

Exemplu Universal pentru Linux / macOS:

4. Arhitectura și Organizarea Depozitelor

Convenția .fossil_repositories

Deschiderea Interfeței Grafice Web

5. Ghid de Lucru pentru Agenți AI (Fluxuri Universale Recomandate)

Regulă Recomandată pentru Agentul AI (System Prompt / Reguli de lucru)

Fluxul 1: Inițializarea unui Proiect Nou

Fluxul 2: Ciclul Standard de Modificare și Commit

Fluxul 3: Explorare Istorică și Investigare Fără Risc

Fluxul 4: Gestiunea Sarcinilor (Ticketing)

Fluxul 5: Documentație ca Memorie Persistentă (Wiki)

6. Referința Completă a Celor 29 de Instrumente MCP

A. Version Control (20 Instrumente)

1. fossil_status

2. fossil_diff

3. fossil_cat

4. fossil_finfo

5. fossil_add

6. fossil_rm

7. fossil_mv

8. fossil_addremove

9. fossil_extras

10. fossil_clean

11. fossil_revert

12. fossil_stash

13. fossil_tag

14. fossil_commit

15. fossil_timeline

16. fossil_info

17. fossil_branch

18. fossil_merge

19. fossil_update

20. fossil_undo

B. Administrare & Depozit (3 Instrumente)

21. fossil_init

22. fossil_open

23. fossil_settings

C. Sistemul de Ticketing (3 Instrumente)

24. fossil_ticket_list

25. fossil_ticket_create

26. fossil_ticket_update

D. Sistemul Wiki (3 Instrumente)

27. fossil_wiki_ls

28. fossil_wiki_read

29. fossil_wiki_write

7. Particularități Windows & Soluții Tehnice Încorporate

1. Problema Expandării Wildcard-urilor la crlf-glob "*"

2. Păstrarea Standardului LF prin .editorconfig

3. Protecție Anti-Hang și Timeout de Siguranță

8. Bune Practici & Sfaturi de Lucru

9. Licență & Declinarea Responsabilității (No Warranty)

📄 Licență

📝 Garanție

User Manual & Technical Reference: Fossil SCM MCP (FossilSoloMCP)

1. Introduction & Project Philosophy

What is Fossil SCM?

Why Fossil for Solo Human + AI Development?

Ideal for Small Teams (Without Git's Complexity)

The Role of the FossilSoloMCP Server

2. History, Origin, and Comparison with agent-vc-mcp

The Starting Point: agent-vc-mcp

Major Limitations of agent-vc-mcp:

Transition to FossilSoloMCP: Complete Rewrite & Maturation

3. Prerequisites and Installation

1. System Prerequisites

2. Configuration in MCP Clients

2. Istoric, Origine și Comparație cu `agent-vc-mcp`

Punctul de Plecare: `agent-vc-mcp`

Limitări Majore ale `agent-vc-mcp`:

Trecerea la `FossilSoloMCP`: Rescriere și Maturizare

Convenția `.fossil_repositories`

1. `fossil_status`

2. `fossil_diff`

3. `fossil_cat`

4. `fossil_finfo`

5. `fossil_add`

6. `fossil_rm`

7. `fossil_mv`

8. `fossil_addremove`

9. `fossil_extras`

10. `fossil_clean`

11. `fossil_revert`

12. `fossil_stash`

13. `fossil_tag`

14. `fossil_commit`

15. `fossil_timeline`

16. `fossil_info`

17. `fossil_branch`

18. `fossil_merge`

19. `fossil_update`

20. `fossil_undo`

21. `fossil_init`

22. `fossil_open`

23. `fossil_settings`

24. `fossil_ticket_list`

25. `fossil_ticket_create`

26. `fossil_ticket_update`

27. `fossil_wiki_ls`

28. `fossil_wiki_read`

29. `fossil_wiki_write`

1. Problema Expandării Wildcard-urilor la `crlf-glob "*"`

2. Păstrarea Standardului LF prin `.editorconfig`

2. History, Origin, and Comparison with `agent-vc-mcp`

The Starting Point: `agent-vc-mcp`

Major Limitations of `agent-vc-mcp`:

Transition to `FossilSoloMCP`: Complete Rewrite & Maturation

The `.fossil_repositories` Convention

1. `fossil_status`

2. `fossil_diff`

3. `fossil_cat`

4. `fossil_finfo`

5. `fossil_add`

6. `fossil_rm`

7. `fossil_mv`

8. `fossil_addremove`

9. `fossil_extras`

10. `fossil_clean`

11. `fossil_revert`

12. `fossil_stash`

13. `fossil_tag`

14. `fossil_commit`

15. `fossil_timeline`

16. `fossil_info`

17. `fossil_branch`

18. `fossil_merge`

19. `fossil_update`

20. `fossil_undo`

21. `fossil_init`

22. `fossil_open`

23. `fossil_settings`

24. `fossil_ticket_list`

25. `fossil_ticket_create`

26. `fossil_ticket_update`

27. `fossil_wiki_ls`

28. `fossil_wiki_read`

29. `fossil_wiki_write`

1. Wildcard Expansion Issue with `crlf-glob "*"`

2. Preserving the LF Standard via `.editorconfig`