Gitlab - SME Driver

AI Backoffice Agent automating SME invoices, auditing provider databases, and compiling pixel-perfect PDFs directly via Telegram using GitLab and Gemini

Comment

Gitlab - SME Driver: AI-Powered Fleet Backoffice & Audit

Inspiration

Small and Medium Enterprises (SMEs), especially in the transport and logistics sectors, suffer from severe backoffice overhead. Fleet managers and drivers waste hours manually registering receipts, generating invoices (Cuentas de Cobro), and auditing provider catalogs.

Our inspiration was to create a frictionless, conversational backoffice assistant where drivers and administrative managers can audit rates, register new providers, and generate pixel-perfect, ready-to-print A4 PDF invoices directly from their messaging app (Telegram), backed by the compliance, version control, and automation power of GitLab.

What it does

GitLab - SME Driver is a secure, enterprise-grade, conversational AI Backoffice. Integrated with Telegram, it enforces a professional, multi-tenant Corporate B2B Fleet Workflow:

  1. The Provider Company (Datos de la Empresa): A logistics/transport company registered in our central database (providers.json) that issues the invoice and receives the settlement (e.g., PharmaLogistics Colombia).
  2. The Driver/Employee: An active resource or contractor assigned by the Provider Company (e.g., Andres Gomez) to physically execute the transport service.
  3. The End Customer (Datos del Cliente): The final client receiving and paying the invoice/receipt (e.g., Stiven Diaz).

By secure Role-Based Access Control (RBAC):

  • Sellers (Restricted Users): Can conversationally query authorized provider rates and propose transaction proposals. The AI dynamically registers and prepares preliminary documents and automatically opens a GitLab Merge Request (MR).
  • Auditors (Super-Users/Admins): Have full system administrative powers. They can register new corporate providers into the central directory, list pending Merge Requests, and conversationally approve them. Approving a transaction merges the GitLab MR, triggering a GitLab CI/CD pipeline that compiles the data into beautiful HTML and A4 PDF receipts using Weasyprint, delivering permanent public preview and download links back to Telegram. Auditors can also invalidate incorrect transactions.

How we built it

We engineered a highly unified, serverless, and lightweight Node.js/TypeScript architecture:

  • Conversational Engine & Cognitive Layer: Powered by Google Cloud Vertex AI utilizing Gemini 2.5 Flash for fast, reliable, and cost-effective reasoning.
  • Agent Integration Framework: Built with the Google Agent Development Kit (ADK) in TypeScript, managing session histories and calling tools dynamically.
  • Unified Middleware Backend: A fast Express.js API which may be deployed as serverless as a single container on Google Cloud Run, consolidating the Telegram Webhook handler, secure RBAC prompt-injection guards, and the local ADK Agent runner.
  • Document Compilation Pipeline: Powered by GitLab CI/CD. Sourced via Gitaly, every approved transaction triggers a Python-based Shared Runner running Weasyprint, rendering Markdown frontmatter data into A4 printable PDFs.
  • Our Custom High-Speed GitLab MCP Server: We developed a custom, high-speed Model Context Protocol (MCP) Server in TypeScript over standard input/output (stdio), mapping 9 critical enterprise tools directly over the GitLab REST API.

The 9 Custom MCP Tools & Their System Capabilities

