# GeekyGramps-MCP
![GeekyGramps-MCP](docs/images/ggmcp-logo.jpg)
![GeekyGramps-MCP](docs/images/ggmcp_new.png)

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.