Introduction to Thoth

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• apps/api/spec/auth.md
• apps/api/spec/bio.md
• apps/web/spec/web.md
• apps/api/test/infrastructure/http/server.integration.test.ts

Thoth is a personal website and Model Context Protocol (MCP) server. It provides a platform for managing personal professional information (Bio), sharing links, and offering an AI-driven interaction interface through an MCP-compatible API.

The project is structured as a monorepo containing runnable services, shared libraries, and infrastructure configurations. It focuses on federated authentication via GitHub and provides both public web surfaces and private tool-based interfaces for AI clients.

Sources: README.md:1-5, apps/api/spec/auth.md:10-12

System Architecture

Thoth uses a monorepo layout to separate concerns between the user interface, the backend logic, and shared utilities.

Project Layout

Component	Path	Description
API	apps/api	The backend server providing MCP tools and Bio endpoints.
Web	apps/web	The owner's public personal website frontend.
Core	packages/core	Shared business logic and dependency injection setup.
Utils	packages/utils	Common utilities, error handling, and shared schemas.
UI	packages/ui	Shared React components and design tokens.
Infra	infra/	Terraform configurations for infrastructure.

Sources: README.md:7-12, package.json:1-10

High-Level Component Interaction

The following diagram illustrates how external clients and visitors interact with Thoth's services.

The API server acts as the central hub, handling both standard HTTP requests from the Web frontend and JSON-RPC calls from MCP clients.

Sources: apps/api/spec/auth.md:10-14, apps/web/src/app/layout.tsx:16-20

Authentication and Authorization

Thoth implements an OAuth 2.1 server using Better Auth, specifically for MCP clients. It federates login to GitHub, ensuring the application never handles user passwords directly.

Authentication Flow

When a client attempts to call a private tool without a valid JWT, the system triggers an authentication challenge.

Access Rules

• Public Access: GET /health, /api/auth endpoints, and public tools like get_bio or ask do not require tokens.
• Private Access: Tools that modify data (e.g., create_bio, remember) require a valid JWT.
• User Scoping: Every user-scoped database row carries a userId, and queries filter by this ID to ensure data isolation.

Sources: apps/api/spec/auth.md:16-35, apps/api/test/infrastructure/http/server.integration.test.ts:182-205

Core Modules

Bio Module

The Bio module manages the owner's professional profile, including their name, headline, and "about" section.

• Public Interface: get_bio tool and GET /bio/:handle HTTP route.
• Private Interface: create_bio and update_bio tools for owners to manage their data.
• Validation: Handles must be lowercase, hyphen-separated slugs (max 60 characters).

Sources: apps/api/spec/bio.md:10-30, apps/api/test/modules/bio/interface/bio.tool.integration.test.ts:89-105

Web Frontend

The web application provides a public view of the configured user's bio and social links.

• Revalidation: The home page is rebuilt at most every 5 minutes (300 seconds) if the bio changes.
• Error Handling: The build fails if a required bio field is missing or blank.

Sources: apps/web/spec/web.md:10-18, apps/web/src/app/page.tsx:5-10

API Endpoints and MCP Tools

Standard HTTP Endpoints

Endpoint	Method	Description
/	GET	API status and name.
/health/live	GET	Liveness probe (200 OK).
/health/ready	GET	Readiness probe (503 if degraded).
/bio/:handle	GET	Returns bio data for a specific handle.
/mcp	POST	Entry point for MCP JSON-RPC 2.0 calls.
/openapi.json	GET	OpenAPI 3.1.0 specification.

Sources: apps/api/test/infrastructure/http/server.integration.test.ts:60-120, apps/api/spec/bio.md:46-48

Principal MCP Tools

Tool Name	Privacy	Purpose
get_bio	Public	Retrieves bio details (name, headline, about).
create_bio	Private	Creates a new bio for the authenticated user.
update_bio	Private	Updates the existing bio for the authenticated user.
ask	Public	Interacts with the AI agent regarding a profile.

Sources: apps/api/spec/bio.md:10-15, apps/api/test/infrastructure/http/mcp-auth.middleware.test.ts:46-55

Technical Requirements

Thoth requires a modern Node.js environment and specific environment variables for operation:

• Node.js: Version 24 or higher.
• Package Manager: pnpm 11 or higher.
• Infrastructure: PostgreSQL for data persistence.
• Environment Variables:
  • GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET: For GitHub federation.
  • BETTER_AUTH_SECRET: For JWT signing.
  • SITE_HANDLE: Configures which bio the web frontend displays.

Sources: package.json:5-10, apps/api/spec/auth.md:45-48, apps/web/test/features/bio/bio.api.test.ts:4-7