JinDaGe - gentleman-book-mcp MCP Details

article

README

🚀 绅士编程书籍MCP服务器

本项目是一个MCP（模型上下文协议）服务器，能让Claude等AI助手读取、搜索和理解绅士编程书籍的内容。相当于为你的AI助手直接打通了获取18章软件架构知识、最佳实践和开发智慧的渠道。

🚀 快速开始

本项目是一个 MCP（模型上下文协议）服务器，允许Claude等AI助手读取、搜索和理解绅士编程书籍的内容。可以将其视为为你的AI助手提供了一条直达18章软件架构知识、最佳实践和开发智慧的通道。

✨ 主要特性

🔧 一级：基础工具

| 工具 | 描述 | | ---- | ---- | | list_chapters | 列出所有18章及元数据 | | read_chapter | 读取任意章节或特定部分 | | search_book | 基于关键词搜索所有内容 | | get_book_index | 完整的目录 |

📦 二级：资源与提示

| 类型 | 名称 | 描述 | | ---- | ---- | ---- | | 资源 | book://index/es | 西班牙语目录 | | 资源 | book://index/en | 英语目录 | | 提示 | explain_concept | 解释书中的任何概念 | | 提示 | compare_patterns | 比较架构模式 | | 提示 | summarize_chapter | 获取章节摘要 |

🧠 三级：语义搜索（人工智能驱动）

| 工具 | 描述 | | ---- | ---- | | semantic_search | 使用嵌入向量进行自然语言搜索 | | build_semantic_index | 构建向量索引 | | semantic_status | 检查语义引擎状态 |

支持使用OpenAI和Ollama进行嵌入向量生成。

📦 安装指南

前提条件

Go 1.21或更高版本
本地克隆的绅士编程书籍

从源代码构建

# 克隆此仓库
git clone https://github.com/Alan-TheGentleman/gentleman-book-mcp.git
cd gentleman-book-mcp

# 构建二进制文件
go build -o bin/gentleman-book-mcp ./cmd/server

# 二进制文件现在位于 ./bin/gentleman-book-mcp

验证安装

./bin/gentleman-book-mcp --help

📚 详细文档

配置

环境变量

| 变量 | 描述 | 默认值 | | ---- | ---- | ---- | | BOOK_PATH | 书籍MDX文件的路径 | ~/work/gentleman-programming-book/src/data/book | | OPENAI_API_KEY | OpenAI API密钥（用于语义搜索） | - | | OLLAMA_BASE_URL | Ollama服务器URL | http://localhost:11434 | | OLLAMA_EMBEDDING_MODEL | 用于嵌入向量的Ollama模型 | nomic-embed-text |

Claude桌面端设置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %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"
      }
    }
  }
}

使用OpenAI（用于语义搜索）

{
  "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-..."
      }
    }
  }
}

使用Ollama（免费、本地）

安装 Ollama
拉取嵌入向量模型：ollama pull nomic-embed-text
启动Ollama：ollama serve
使用标准配置（自动检测Ollama）

使用方法

配置完成后，重启Claude桌面端并开始聊天！

示例对话

列出章节：

你：绅士编程书籍有哪些章节？
Claude：[使用 list_chapters] 本书有18章，涵盖...

读取特定内容：

你：给我读一下关于六边形架构的章节
Claude：[使用 read_chapter] 这是六边形架构章节...

搜索主题：

你：在书中查找关于TDD的信息
Claude：[使用 search_book] 我找到了几处关于TDD的提及...

语义搜索（如果已配置）：

你：我应该如何构建一个可维护的React应用程序？
Claude：[使用 semantic_search] 根据书中的建议...

使用提示：

你：根据这本书解释一下干净架构
Claude：[使用 explain_concept 提示] 根据绅士编程书籍...

书籍内容

服务器提供对18章英语和西班牙语内容的访问： | 序号 | 章节 | 主题 | | ---- | ---- | ---- | | 1 | 干净敏捷 | 敏捷、瀑布、XP、TDD | | 2 | 沟通 | 远程工作、团队动态 | | 3 | 六边形架构 | 端口、适配器、领域 | | 4 | Go语言 | Go基础 | | 5 | NVIM指南 | Neovim设置和使用 | | 6 | 算法 | 大O表示法、搜索、排序 | | 7 | 干净架构 | 层、用例、领域 | | 8 | 前端干净架构 | 范围规则、前端模式 | | 9 | React | 钩子、状态、组合 | | 10 | TypeScript | 类型、接口、模式 | | 11 | 前端雷达 | 框架比较 | | 12 | Angular | 组件、服务、测试 | | 13 | 桶模块 | 模块组织 | | 14 | 前端历史 | 网络演变 | | 15 | 人工智能驱动的开发 | Claude代码、人工智能工作流 | | 16 | 前端手册 | 测试、安全、性能 | | 17 | 软技能 | 领导力、沟通 | | 18 | 软件架构 | 微服务、模式 |

架构

gentleman-book-mcp/
├── cmd/
│   └── server/
│       └── main.go              # MCP服务器入口点
├── internal/
│   ├── book/
│   │   ├── models.go            # 数据结构
│   │   └── parser.go            # MDX文件解析器
│   └── embeddings/
│       └── embeddings.go        # 语义搜索引擎
├── go.mod
├── go.sum
├── README.md                    # 英语文档
└── README.es.md                 # 西班牙语文档

开发

# 在开发模式下运行
go run ./cmd/server

# 构建
go build -o bin/gentleman-book-mcp ./cmd/server

# 使用MCP检查器测试
npx @anthropic-ai/mcp-inspector ./bin/gentleman-book-mcp

故障排除

"书籍路径不存在"

确保 BOOK_PATH 环境变量指向书籍MDX文件的正确位置。

"语义搜索不可用"

设置 OPENAI_API_KEY 或确保Ollama正在运行并安装了嵌入向量模型。

服务器无响应

检查二进制文件是否有执行权限：chmod +x ./bin/gentleman-book-mcp

贡献

欢迎贡献！可以自由地：

报告错误
建议新功能
提交拉取请求

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

gentleman-book-mcp