Metadata-Version: 2.5
Name: fossil-scm-mcp
Version: 1.0.0
Summary: Model Context Protocol (MCP) server for Fossil SCM with 29 specialized tools for AI agents
Project-URL: Homepage, https://github.com/ReluPercan/FossilSoloMCP
Project-URL: Documentation, https://github.com/ReluPercan/FossilSoloMCP#readme
Project-URL: Repository, https://github.com/ReluPercan/FossilSoloMCP.git
Project-URL: Bug Tracker, https://github.com/ReluPercan/FossilSoloMCP/issues
Author: Relu Percan
License: MIT
License-File: LICENSE
Keywords: ai-agents,fastmcp,fossil,fossil-scm,mcp,model-context-protocol,version-control
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.3.0
Description-Content-Type: text/markdown

[🇬🇧 English](README.md) | [🇷🇴 Versiunea în limba română](doc/citeste-ma.md)

---

⚠️ **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** 🤔😉🤫.  

---

# Fossil SCM - MCP Server

A robust Model Context Protocol (MCP) server providing comprehensive, headless programmatic access to **Fossil SCM** repositories. It exposes **29 dedicated tools** covering Version Control, Repository Administration & Settings, Bug/Task Ticketing, and Wiki management, tailored specifically for AI agents (Google Antigravity, Claude Desktop, Cursor, etc.).

## Prerequisites

> [!IMPORTANT]
> **CRITICAL:** This package does NOT install the Fossil executable itself.  
> For this MCP server to function, you MUST have the `fossil` command-line utility installed and available in your system's `PATH` environment variable.

1. Download Fossil from the official website: [https://fossil-scm.org/](https://fossil-scm.org/)
2. Extract and place the executable (`fossil.exe` on Windows, `fossil` on Linux/macOS) in a directory of your choice.
3. Add that directory to your system's `PATH`.

## Installation & Configuration

To integrate this MCP server with Claude Desktop, Google Antigravity, or other MCP-compatible clients, add the following configuration to your MCP configuration file (e.g., `claude_desktop_config.json` or `mcp_config.json`):

### Using `uv` (Recommended)

```json
{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/fossil-scm-mcp",
        "fossil-scm-mcp"
      ]
    }
  }
}
```

*Replace `/path/to/fossil-scm-mcp` with the actual path to the repository directory on your system (e.g., `C:/Tools/FossilSCM` or `/home/user/FossilSCM`).*

> [!IMPORTANT]
> **Golden Rule for AI Agents (Dynamic `cwd`):**  
> The server operates completely decoupled and dynamically. To cleanly handle multiple repositories without workspace conflicts, **always instruct your AI assistant to provide the `cwd` parameter** (the absolute path of the current project) on every tool call.  
> 
> *Recommended AI Agent Rule (System Prompt / Custom Instructions):*
> ```text
> When calling any tool in the fossil-scm MCP server, always provide the 'cwd' parameter explicitly set to the current project's absolute working directory.
> ```

> [!TIP]
> The `--repository` CLI parameter can optionally specify a static fallback working directory for calls omitting `cwd`. However, passing `cwd` dynamically on every tool call remains the recommended practice.

## Key Features & Capabilities

- **29 Specialized Tools:**
  - **Version Control (20 tools):** Workspace status (`fossil_status`), diff with revision and branch support (`fossil_diff`), historical file inspection without checkout (`fossil_cat`), per-file commit history (`fossil_finfo`), granular file restoration (`fossil_revert`), DAG-preserving file rename (`fossil_mv`), workspace cleanup (`fossil_clean`), branch merging with auto-close (`fossil_merge`), temporary stash management (`fossil_stash`), symbolic tag management (`fossil_tag`), granular add/remove (`fossil_add`, `fossil_rm`, `fossil_addremove`, `fossil_extras`), branch management (`fossil_branch`), commit with new branch creation (`fossil_commit`), timeline with path and type filters (`fossil_timeline`), and safe undo/update operations (`fossil_undo`, `fossil_update`).
  - **Ticketing & Bug Tracking (3 tools):** List (`fossil_ticket_list`), create (`fossil_ticket_create`), and update tickets (`fossil_ticket_update`) stored directly within the repository database.
  - **Wiki Documentation (3 tools):** List (`fossil_wiki_ls`), export/read (`fossil_wiki_read`), and commit/write (`fossil_wiki_write`) Markdown wiki pages.
  - **Repository Administration & Setup (3 tools):** Initialize new repositories (`fossil_init`), open repositories (`fossil_open`), and inspect/modify repository configurations (`fossil_settings`).
- **Headless & Anti-Hang Resilience:**
  - Automatically sets `stdin` to `DEVNULL` to instantly fail interactive CLI prompts (`y/N`) instead of hanging.
  - Built-in 30-second timeout mechanism with clean error reporting.
  - Default `--no-warnings` and automatic prompt handling on commits for binary files and CRLF/LF line endings.
  - `fossil_add` uses `force=True` by default, cleanly bypassing `ignore-glob` confirmation prompts when files are explicitly specified.
- **Centralized Repositories:** Automatically organizes repositories into a `.fossil_repositories/` directory outside the active working tree.
- **Safety First:** Destructive operations (`undo`, `update`) are explicitly labeled with warnings so AI agents ask for human confirmation before executing.

---

## 📚 Documentation

For complete architectural details, AI agent workflows, and the in-depth API reference covering all 29 tools, see the [User Manual & Technical Reference](Manual.md).

---

## 📄 License

This project is licensed under the terms of the **MIT** License. See the [LICENSE](LICENSE) file for complete details.

---

## 📝 Warranty

No warranty of any kind is provided!

