Repository avatar
AI Tools
v1.0.1
active

g-krusch

dev.krusch/g-krusch

Local-first Google Workspace MCP server with hybrid FTS5 Drive RAG, Docs, Calendar, and Gmail.

Documentation

ā˜ļø G-Krusch — Sovereign Google Workspace Hub & MCP Bridge

Google Drive RAG, Cloud-Synced agent.md Steering, Calendar & Gmail Extensions for AI Agents
Powers autonomous IDE agents (via MCP) and Krusch Companion's <holodata> Agentic Proxy (via REST on :5446).

Node.js MCP HOL Guard Catalog Krusch Companion Bridge Tests Passed License: MIT M8ven Score


🧠 Why G-Krusch?

Most AI agents are trapped either in ephemeral context windows or isolated local folders that you can't easily access when away from your workstation. G-Krusch bridges the gap between humans, coding agents, and personal assistants (krusch-companion) across your Google Workspace:

  1. agent.md Cloud-Synced Steering: Edit your agent rules, project priorities, and personas from your phone, tablet, or web browser directly in Google Drive. When an agent boots, it dynamically pulls the latest instructions via get_agent_steering (GET /api/steering).
  2. Sovereign 1,024-Dim Vector & FTS5 BM25 Drive RAG: Queries your Google Docs, PDFs, notes, and specs using a 3-tier dense semantic embedding cascade (Tier 1: local GPU Ollama snowflake-arctic-embed2:latest 8K-ctx 1,024-dim -> Tier 2: Gemini models/gemini-embedding-001 at outputDimensionality: 1024 -> Tier 3: uncached deterministic 64-dim offline fallback) fused with SQLite FTS5 Porter-stemmed BM25 keyword search.
  3. 3-Tier Page-Faithful PDF Extraction: Validates %PDF- magic bytes prior to disk spooling (validatePdfMagicBytes) and extracts multi-page PDFs with page citations ([contract.pdf p.1]) via Tier 1 Krusch-Nexus (pdftotext -bbox-layout), Tier 2 system Poppler pdftotext, or Tier 3 pure-JS stream extraction (extractPdfTextNative).
  4. Two-Way Agent Filesystem + Native Google Docs, Sheets & Slides: Agents can read project briefs from context/, check decision logs in memory/, and use write_drive_file to create or update Markdown files, styled Google Docs (.gdoc), Google Sheets (.gsheet from CSV or Markdown tables), and 16:9 Google Slides presentations (.slides from ----separated Markdown decks) directly in output/.
  5. Google Calendar & Gmail Extensions: Exposes hardened REST endpoints (/api/calendar/events, /api/gmail/messages, /api/gmail/drafts, /api/gmail/send) so Krusch Companion can check your schedule, book appointments, search your inbox, and compose RFC-2822 / RFC-2047 emails.

šŸ“ Workspace Structure in Google Drive

When G-Krusch connects to your Google Drive, it manages a dedicated workspace folder (defaults to G-Krusch):

Google Drive /
  └── G-Krusch/
        ā”œā”€ā”€ agent.md             # Authoritative steering & invariants (edit anywhere)
        ā”œā”€ā”€ context/             # Domain knowledge, architectural specs, SOPs
        ā”œā”€ā”€ memory/              # Decisions, invariants, project logs
        └── output/              # Agent-generated artifacts, reports, proposals

šŸ›”ļø Security & Concurrency Hardening

  • AES-256-GCM Encrypted Token Vault (src/lib/crypto.js & src/lib/db.js): OAuth 2.0 access and refresh tokens are encrypted at rest in SQLite WAL using AES-256-GCM with NIST SP 800-38D 12-byte (96-bit) IVs and 16-byte authentication tags (plus transparent legacy 16-byte IV decryption).
  • OAuth 2.0 CSRF State & CORS Origin Lockdown (src/lib/oauth.js & src/lib/auth-guard.js): Generates one-time 32-byte CSRF state tokens with constant-time validation on /auth/google/callback, and restricts browser CORS requests to trusted localhost, RFC1918 LAN, and Tailscale (100.64.0.0/10) origins.
  • FIFO Keyed Mutex & Atomic SQLite Transactions (src/lib/mutex.js & src/lib/rag.js): AsyncKeyedMutex serializes concurrent OAuth token refreshes, workspace provisioning, per-path writes, and RAG indexing, while saveIndexedDocumentTransactional commits document chunks and FTS5 indices atomically with automatic FTS5 self-healing (ensureFtsSync).
  • Path Traversal, Drive Query Escaping & Workspace Boundary Guard (src/lib/path-utils.js & src/lib/drive.js): Blocks .., control characters, and sensitive dotfiles (.env, .git, id_rsa, .pem), escapes backslashes and quotes in Drive API queries, and verifies workspace ancestry before trashing any file by fileId.
  • CRLF Header Injection Shield & RFC 2047 UTF-8 Encoder (src/lib/extensions.js): Strips CR/LF and control characters from email headers, validates recipient addresses, and encodes non-ASCII subjects using =?UTF-8?B?...?=.
  • Constant-Time API Key Guard (src/lib/auth-guard.js): Uses crypto.timingSafeEqual when API_KEY or GCRUSH_SECRET is configured to protect workspace and MCP endpoints against timing side-channel attacks, paired with HTML escaping (escapeHtml) on OAuth callback pages.

⚔ Quick Start & Diagnostics

Agent-Assisted Setup

