Research Decisions
Date: 2026-02-16
Decision 1: Build New Server (No Existing Solution)
Context: Need an MCP server for GitLab. Investigate existing open‑source options.
Chosen: Build from scratch.
Rationale:
- No mature MCP server for GitLab found in official or community lists.
- GitLab’s REST API is comprehensive and straightforward to wrap.
- Building allows customizing tool design for agent friendliness (high‑level actions, idempotency).
Decision 2: Go Implementation
Context: Choose language for MCP server.
Chosen: Go.
Rationale:
- Consistent with other OpenClaw tools and the DNS/Namecheap MCP servers.
- Static binary, easy to deploy on VPS.
- Strong stdlib for HTTP and JSON.
- Good concurrency model.
Decision 3: Stdio Primary, Web Optional
Context: Transport layer for MCP.
Chosen: stdio as primary; add HTTP endpoint as secondary extension.
Rationale:
- Stdio is standard for AI agents (ChatGPT, Claude).
- Simpler security (OS permissions).
- Web mode adds flexibility for browsers or remote scripts without complicating main code path.
Decision 4: REST API over GraphQL
Context: Choose backend API to talk to GitLab.
Chosen: REST API (v4).
Rationale:
- Simpler to implement for a known set of tools.
- Adequate for MVP; GraphQL can be added later for performance if needed.
- Most examples and documentation are REST.
Decision 5: Personal Access Token (PAT) Auth
Context: How will server authenticate to GitLab?
Chosen: PAT via `PRIVATE-TOKEN` header.
Rationale:
- Easy to set up and scope.
- No OAuth flow required for server‑to‑server.
- Token stored in environment variable; rotate if compromised.
Decision 6: Idempotent High‑Level Tools
Context: Tool granularity – raw vs opinionated.
Chosen: Opinionated, high‑level tools with idempotent behavior where practical (e.g., `upsert_file`, `create_issue` checks for existing by title if needed).
Rationale:
- Reduces cognitive load for AI agents.
- Encourages safer automation.
- Prevents duplicate issues/MRs from multiple calls.