Architecture

Gitlas is divided into two MCP servers that reflect distinct domain boundaries. The agent (ollamarama-matrix from PyPI, deployed as the ollamarama/ service) connects to both and decides which tool to call.

Domain Boundary

Responsibility	Gitlas	forgejo-mcp
Markdown pages (read, write, search)	✅	❌
Templates and frontmatter	✅	❌
Local Git operations (branch, commit)	✅	❌
git push to remote	✅	❌
Pull Requests	❌	✅
Issues and comments	❌	✅
Reviews	❌	✅
Labels and milestones	❌	✅
Releases and attachments	❌	✅
Repository metadata	❌	✅

Decision Rule

Can the operation run against a plain local Git repository without any Forgejo API? → Gitlas.

Does the operation need Forgejo-specific API objects (PRs, issues, labels, releases) or project metadata? → forgejo-mcp.

Why This Separation

• Gitlas needs no knowledge of Forgejo. The same server works with any Git remote — GitHub, GitLab, Gitea, or a bare SSH server.
• forgejo-mcp needs no knowledge of Markdown content. It operates purely on Forgejo API resources.
• The agent composes both. The ollamarama-matrix bot lists tools from both servers and merges them into a single schema for the LLM. A typical workflow spans both:

update_page        → Gitlas
commit_changes     → Gitlas
push_changes       → Gitlas
create_pull_request → forgejo-mcp

• Future-proof. Replacing forgejo-mcp with github-mcp or gitlab-mcp requires zero changes to Gitlas.

Profiles

Docker Compose defines two profiles:

Profile	Services
demo	Ollama + gitlas-mcp
full	All of demo + forgejo-mcp (upstream image codeberg.org/goern/forgejo-mcp:latest), ollamarama, open-webui, quartz

Use make demo-minimal (demo) for local development, make demo (full) for the complete stack with Matrix integration.

Service Topology

Matrix Client (Element)
       │
       ▼
ollamarama-matrix (Matrix bot)
       │
       ├── MCP ──► Gitlas MCP Server (port 8765, SSE)
       │                │
       │                ├── read_page / search_documents
       │                ├── create_page / update_page
       │                ├── create_branch / commit_changes
       │                └── push_changes
       │
       └── MCP ──► forgejo-mcp (port 8080, SSE)
                        │
                        ├── create_pull_request
                        ├── create_issue
                        ├── list_repo_issues
                        └── (60+ tools for Forgejo API)