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](https://github.com/Alan-TheGentleman/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](https://github.com/Alan-TheGentleman/gentleman-programming-book) cloned locally ### Build from source ```bash # 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 ```bash ./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): ```json { "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) ```json { "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](https://ollama.ai) 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 ```bash # 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](LICENSE) for details. ## Related Projects - [Gentleman Programming Book](https://github.com/Alan-TheGentleman/gentleman-programming-book) - The book itself - [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification - [mcp-go](https://github.com/mark3labs/mcp-go) - Go SDK for MCP ---Made with β€οΈ by Gentleman Programming