BookStack MCP 服务器

这是一个提供从BookStack搜索页面工具的模型上下文协议（MCP）服务器。该服务器与BookStack API交互，并提供经过干净HTML到文本转换的结构化数据。

功能

• 使用可定制查询搜索BookStack中的页面
• 获取包括标题、URL和内容在内的结构化数据
• 可配置分页（页数和数量）
• HTML到文本转换以实现干净的内容阅读
• 清晰的错误处理和验证

安装

通过Smithery安装

要通过Smithery自动安装mcp-bookstack用于Claude桌面应用：

npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude

手动安装

1. 克隆仓库：

git clone https://github.com/yellowgg2/mcp-bookstack.git
cd mcp-bookstack

2. 安装依赖：

npm install

3. 配置环境：

创建一个.env文件，其中包含您的BookStack API凭证，或在MCP设置配置文件中提供它们：

BOOKSTACK_API_TOKEN=your_token
BOOKSTACK_API_URL=your_bookstack_url
BOOKSTACK_API_KEY=your_api_key

4. 构建服务器：

npm run build

5. 添加到您的MCP设置配置文件（位置取决于您的系统）：

对于VSCode Claude扩展：

{
  "mcpServers": {
    "bookstack": {
      "command": "node",
      "args": ["/path/to/mcp-bookstack/build/app.js"],
      "env": {
        "BOOKSTACK_API_URL": "your_bookstack_url",
        "BOOKSTACK_API_TOKEN": "your_token",
        "BOOKSTACK_API_KEY":  "your_api_key"
      }
    }
  }
}

使用

该服务器提供了一个名为search_pages的工具，可用于搜索BookStack中的页面。

工具：search_pages

参数：

• query (字符串)：用于搜索页面的查询
  • 默认值：""（空字符串）
• page (数字)：要返回的页数
  • 范围：1-10
  • 默认值：1
• count (数字)：要返回的页面数量
  • 范围：1-30
  • 默认值：10

示例用法：

使用_mcp_tool：
server_name: "bookstack"
tool_name: "search_pages"
参数: {
  "query": "知识库",
  "page": 1,
  "count": 5
}

示例输出：

# 页面标题

页面内容以纯文本格式呈现...

来源：https://your-bookstack-url/page-url

与Claude集成

要使用此MCP服务器与Claude集成，您需要：

1. 安装Claude桌面应用或VSCode Claude扩展
2. 在您的设置中配置MCP服务器
3. 使用Claude的自然语言界面与BookStack互动

配置

对于Claude桌面应用、VSCode Claude扩展和Cursor，添加服务器配置到：

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "bookstack": {
      "command": "node",
      "args": ["/path/to/mcp-bookstack/build/app.js"],
      "env": {
        "BOOKSTACK_API_URL": "your_bookstack_url",
        "BOOKSTACK_API_TOKEN": "your_token",
        "BOOKSTACK_API_KEY": "your_api_key"
      }
    }
  }
}

示例互动

一旦配置完成，您可以使用自然语言与Claude互动以搜索BookStack页面。示例：

• "搜索关于我们BookStack知识库中的API使用的文档"
• "查找关于内部文档中部署的信息"
• "在BookStack中查找安全指南"

Claude将自动使用适当的参数来搜索您想要的页面。

页面响应结构

每个页面响应包括：

• 页面标题
• 页面全文内容（从HTML转换为纯文本）
• 原始页面的源URL

HTML到文本转换处理：

• HTML实体解码
• 换行符和段落格式
• 列表项及其项目符号
• 移除HTML标签
• 空白规范化

开发

服务器构建使用：

• TypeScript
• 模型上下文协议SDK
• Axios进行API请求
• Zod进行数据验证
• dotenv进行环境配置

要修改服务器：

1. 修改src/app.ts
2. 重新构建：

npm run build

错误处理

服务器包括强大的错误处理机制，针对：

• API连接失败
• 认证问题
• 参数值无效
• 数据解析错误

错误以适当的错误代码和描述性消息返回。

贡献

欢迎贡献！请随意提交Pull Request。

许可

MIT许可 - 欢迎在自己的项目中使用。