📚 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