📚 Gentleman Book MCP Server

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

📦 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

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

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:

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