GeekyGramps-MCP

Status: active Created: 2026-07-01 Owner: Felton Builder: Codex (implementation), Claude (architecture/review)

Purpose

A Fastify-based MCP (Model Context Protocol) gateway providing shared, project-scoped memory to multiple AI coding agents (Claude Code, Codex, Antigravity) working against the same homelab. Backed by PostgreSQL, with per-request token enforcement on every route except a health check, and secrets delivered via an Infisical CRD rather than baked into config.

Built so several agents can read/write a common project memory store without stepping on each other, instead of each agent keeping its own disconnected context.

Structure

src/       Fastify server, DB access, project-key validation, tool policy enforcement
scripts/   DB provisioning/init, MCP reachability diagnostics, agent tmux session launcher, request router
test/      Node built-in test coverage for the token gate, tool policy, and project-key validation
deploy/    k3s app-template values, Infisical secret CRD, fail-closed NetworkPolicy

Stack

• Runtime: Node.js, Fastify
• Storage: PostgreSQL
• Protocol: Model Context Protocol (@modelcontextprotocol/sdk)
• Secrets: Infisical (Kubernetes CRD-based sync)
• Deploy target: k3s, NodePort-only exposure, fail-closed NetworkPolicy

Notes

This is a personal homelab tool, published for portfolio purposes. Deployment values (registry path, service names, CIDRs) are placeholders — the operational runbook used to actually deploy this is kept private, since it contains live infrastructure detail rather than anything reusable outside this specific environment.