📚 Gentleman Book MCP Server

Give AI assistants direct access to the Gentleman Programming Book

Features • Installation • Configuration • Usage • Español

What is this?

This is an MCP (Model Context Protocol) server that allows AI assistants like Claude to read, search, and understand content from the Gentleman Programming Book.

Think of it as giving your AI assistant a direct line to 18 chapters of software architecture knowledge, best practices, and development wisdom.

Features

🔧 Level 1: Basic Tools

Tool	Description
`list_chapters`	List all 18 chapters with metadata
`read_chapter`	Read any chapter or specific section
`search_book`	Keyword-based search across all content
`get_book_index`	Complete table of contents

📦 Level 2: Resources & Prompts

Type	Name	Description
Resource	`book://index/es`	Spanish table of contents
Resource	`book://index/en`	English table of contents
Prompt	`explain_concept`	Explain any concept from the book
Prompt	`compare_patterns`	Compare architectural patterns
Prompt	`summarize_chapter`	Get chapter summaries

🧠 Level 3: Semantic Search (AI-Powered)

Tool	Description
`semantic_search`	Natural language search using embeddings
`build_semantic_index`	Build the vector index
`semantic_status`	Check semantic engine status

Supports both OpenAI and Ollama for embeddings generation.

Installation

Prerequisites

Go 1.21 or higher
The Gentleman Programming Book cloned locally

Build from source

# Clone this repository
git clone https://github.com/Alan-TheGentleman/gentleman-book-mcp.git
cd gentleman-book-mcp

# Build the binary
go build -o bin/gentleman-book-mcp ./cmd/server

# The binary is now at ./bin/gentleman-book-mcp

Verify installation

./bin/gentleman-book-mcp --help

Configuration

Environment Variables

Variable	Description	Default
`BOOK_PATH`	Path to book MDX files	`~/work/gentleman-programming-book/src/data/book`
`OPENAI_API_KEY`	OpenAI API key (for semantic search)	-
`OLLAMA_BASE_URL`	Ollama server URL	`http://localhost:11434`
`OLLAMA_EMBEDDING_MODEL`	Ollama model for embeddings	`nomic-embed-text`

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gentleman-book": {
      "command": "/absolute/path/to/gentleman-book-mcp",
      "env": {
        "BOOK_PATH": "/path/to/gentleman-programming-book/src/data/book"
      }
    }
  }
}

With OpenAI (for semantic search)

{
  "mcpServers": {
    "gentleman-book": {
      "command": "/absolute/path/to/gentleman-book-mcp",
      "env": {
        "BOOK_PATH": "/path/to/gentleman-programming-book/src/data/book",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

With Ollama (free, local)

Install Ollama
Pull an embedding model: ollama pull nomic-embed-text
Start Ollama: ollama serve
Use the standard configuration (Ollama is auto-detected)

Usage

Once configured, restart Claude Desktop and start chatting!

Example conversations

List chapters:

You: What chapters are in the Gentleman Programming Book?
Claude: [Uses list_chapters] The book has 18 chapters covering...

Read specific content:

You: Read me the chapter about hexagonal architecture
Claude: [Uses read_chapter] Here's the hexagonal architecture chapter...

Search for topics:

You: Find information about TDD in the book
Claude: [Uses search_book] I found several mentions of TDD...

Semantic search (if configured):

You: How should I structure a React application for maintainability?
Claude: [Uses semantic_search] Based on the book's recommendations...

Use prompts:

You: Explain clean architecture according to the book
Claude: [Uses explain_concept prompt] According to the Gentleman Programming Book...

Book Content

The server provides access to 18 chapters in both English and Spanish:

#	Chapter	Topics
1	Clean Agile	Agile, Waterfall, XP, TDD
2	Communication	Remote work, Team dynamics
3	Hexagonal Architecture	Ports, Adapters, Domain
4	GoLang	Go fundamentals
5	NVIM Guide	Neovim setup and usage
6	Algorithms	Big O, Search, Sort
7	Clean Architecture	Layers, Use Cases, Domain
8	Clean Architecture Frontend	Scope Rule, Frontend patterns
9	React	Hooks, State, Composition
10	TypeScript	Types, Interfaces, Patterns
11	Frontend Radar	Framework comparison
12	Angular	Components, Services, Testing
13	Barrels	Module organization
14	Frontend History	Web evolution
15	AI-Driven Development	Claude Code, AI workflows
16	Frontend Manual	Testing, Security, Performance
17	Soft Skills	Leadership, Communication
18	Software Architecture	Microservices, Patterns

Architecture

gentleman-book-mcp/
├── cmd/
│   └── server/
│       └── main.go              # MCP server entry point
├── internal/
│   ├── book/
│   │   ├── models.go            # Data structures
│   │   └── parser.go            # MDX file parser
│   └── embeddings/
│       └── embeddings.go        # Semantic search engine
├── go.mod
├── go.sum
├── README.md                    # English documentation
└── README.es.md                 # Spanish documentation

Development

# Run in development mode
go run ./cmd/server

# Build
go build -o bin/gentleman-book-mcp ./cmd/server

# Test with MCP Inspector
npx @anthropic-ai/mcp-inspector ./bin/gentleman-book-mcp

Troubleshooting

"Book path does not exist"

Make sure the BOOK_PATH environment variable points to the correct location of the book's MDX files.

"Semantic search not available"

Either set OPENAI_API_KEY or ensure Ollama is running with an embedding model installed.

Server not responding

Check that the binary has execute permissions: chmod +x ./bin/gentleman-book-mcp

Contributing

Contributions are welcome! Feel free to:

Report bugs
Suggest new features
Submit pull requests

License

MIT License - see LICENSE for details.

Related Projects

Gentleman Programming Book - The book itself
Model Context Protocol - MCP specification
mcp-go - Go SDK for MCP

Made with ❤️ by Gentleman Programming

Gentleman Programming Book