To bypass platform-level limits, we built our own tailored MCP server. These 9 tools empower the AI Agent with real administrative capabilities:

  1. get_providers (Read Database): Fetches the active company directory (providers.json). Allows the agent to verify if a logistics provider exists and fetch their agreed-upon rates.
  2. add_provider (Database Sync): Dynamically parses, appends, and commits a new corporate provider cleanly back to the database in GitLab. Operates entirely in native TS, eliminating JSON formatting or escaping bugs.
  3. create_branch (Transaction Spawning): Spawns a new Git branch for a proposed transaction to keep changes isolated and secure.
  4. create_or_update_file (File Commit): Writes or updates Markdown receipt/invoice transactions in their respective directories (receipts/ or invoices/).
  5. create_merge_request (Approval Request): Automatically opens a Merge Request in GitLab, acting as an audit-ready "Transaction Proposal."
  6. merge_mr (Transaction Settlement): Approves and merges the MR. This represents the final "Settle and Issue" action which automatically triggers the document compilation.
  7. add_mr_label (Audit Invalidation): Adds a label (such as INVALID) to an existing Merge Request. This empowers auditors to flag and cancel incorrect transactions.
  8. list_directory_files (Audit Discovery): Lists files inside the receipts/ or invoices/ folders, enabling the agent to audit and fetch past compiled documents.
  9. get_artifact_links (Frictionless Delivery): Dynamically constructs permanent, latest public URLs for both compiled HTML and PDF artifacts on the main branch. It outputs two clean links: Online Preview (opening GitLab's native PDF Viewer /file/ endpoint) and Direct Download (raw /raw/ download endpoint).

Challenges we ran into

We tackled several severe, low-level technical challenges that pushed our engineering skills to the limit:

  1. The Regional 404 NOT_FOUND Constraint: During Google Cloud deployments, Vertex AI's us-central1 reasoning engine class loader would throw obscure internal errors. We bypassed this by migrating from experimental model previews to the fully GA and stable gemini-2.5-flash backend.
  2. Node.js ByteString & Symbol Errors: Connecting directly to GitLab's /api/v4/mcp endpoint over Server-Sent Events (SSE) threw native Node.js network errors due to undici injecting Symbol-based headers. We solved this by building our own custom TypeScript GitLab MCP Server running locally, communicating over standard HTTP REST, which is 100% stable.
  3. Google ADK Zod Schema Translation Bugs: The massive 170-tool community GitLab MCP server uses complex union schemas that crashed Google's internal ADK type translation utility with TypeError: o.toLowerCase is not a function. By writing our own tailored, lightweight 9-tool MCP server, we designed clean, plain Zod schemas that are 100% ADK-compliant.
  4. GitLab CI/CD Docker image deprecations: Running Weasyprint on Debian slim containers triggered missing package candidates. We optimized our .gitlab-ci.yml for the latest Debian Trixie (Debian 13) using shared-mime-info and resolved Jinja2 class loaders typos.
  5. Official GitLab Beta MCP & Google Cloud Agent Builder Compatibility (The 404 Wall): During initial integration tests, we attempted to utilize GitLab's newly-released native Beta MCP Server (/api/v4/mcp). However, we repeatedly ran into frustrating 404 Not Found API errors. Despite configuring everything perfectly—including verifying Owner roles, activating experimental Duo flags, and allocating SaaS Ultimate trial seats—both the Gemini CLI/ADK locally and Google Cloud Agent Builder in the cloud rejected the handshake due to OAuth and SSE transport constraints. Recognizing this platform-level Beta limitation, we pivoted and engineered our own custom stdio-based GitLab MCP Server, turning a major platform blocker into a robust, high-performance integration that gave our agent complete and secure control over the repository.

Accomplishments that we're proud of

  • True Git-as-a-Database: Successfully implementing a system where all transaction states and corporate databases are completely version-controlled, auditable, and backed up on GitLab without a heavy external SQL database.
  • Extreme Stack Unification: Merging the Telegram webhook middleware, the security layer, and the Google ADK Agent into a single, highly-cohesive, 100% serverless Node.js container with zero unnecessary network latency.
  • Beautiful PDFs: The Weasyprint compiler generates outstanding, professional, ready-to-print PDFs that look identical to manually-crafted invoices.

What we learned

  • Model Context Protocol (MCP) Mastery: We learned how to build custom MCP servers from scratch using the @modelcontextprotocol/sdk and integrate them as stdio subprocesses within an AI agent.
  • Secure Agent Design: How to enforce strict server-side RBAC and prevent prompt injection by wrapping user messages in immutable <system_enforced_context> XML blocks on the middleware level.

What's next for Gitlab - SME Driver

  • GCP Secret Manager Integration: Move the GitLab Personal Access Tokens from the environment variables into fully automated Google Secret Manager bindings.
  • Direct Telegram Document Upload: Program the Middleware to automatically fetch the compiled PDF from GitLab's CI/CD artifacts and send the raw .pdf file attachment directly to the driver's chat, rather than just delivering a download URL.

Built With

Share this project:

Updates