Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
Thoth is a personal website and Model Context Protocol (MCP) server monorepo. It contains runnable services in apps/, shared libraries in packages/, and infrastructure definitions in infra/.
This guide explains how to prepare your local environment, install dependencies, and run the various components of the Thoth ecosystem.
Sources: README.md:1-12
Prerequisites
You must install the following software versions to ensure compatibility with the Thoth monorepo:
- Node.js: Version 24 or higher.
- pnpm: Version 11 or higher (v12.15.0 is the specified package manager).
- Docker: Required for running infrastructure services via Docker Compose.
- graphify: Optional tool for architecture visualization.
Sources: package.json:6-10, CLAUDE.md:27-31
Development Environment Setup
Thoth uses a pnpm monorepo structure with Turborepo for orchestration. Follow these steps to initialize the project:
- Clone the repository and install dependencies:
pnpm install - Set up environment variables for AI tooling. The
githubMCP server requires a token:export GITHUB_TOKEN=$(gh auth token) - Configure required secrets and environment variables for the API, such as GitHub OAuth credentials and Better Auth secrets.
Sources: README.md:14-22, package.json:11-20, apps/api/spec/auth.md:43-45
Core Configuration Options
| Environment Variable | Description | Source |
|---|---|---|
GITHUB_TOKEN | Token for GitHub MCP server integration. | README.md:20 |
GITHUB_CLIENT_ID | OAuth Client ID for GitHub federation. | apps/api/spec/auth.md:44 |
GITHUB_CLIENT_SECRET | OAuth Client Secret for GitHub federation. | apps/api/spec/auth.md:44 |
BETTER_AUTH_URL | Public base URL and token audience for auth. | apps/api/spec/auth.md:44 |
BETTER_AUTH_SECRET | Signing secret for JWT tokens. | apps/api/spec/auth.md:45 |
Running the Services
You can run the entire stack or individual applications using the following commands:
Running with Docker
Use Docker Compose to manage infrastructure dependencies like databases.
- Start services:
pnpm compose:up - Watch for changes:
pnpm compose:watch - Stop services:
pnpm compose:down
Sources: package.json:28-30
Local Development Commands
The monorepo provides scripts to run applications in parallel or individually.
The diagram above shows the default development flow when starting the monorepo services.
Sources: package.json:12, apps/api/package.json:10, apps/web/package.json:10
Testing and Verification
Thoth enforces strict verification rules through a comprehensive pipeline. You should run the verify command before committing changes.
- Full Verification:
pnpm verifyruns secrets detection, linting, type-checking, architecture rules, dead code analysis, and all tests. - Linting:
pnpm lintuses Biome for code quality checks. - Integration Testing:
pnpm test:integrationruns end-to-end tests for the API and MCP protocols.
Sources: package.json:13-21, apps/api/package.json:13
API and MCP Discovery
The API provides several endpoints for health checks and tool discovery.
| Endpoint | Purpose | Rule Reference |
|---|---|---|
GET /health/live | Basic liveness check. | apps/api/test/infrastructure/http/server.integration.test.ts:107 |
GET /openapi.json | Serves OpenAPI 3.1 documentation. | apps/api/test/infrastructure/http/server.integration.test.ts:95 |
POST /mcp | Main entry point for MCP tool calls. | apps/api/test/infrastructure/http/server.integration.test.ts:143 |
/.well-known/oauth-protected-resource | Metadata for MCP auth discovery. | apps/api/test/infrastructure/http/server.integration.test.ts:121 |
Architecture Overview
Thoth utilizes the Model Context Protocol (MCP) to expose tools to AI clients. Authentication is handled by Better Auth, federating to GitHub.
The sequence above illustrates the authentication flow for private MCP tools.
Sources: apps/api/spec/auth.md:14-23, apps/api/test/infrastructure/http/server.integration.test.ts:251-268
Summary
Setting up Thoth involves installing Node.js 24+, pnpm, and Docker. The development environment relies on pnpm workspaces to manage the API and Web applications, with automated verification scripts ensuring code quality. Key configurations revolve around GitHub OAuth and MCP server tokens to enable the AI-integrated features of the platform.