📚 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)

1. Install Ollama
2. Pull an embedding model: ollama pull nomic-embed-text
3. Start Ollama: ollama serve
4. 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