Gentleman Book MCP

🚀 Gentleman Book MCP Server

This is an MCP (Model Context Protocol) server that enables AI assistants like Claude to access, search, and understand the content of the Gentleman Programming Book. It directly connects AI assistants to 18 chapters of software architecture knowledge, best practices, and development wisdom.

🚀 Quick Start

Once configured, restart Claude Desktop and start chatting to use the server's features.

✨ Features

🔧 Level 1: Basic Tools

📦 Level 2: Resources & Prompts

🧠 Level 3: Semantic Search (AI-Powered)

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

📚 Documentation

Configuration

Environment Variables

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

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:

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

🔧 Technical Details

The server codebase is organized as follows:

• cmd/server: The entry point of the MCP server.
• internal/book: Contains data structures and an MDX file parser.
• internal/embeddings: Implements the semantic search engine.

📄 License

This project is under the 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