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.
Badge for your README
Markdown
[](/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
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)
- # 📚 Gentleman Book MCP Server
- <p align="center">
- <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go Version">
- <img src="https://img.shields.io/badge/MCP-1.0-purple?style=for-the-badge" alt="MCP Version">
- <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
- </p>
- <p align="center">
- <b>Give AI assistants direct access to the Gentleman Programming Book</b>
- </p>
- <p align="center">
- <a href="#features">Features</a> •
- <a href="#installation">Installation</a> •
- <a href="#configuration">Configuration</a> •
- <a href="#usage">Usage</a> •
- <a href="./README.es.md">Español</a>
- </p>
- ---
- ## 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
- ---
- <p align="center">
- Made with ❤️ by <a href="https://github.com/Alan-TheGentleman">Gentleman Programming</a>
- </p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.