Ask your coding agent (Claude Code, Codex, Cursor, Windsurf, or Antigravity):

Read https://raw.githubusercontent.com/kruschdev/G-krusch/main/INSTALL.md and set up G-krusch on this machine.

1. Installation

git clone https://github.com/kruschdev/G-krusch.git
cd G-krusch
npm install

2. Configure Environment

Copy .env.example to .env and provide your Google OAuth credentials (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET) and optional GEMINI_API_KEY:

cp .env.example .env

3. Run Production Diagnostic Doctor & Tests

(All 32 unit & hardening tests run hermetically against an isolated per-PID temporary SQLite database with zero external credentials required)

# Run 12-point production diagnostic check (Node 22+, SQLite WAL + busy_timeout, FTS5 sync, 12-byte AES-256-GCM, OAuth, Embeddings, Nexus PDF, MCP, Extensions)
npm run doctor

# Run all 32 unit & hardening tests
npm test

4. Launch G-Krusch (CLI or Systemd User Service)

# Start directly on http://localhost:5446
npm start

# Or manage via systemd user service on port 5446
systemctl --user status g-krusch.service
systemctl --user restart g-krusch.service

Endpoints:

  • Web Dashboard: http://localhost:5446
  • Health & Telemetry: http://localhost:5446/api/health
  • MCP SSE Transport: http://localhost:5446/mcp/sse
  • Google OAuth Flow: http://localhost:5446/auth/google

šŸ› ļø MCP Integration (Antigravity, Cursor, Claude Code)

SSE Transport (http://localhost:5446/mcp/sse)

{
  "mcpServers": {
    "g-krusch": {
      "url": "http://localhost:5446/mcp/sse"
    }
  }
}

Stdio Transport

{
  "mcpServers": {
    "g-krusch": {
      "command": "node",
      "args": ["/absolute/path/to/G-krusch/src/index.js", "--stdio"]
    }
  }
}

🧰 Exposed MCP Tools (12 Tools)

ToolDescription
get_agent_steeringRetrieves active agent.md steering directives directly from Google Drive.
search_drive_ragHybrid semantic vector + FTS5 BM25 keyword search across all indexed files in Google Drive.
read_drive_fileReads any document from Drive (exports Google Docs, Sheets, Slides & PDFs cleanly to Markdown/CSV).
write_drive_fileCreates or updates Markdown files, native Google Docs (.gdoc), Google Sheets (.gsheet), or Google Slides presentations (.slides, with Notes: speaker notes) in the workspace.
delete_drive_fileSoft-trashes a file in the G-Krusch Google Drive workspace.
list_drive_workspaceLists all folders and files in the G-Krusch Drive hierarchy.
sync_drive_ragTriggers an incremental scan and embedding sync of Google Drive files.
get_workspace_statusReports OAuth connection health, indexed file count, and cached embedding statistics.
list_calendar_eventsLists upcoming events from the user's primary Google Calendar with optional query and time window.
create_calendar_eventSchedules a new event or reservation hold on the user's primary Google Calendar.
search_gmail_messagesSearches Gmail messages using standard Gmail operators (is:unread, from:...).
compose_gmail_messageCreates an RFC-2822 / RFC-2047 sanitized Gmail draft or sends an email immediately (send_immediately: true).

ā˜ļø Google Workspace Extension REST APIs (Krusch Companion Bridge)

In addition to its MCP server, G-Krusch exposes REST Extension APIs on port 5446 consumed by krusch-companion's <holodata> Dual-Engine Agentic Proxy:

MethodEndpointDescription
GET/api/healthReports SQLite WAL health, OAuth status, Krusch-Nexus PDF engine status, RAG counts, and active extensions.
GET/api/steeringRetrieves agent.md cloud steering directives (?refresh=true to bypass cache).
PUT/api/steeringUpdates agent.md steering content in Google Drive.
GET/api/workspace/treeReturns recursive folder & file tree for the G-Krusch Google Drive workspace.
GET/api/rag/search?q=...Hybrid semantic + FTS5 BM25 search across indexed Google Drive documents (gkrusch_drive).
POST/api/rag/syncIncrementally indexes workspace documents into SQLite vector + FTS5 tables.
GET/api/drive/read?path=...Reads a Google Drive file or exports a Google Doc, Sheet, Slides deck, or PDF (gkrusch_drive).
POST/api/drive/writeCreates or updates a Markdown file, native Google Doc (.gdoc), Google Sheet (.gsheet), or Google Slides deck (.slides) inside the G-Krusch Drive workspace (gkrusch_drive).
DELETE/api/drive/fileSoft-trashes a file by path or fileId.
GET/api/calendar/eventsLists upcoming events from the user's primary Google Calendar (gkrusch_calendar).
POST/api/calendar/eventsSchedules a new Google Calendar event ({ summary, startTime, endTime, description }) (gkrusch_calendar).
GET/api/gmail/messages?q=...Searches Gmail messages and returns sender, subject, date, and snippet previews (gkrusch_gmail).
POST/api/gmail/draftsEncodes a CRLF-sanitized RFC-2822 / RFC-2047 MIME message and creates a Gmail draft (sendImmediately: false) or sends immediately (gkrusch_gmail / concierge_reservation).
POST/api/gmail/sendSends a CRLF-sanitized RFC-2822 / RFC-2047 MIME email immediately via Gmail (sendImmediately: true).

šŸ“„ License

MIT Ā© kruschdev. Part of the Krusch Homelab Sovereign AI Ecosystem.