Keelson

An extensible MCP server chassis for building and testing scoped, guardrailed AI access to real systems - files, email, spreadsheets - without handing an assistant the keys to everything.

Keelson is a personal R&D playground and portfolio piece. It exists to answer one question that matters for real deployments: how do you let an AI assistant work inside an existing system safely? Not by giving it everything - by scoping what it can see, redacting what it shouldn't, and enforcing read-only where write is dangerous.

The idea

Everyone understands what a chat AI can do. The unsolved, valuable part is the safety layer around its access: scope it to one folder or label, strip PII before it ever reaches the model, keep destructive operations behind explicit guardrails. Keelson is where those patterns get built and proven.

Architecture (a chassis, not a monolith)

The whole point is that capabilities are pluggable. The core never changes; you drop in new tools and data sources.

• The contract (src/contract.ts) - the fixed shapes everything agrees on. A Document is the universal currency; a DocumentSource is any adapter that can produce Documents; a KeelsonTool is any capability. Tools never know where data came from.
• Adapters (src/sources/) - the only components that know where data physically lives. LocalFolderSource reads a folder today; a Google Drive or Gmail adapter slots in beside it with zero tool changes.
• Tools (src/tools/) - self-contained capabilities. The first is institutional_memory: read-only search across all documents, returns matching passages with their source for a human to read.
• The core / auto-loader (src/server.ts) - scans the tools/ folder and registers whatever it finds. Drop in a file = new capability. Serves over Streamable HTTP with bearer-token auth and DNS-rebinding protection.

Design rule

Read and assemble, never send or decide (for read-only tools). Every retrieval tool returns something a human reviews. Write-capable tools - built and tested against disposable sandbox accounts - live behind explicit guardrails and scoping. The point of the playground is to learn that danger zone safely.

Stack

TypeScript (strict) · Node 22 · @modelcontextprotocol/sdk v1 (stable) · Express 5 · zod 4 · Streamable HTTP transport (stateless).

The MCP SDK is isolated behind a thin server wrapper, so swapping SDK versions is a one-file change that never touches tools or adapters.

Run it

KEELSON_TOKEN="your-token" npx tsx src/server.ts health: curl -s http://127.0.0.1:8765/health MCP: POST /mcp (Bearer auth; JSON-RPC 2.0: initialize, then tools/call)

Roadmap

• Gmail / Google Drive adapters with scoped, read-only OAuth against disposable sandbox accounts
• A redaction layer - strip PII before content reaches the model
• Write-capable tools behind explicit guardrails (the supervised danger zone)
• Additional tools: grant/RFP triage, document-prep, meeting/email digestion
• Sub-agent orchestration (fan-out / fan-in) for multi-step tasks

License

BSD-2-Clause.