lighthouse

README

Lighthouse

Build GraphQL APIs in Go. Fast.

Documentation • Quick Start • 中文

---

What is Lighthouse?

Lighthouse is a batteries-included GraphQL framework for Go. Define your schema, run one command, and get a production-ready API with DataLoaders, authentication, and database migrations.

type User @loader(keys: ["id"]) {
  id: ID!
  name: String! @varchar(length: 100)
  posts: [Post!]! @goField(forceResolver: true)
}

extend type Query {
  me: User! @auth
}

lighthouse generate:schema  # That's it. Models, resolvers, dataloaders generated.

Features

Feature	Description
Schema-First	Define GraphQL schema, generate Go code
DataLoader	Auto-generated, N+1 problem solved
Auth Directives	@auth, @own built-in
Database	GORM + MySQL, connection pooling, master-slave
Migrations	Atlas-powered schema migrations
Queue	Redis-based async jobs (asynq)
Messaging	NATS pub/sub for real-time
Storage	S3/MinIO/COS unified interface
Metrics	Prometheus + health checks
MCP	AI-powered development with Claude Code

5-Minute Start

# Install
go install github.com/light-speak/lighthouse@latest

# Create project
lighthouse generate:init --module github.com/you/myapp --models user,post
cd myapp

# Configure .env, then run
go run . app:start

Open http://localhost:8080 → GraphQL Playground ready.

Project Structure

myapp/
├── schema/          # GraphQL definitions
├── models/          # Generated Go structs
├── resolver/        # Your business logic
├── graph/           # gqlgen generated (don't touch)
├── commands/        # CLI commands
├── server/          # HTTP server setup
└── migrations/      # Database migrations

Tech Stack

• gqlgen - GraphQL engine
• GORM - ORM
• Atlas - Migrations
• asynq - Job queue
• NATS - Messaging
• zerolog - Logging

MCP Integration

Lighthouse includes built-in Model Context Protocol (MCP) support, enabling AI assistants like Claude Code to understand and work with your Lighthouse projects.

Setup

Option 1: Using CLI (Recommended)

# Install lighthouse first
go install github.com/light-speak/lighthouse@latest

# Add MCP server to Claude Code
claude mcp add lighthouse -- lighthouse mcp

Option 2: Manual Configuration

Add to .mcp.json in your project root (for team sharing):

{
  "mcpServers": {
    "lighthouse": {
      "type": "stdio",
      "command": "lighthouse",
      "args": ["mcp"]
    }
  }
}

Or add to ~/.claude.json (for personal use across projects):

{
  "mcpServers": {
    "lighthouse": {
      "command": "lighthouse",
      "args": ["mcp"]
    }
  }
}

Verify Installation

# Check if MCP server is registered
claude mcp list

What AI Can Do

Capability	Description
Generate Code	Create schemas, resolvers, commands, tasks
Query Docs	Get directive usage (@loader, @auth, etc.)
Config Help	Database, Redis, queue configuration
Run Commands	Execute any lighthouse CLI command
Read Examples	Access schema, resolver, dataloader examples

Available Tools

generate_schema      - Generate GraphQL schema and models
generate_dataloader  - Generate DataLoader code
generate_command     - Create new CLI command
generate_task        - Create async queue task
init_project         - Initialize new project
get_directive_info   - Get directive documentation
get_config_info      - Get configuration docs
list_generators      - List all generators
search_docs          - Search framework docs
run_command          - Run any lighthouse command

Documentation

📚 Full Documentation

• Getting Started
• Schema Basics
• DataLoader
• Authentication
• Database

Contributing

PRs welcome. Open an issue first for major changes.

License

MIT

---

_{Built with ☕ by Light Speak}