Skip to content
Back to search

gentleman-book-mcp

MCP Server for Gentleman Programming Book - Give AI assistants direct access to 18 chapters of software architecture knowledge

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alan-thegentleman--gentleman-book-mcp/badge.svg)](/listings/alan-thegentleman--gentleman-book-mcp)

HTML

<a href="/listings/alan-thegentleman--gentleman-book-mcp"><img src="/api/listings/alan-thegentleman--gentleman-book-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Go 1.21 or higher - The [Gentleman Programming Book](https://github.com/Alan-TheGentleman/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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 271 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 📚 Gentleman Book MCP Server
  2. <p align="center">
  3. <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go Version">
  4. <img src="https://img.shields.io/badge/MCP-1.0-purple?style=for-the-badge" alt="MCP Version">
  5. <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
  6. </p>
  7. <p align="center">
  8. <b>Give AI assistants direct access to the Gentleman Programming Book</b>
  9. </p>
  10. <p align="center">
  11. <a href="#features">Features</a> •
  12. <a href="#installation">Installation</a> •
  13. <a href="#configuration">Configuration</a> •
  14. <a href="#usage">Usage</a> •
  15. <a href="./README.es.md">Español</a>
  16. </p>
  17. ---
  18. ## What is this?
  19. 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).
  20. Think of it as giving your AI assistant a direct line to 18 chapters of software architecture knowledge, best practices, and development wisdom.
  21. ## Features
  22. ### 🔧 Level 1: Basic Tools
  23. | Tool | Description |
  24. | ---------------- | --------------------------------------- |
  25. | `list_chapters` | List all 18 chapters with metadata |
  26. | `read_chapter` | Read any chapter or specific section |
  27. | `search_book` | Keyword-based search across all content |
  28. | `get_book_index` | Complete table of contents |
  29. ### 📦 Level 2: Resources & Prompts
  30. | Type | Name | Description |
  31. | -------- | ------------------- | --------------------------------- |
  32. | Resource | `book://index/es` | Spanish table of contents |
  33. | Resource | `book://index/en` | English table of contents |
  34. | Prompt | `explain_concept` | Explain any concept from the book |
  35. | Prompt | `compare_patterns` | Compare architectural patterns |
  36. | Prompt | `summarize_chapter` | Get chapter summaries |
  37. ### 🧠 Level 3: Semantic Search (AI-Powered)
  38. | Tool | Description |
  39. | ---------------------- | ---------------------------------------- |
  40. | `semantic_search` | Natural language search using embeddings |
  41. | `build_semantic_index` | Build the vector index |
  42. | `semantic_status` | Check semantic engine status |
  43. **Supports both OpenAI and Ollama** for embeddings generation.
  44. ## Installation
  45. ### Prerequisites
  46. - Go 1.21 or higher
  47. - The [Gentleman Programming Book](https://github.com/Alan-TheGentleman/gentleman-programming-book) cloned locally
  48. ### Build from source
  49. ```bash
  50. # Clone this repository
  51. git clone https://github.com/Alan-TheGentleman/gentleman-book-mcp.git
  52. cd gentleman-book-mcp
  53. # Build the binary
  54. go build -o bin/gentleman-book-mcp ./cmd/server
  55. # The binary is now at ./bin/gentleman-book-mcp
  56. ```
  57. ### Verify installation
  58. ```bash
  59. ./bin/gentleman-book-mcp --help
  60. ```
  61. ## Configuration
  62. ### Environment Variables
  63. | Variable | Description | Default |
  64. | ------------------------ | ------------------------------------ | ------------------------------------------------- |
  65. | `BOOK_PATH` | Path to book MDX files | `~/work/gentleman-programming-book/src/data/book` |
  66. | `OPENAI_API_KEY` | OpenAI API key (for semantic search) | - |
  67. | `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` |
  68. | `OLLAMA_EMBEDDING_MODEL` | Ollama model for embeddings | `nomic-embed-text` |
  69. ### Claude Desktop Setup
  70. Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
  71. ```json
  72. {
  73. "mcpServers": {
  74. "gentleman-book": {
  75. "command": "/absolute/path/to/gentleman-book-mcp",
  76. "env": {
  77. "BOOK_PATH": "/path/to/gentleman-programming-book/src/data/book"
  78. }
  79. }
  80. }
  81. }
  82. ```
  83. ### With OpenAI (for semantic search)
  84. ```json
  85. {
  86. "mcpServers": {
  87. "gentleman-book": {
  88. "command": "/absolute/path/to/gentleman-book-mcp",
  89. "env": {
  90. "BOOK_PATH": "/path/to/gentleman-programming-book/src/data/book",
  91. "OPENAI_API_KEY": "sk-..."
  92. }
  93. }
  94. }
  95. }
  96. ```
  97. ### With Ollama (free, local)
  98. 1. Install [Ollama](https://ollama.ai)
  99. 2. Pull an embedding model: `ollama pull nomic-embed-text`
  100. 3. Start Ollama: `ollama serve`
  101. 4. Use the standard configuration (Ollama is auto-detected)
  102. ## Usage
  103. Once configured, restart Claude Desktop and start chatting!
  104. ### Example conversations
  105. **List chapters:**
  106. ```
  107. You: What chapters are in the Gentleman Programming Book?
  108. Claude: [Uses list_chapters] The book has 18 chapters covering...
  109. ```
  110. **Read specific content:**
  111. ```
  112. You: Read me the chapter about hexagonal architecture
  113. Claude: [Uses read_chapter] Here's the hexagonal architecture chapter...
  114. ```
  115. **Search for topics:**
  116. ```
  117. You: Find information about TDD in the book
  118. Claude: [Uses search_book] I found several mentions of TDD...
  119. ```
  120. **Semantic search (if configured):**
  121. ```
  122. You: How should I structure a React application for maintainability?
  123. Claude: [Uses semantic_search] Based on the book's recommendations...
  124. ```
  125. **Use prompts:**
  126. ```
  127. You: Explain clean architecture according to the book
  128. Claude: [Uses explain_concept prompt] According to the Gentleman Programming Book...
  129. ```
  130. ## Book Content
  131. The server provides access to **18 chapters** in both English and Spanish:
  132. | # | Chapter | Topics |
  133. | --- | --------------------------- | ------------------------------ |
  134. | 1 | Clean Agile | Agile, Waterfall, XP, TDD |
  135. | 2 | Communication | Remote work, Team dynamics |
  136. | 3 | Hexagonal Architecture | Ports, Adapters, Domain |
  137. | 4 | GoLang | Go fundamentals |
  138. | 5 | NVIM Guide | Neovim setup and usage |
  139. | 6 | Algorithms | Big O, Search, Sort |
  140. | 7 | Clean Architecture | Layers, Use Cases, Domain |
  141. | 8 | Clean Architecture Frontend | Scope Rule, Frontend patterns |
  142. | 9 | React | Hooks, State, Composition |
  143. | 10 | TypeScript | Types, Interfaces, Patterns |
  144. | 11 | Frontend Radar | Framework comparison |
  145. | 12 | Angular | Components, Services, Testing |
  146. | 13 | Barrels | Module organization |
  147. | 14 | Frontend History | Web evolution |
  148. | 15 | AI-Driven Development | Claude Code, AI workflows |
  149. | 16 | Frontend Manual | Testing, Security, Performance |
  150. | 17 | Soft Skills | Leadership, Communication |
  151. | 18 | Software Architecture | Microservices, Patterns |
  152. ## Architecture
  153. ```
  154. gentleman-book-mcp/
  155. ├── cmd/
  156. │ └── server/
  157. │ └── main.go # MCP server entry point
  158. ├── internal/
  159. │ ├── book/
  160. │ │ ├── models.go # Data structures
  161. │ │ └── parser.go # MDX file parser
  162. │ └── embeddings/
  163. │ └── embeddings.go # Semantic search engine
  164. ├── go.mod
  165. ├── go.sum
  166. ├── README.md # English documentation
  167. └── README.es.md # Spanish documentation
  168. ```
  169. ## Development
  170. ```bash
  171. # Run in development mode
  172. go run ./cmd/server
  173. # Build
  174. go build -o bin/gentleman-book-mcp ./cmd/server
  175. # Test with MCP Inspector
  176. npx @anthropic-ai/mcp-inspector ./bin/gentleman-book-mcp
  177. ```
  178. ## Troubleshooting
  179. ### "Book path does not exist"
  180. Make sure the `BOOK_PATH` environment variable points to the correct location of the book's MDX files.
  181. ### "Semantic search not available"
  182. Either set `OPENAI_API_KEY` or ensure Ollama is running with an embedding model installed.
  183. ### Server not responding
  184. Check that the binary has execute permissions: `chmod +x ./bin/gentleman-book-mcp`
  185. ## Contributing
  186. Contributions are welcome! Feel free to:
  187. - Report bugs
  188. - Suggest new features
  189. - Submit pull requests
  190. ## License
  191. MIT License - see [LICENSE](LICENSE) for details.
  192. ## Related Projects
  193. - [Gentleman Programming Book](https://github.com/Alan-TheGentleman/gentleman-programming-book) - The book itself
  194. - [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
  195. - [mcp-go](https://github.com/mark3labs/mcp-go) - Go SDK for MCP
  196. ---
  197. <p align="center">
  198. Made with ❤️ by <a href="https://github.com/Alan-TheGentleman">Gentleman Programming</a>
  199. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.