fossil-scm-mcp

Top-level Files of tip
Login

Top-level Files of tip

Download File Ages Tree-View

Files in the top-level directory from the latest check-in

fossil-scm-mcp

A Model Context Protocol (MCP) server for Fossil SCM. Designed for low-latency, high-context AI agent workflows with LLMs (Claude, Cursor, etc). Exposes Fossil's versioning, artifacts, timeline, and durable tech notes as first-class tools and resources.

Quick Start for Other AI Agents (Self-Bootstrapping from Fossil Remote)

🚨 CRITICAL RULE — AGENTS MUST OBEY THIS WITHOUT EXCEPTION 🚨

This entire project (and any work you perform while inside this checkout or any subdirectory) is stored exclusively in a Fossil SCM repository.

This is the most important rule for any agent using this MCP. The whole point of this server is to demonstrate and enforce proper Fossil-only workflows.

0. Check that Fossil is installed (required before anything else)

# Check for Fossil
if command -v fossil >/dev/null 2>&1; then
  echo "✓ Fossil found: $(fossil version | head -1)"
else
  echo "✗ Fossil is NOT installed in PATH."
  echo ""
  echo "Install Fossil for your platform:"
  echo ""
  echo "  • Linux (Debian / Ubuntu / Mint):   sudo apt update && sudo apt install fossil"
  echo "  • Linux (Fedora / RHEL / Rocky):    sudo dnf install fossil"
  echo "  • Linux (Arch / Manjaro):           sudo pacman -S fossil"
  echo "  • Linux (openSUSE):                 sudo zypper install fossil"
  echo "  • macOS (Homebrew):                 brew install fossil"
  echo "  • Windows:                          Download the .exe from https://fossil-scm.org/home/uv/download.html"
  echo "  • Any OS (official binaries):       https://fossil-scm.org/home/uv/download.html"
  echo ""
  echo "After installing, verify with:  fossil version"
  echo "Then re-run the steps below."
  exit 1
fi

This project is designed to be installed directly by another agent from the public Fossil repository, without Git.

# 1. Acquire the source using Fossil (the correct tool)
fossil clone https://refaqtory.net/fossil-scm-mcp /tmp/fossil-scm-mcp.fossil

# 2. Open a checkout in your working area
mkdir -p ~/agent-work/fossil-scm-mcp
cd ~/agent-work/fossil-scm-mcp
fossil open /tmp/fossil-scm-mcp.fossil

# 3. Bootstrap the Python environment (creates .venv, which is ignored)
./bootstrap.sh

# 4. Run the MCP server
.venv/bin/python -m fossil_mcp
# or the shorter alias
.venv/bin/fossil-mcp

Once running, the server provides the special resource fossil://agent/fossil-best-practices (also available as the file FOSSIL-FOR-AGENTS.md). Read it immediately — it teaches you the correct "Fossil way" (atomic commits, heavy use of tech notes for memory, keeping the repo perfectly clean, etc.).

The bootstrap.sh script prefers uv when available (excellent for agents) and falls back to a standard venv. The resulting environment lets you run the server or the integration test with almost zero friction.

The clone URL above corresponds to the repository browsable at the URL you were given (https://refaqtory.net/fossil-scm-mcp/dir?ci=tip).

Goals & Constraints

Proposed Architecture (Baseline)

Runtime & SDK

Project Layout (final) 

.
├── .fossil-settings/
│   └── ignore-glob          # aggressively ignore venvs, __pycache__, build, test artifacts
├── README.md
├── pyproject.toml           # modern packaging, deps (mcp), scripts
├── fossil_mcp/
│   ├── __init__.py
│   ├── __main__.py          # `python -m fossil_mcp`
│   └── server.py            # FastMCP instance, all @tool / @resource
└── tests/
    └── integration_test.py  # spawns server over stdio, drives JSON-RPC, asserts responses

Implementation Strategy

Tools (Actions)

  1. fossil_status — Aggregate of fossil status, fossil changes, fossil extras. Returns structured JSON: { "checkout": {...}, "changes": [{"status":"EDITED","path":".."}], "extras": ["untracked.."] }
  2. fossil_commit — fossil commit -m "msg" [ --allow-empty ? ]. Requires non-empty message. Optional addremove: bool to auto-include new files. Returns result text. Dry-run supported.
  3. fossil_timeline — Recent history. Uses fossil json timeline checkin ... internally for accuracy, then renders to compact lines optimized for context (e.g. [<short-uuid>] <user> <tags> <comment>). Params: limit:int=20, tag:str|None, branch:str|None.
  4. fossil_diff — Unified diff via fossil diff --unified -N ... (or json where helpful). Params: files: list[str]|None (None = all uncommitted), context:int=3, revision:str|None (for historical).
  5. fossil_technote — Multi-action for durable memory:
    • action: "list" | "read" | "create" | "append"
    • For read/create/append: ref (datetime|id|tag), content, tags, etc.
    • Create uses --technote now, append does export + commit update.
  6. fossil_artifact_view — Raw content: fossil artifact <SHA> or fossil cat <file> -r <REV>. Returns exact bytes decoded as utf8 (or error). Critical for grounding LLM on exact file versions or manifests.

Resources (Data Sources)

Error & Observability

Testing

Performance / Polish

Installation & Usage (for LLM Clients)

Prerequisites

(The mcp Python package will be pulled in automatically when you pip install -e . inside a venv.)

The easiest way for agents and humans is:

./bootstrap.sh
.venv/bin/python -m fossil_mcp

See the "Quick Start for Other AI Agents" section above for the full clone + bootstrap flow from the public Fossil remote.

Manual equivalent (if you prefer):

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m fossil_mcp

The integration test also auto-detects the local .venv:

python tests/integration_test.py   # or .venv/bin/python ...

This project keeps your system Python untouched and always talks to the real fossil binary in your PATH.

Claude Desktop / Cursor / MCP Host Config Example

{
  "mcpServers": {
    "fossil-scm": {
      "command": "python",
      "args": [
        "/home/ben/Documents/refaqtor/fossil-scm-mcp/fossil_mcp/server.py"
      ],
      "env": {}
    }
  }
}

Recommended (with uv for hermetic): 

{
  "mcpServers": {
    "fossil-scm": {
      "command": "uv",
      "args": [
        "--with", "mcp",
        "run", "--python", "3.12",
        "python", "-m", "fossil_mcp"
      ],
      "cwd": "/path/to/your/fossil-workdir"
    }
  }
}

The server inherits the cwd / .fslckout, so open the desired Fossil checkout before launching the host, or set cwd in the MCP client config.

Direct CLI Test

python -m fossil_mcp --help   # if implemented
# or just launch and send manual JSON-RPC (advanced)

Development Process Notes

This project was built entirely inside Fossil with strict phase commits + tech notes:

See the timeline (fossil timeline) for the exact engineering log.

License

MIT (or public domain, matching Fossil spirit).

Status

Phase 3 complete (full tool + resource impl). All 6 tools and 2 resources execute real fossil commands safely. See Fossil timeline and fossil wiki list --technote for the live engineering log (including multiple tech notes created during verification of fossil_technote).