https://github.com/spencerjireh/folionaut
A TypeScript/Express backend for portfolio websites featuring a flexible CMS, AI-powered chat with tool use, and Model Context Protocol (MCP) server integration.
https://github.com/spencerjireh/folionaut
ai-chat bun cms drizzle-orm express mcp portfolio rest-api turso typescript
Last synced: 3 months ago
JSON representation
A TypeScript/Express backend for portfolio websites featuring a flexible CMS, AI-powered chat with tool use, and Model Context Protocol (MCP) server integration.
- Host: GitHub
- URL: https://github.com/spencerjireh/folionaut
- Owner: spencerjireh
- License: mit
- Created: 2026-02-09T03:05:50.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-22T22:37:01.000Z (5 months ago)
- Last Synced: 2026-02-23T03:38:46.491Z (5 months ago)
- Topics: ai-chat, bun, cms, drizzle-orm, express, mcp, portfolio, rest-api, turso, typescript
- Language: TypeScript
- Homepage: https://spencerjireh.github.io/folionaut/
- Size: 3.02 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Folionaut
AI & MCP enhanced portfolio content management system
Documentation •
API Reference •
Quick Start
---
## Overview
A TypeScript/Express backend for portfolio websites featuring a flexible CMS, AI-powered chat with tool use, and Model Context Protocol (MCP) server integration.
### Key Features
- **Flexible CMS** - Free-form JSON content with versioning, soft delete, and full audit trail
- **AI Chat** - Rate-limited chat with PII obfuscation and tool use for content queries
- **MCP Server** - Expose content tools to AI assistants via Model Context Protocol
- **Resilient** - Circuit breaker for LLM, token bucket rate limiting, graceful degradation
- **Observable** - OpenTelemetry tracing, Prometheus metrics, structured logging
## Tech Stack
Bun
Express
TypeScript
Turso
Drizzle
Redis
Zod
OTel
Prometheus
## Quick Start
```bash
# Install
bun install
# Configure
cp .env.example .env
# Edit .env with your Turso and API keys
# Database
bun run db:migrate
# Run
bun run dev
```
See the [Configuration Guide](https://spencerjireh.github.io/folionaut/guide/configuration.html) for environment variables.
## API
### Public
| Endpoint | Description |
|----------|-------------|
| `GET /api/v1/content` | List published content |
| `GET /api/v1/content/:type/:slug` | Get content item |
| `GET /api/v1/content/bundle` | Get all content |
| `POST /api/v1/chat` | Chat with AI |
| `GET /api/health` | Health check |
| `GET /api/metrics` | Prometheus metrics |
### Admin
Requires `X-Admin-Key` header.
| Endpoint | Description |
|----------|-------------|
| `POST /api/v1/admin/content` | Create content |
| `PUT /api/v1/admin/content/:id` | Update content |
| `DELETE /api/v1/admin/content/:id` | Soft delete |
| `GET /api/v1/admin/content/:id/history` | Version history |
| `POST /api/v1/admin/content/:id/restore` | Restore version |
Full specification: [API Reference](https://spencerjireh.github.io/folionaut/api/reference.html)
## Architecture
```
src/
├── routes/ # HTTP handlers
├── services/ # Business logic
├── repositories/ # Data access
├── middleware/ # Express middleware
├── cache/ # Redis with memory fallback
├── resilience/ # Rate limiter, circuit breaker
├── events/ # Typed event emitter
├── llm/ # LLM provider abstraction
├── tools/ # Shared tools (chat & MCP)
├── mcp/ # MCP server (stdio transport)
└── observability/ # Metrics, tracing
```
See [Architecture Overview](https://spencerjireh.github.io/folionaut/architecture/) for details.
## Documentation
| Topic | Link |
|-------|------|
| Getting Started | [Quick Start Guide](https://spencerjireh.github.io/folionaut/guide/quick-start.html) |
| Configuration | [Environment & Settings](https://spencerjireh.github.io/folionaut/guide/configuration.html) |
| Architecture | [High-Level Design](https://spencerjireh.github.io/folionaut/architecture/high-level-design.html) |
| API | [OpenAPI Reference](https://spencerjireh.github.io/folionaut/api/reference.html) |
| MCP Server | [Integration Guide](https://spencerjireh.github.io/folionaut/integrations/mcp-server.html) |
| Operations | [Runbook](https://spencerjireh.github.io/folionaut/operations/runbook.html) |
## Scripts
```bash
bun run dev # Development server
bun run build # Production build
bun run test # Run tests
bun run lint # Lint code
bun run db:studio # Drizzle Studio GUI
bun run mcp # Start MCP server
```
## License
This project is licensed under the [MIT License](LICENSE).