AI导哈

BookStack文档管理服务

一个用于管理BookStack文档的Python MCP服务器，支持内容列表、搜索、页面管理等功能。

  • by lborjigi
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 lborjigi/bookstack-mcp

使用说明

BookStack MCP游标服务器

一个最小的Python MCP（模型上下文协议）服务器，允许Cursor AI管理您的BookStack文档。

特性

此服务器提供基本的BookStack管理工具：

  • 列表内容：浏览书籍、书架、章节和页面
  • 搜索：对所有内容进行全文搜索
  • 页面管理：创建、读取、更新和删除页面
  • 图书管理：创建新书
  • 章节管理：创建新章节

先决条件

  • Python 3.8或更高版本
  • 具有API访问权限的BookStack实例
  • BookStack API令牌（ID和Secret）

设置

1.安装依赖项

pip install -r requirements.txt

2.配置环境

首先，您需要在BookStack中创建一个API令牌：

  1. 登录到您的BookStack实例http://192.168.1.193:6875
  2. 转到您的个人资料→ API令牌
  3. 创建具有适当权限的新令牌
  4. 复制令牌ID和令牌密钥

然后创建一个 .env 文件：

cp .env.example .env

编辑 .env 并添加您的BookStack凭据：

BS_URL=http://192.168.1.193:6875
BS_TOKEN_ID=your_actual_token_id
BS_TOKEN_SECRET=your_actual_token_secret

3.测试服务器

直接运行服务器进行测试：

python server.py

服务器将启动并通过stdio监听MCP协议消息。

光标集成

要将此MCP服务器与Cursor一起使用，请将其添加到Cursor MCP设置中：

  1. 打开光标设置（Cmd/Ctrl+，）
  2. 导航至 特性 → 模型上下文协议
  3. 添加新的服务器配置：
{
  "mcpServers": {
    "bookstack": {
      "command": "python",
      "args": ["/home/borjigin/dev/bookstack-mcp/server.py"],
      "env": {
        "BS_URL": "http://192.168.1.193:6875",
        "BS_TOKEN_ID": "your_token_id",
        "BS_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}

或者使用脚本包装器：

{
  "mcpServers": {
    "bookstack": {
      "command": "/home/borjigin/dev/bookstack-mcp/run_server.sh"
    }
  }
}
  1. 重新启动游标

可用工具

配置后，您可以要求Cursor与BookStack交互：

列表内容

  • “列出BookStack中的所有书籍”
  • “给我看第五册的章节”
  • “查找名称中包含“API”的页面”

搜索

  • “在BookStack中搜索“身份验证””
  • “查找有关Docker的文档”

阅读内容

  • “获取第42页的内容”
  • “显示页面ID 10中的内容”

创建内容

  • “创建一本名为“API文档”的新书”
  • “在第5册中创建一个名为“入门”的章节”
  • “在第3册中创建一个包含降价内容的页面…”

更新内容

  • “更新第15页，将标题更改为“新标题””
  • “使用此标记修改第20页的内容…”

删除内容

  • “删除第99页”

工具参考

书架_列表_内容

列出内容实体（书籍、书架、章节、页面）

  • entity_type：“书籍”|“书架”|“章节”|“页面”
  • count：项目数（默认值为20）
  • offset：分页偏移量（默认值0）
  • filter_name：按名称子字符串筛选

书架_搜索

搜索所有内容

  • query：搜索查询字符串
  • page：页码（默认1）
  • count：每页结果数（默认值为20）

书架_get_page

获取页面详细信息和内容

  • page_id：页面ID

书架_创意_页面

创建新页面

  • book_id：图书ID（必填）
  • name：页面标题（必填）
  • html 或 markdown：内容（需要一个）
  • chapter_id：可选章节ID
  • tags：可选标记（格式：“tag1=value1，tag2=value2”）

书架更新页面

更新现有页面

  • page_id：页面ID（必填）
  • name：新标题（可选）
  • html 或 markdown：新内容（可选）
  • tags：可选标签

bookback_delete_page

删除页面

  • page_id：页面ID（必填）

书架_创意_书籍

创建新书

  • name：书名（必填）
  • description：可选描述
  • tags：可选标签

书架_创意_触觉

创建新章节

  • book_id：图书ID（必填）
  • name：章节名称（必填）
  • description：可选描述
  • tags：可选标签

故障排除

连接问题

如果Cursor无法连接到BookStack：

  1. 验证BookStack是否正在运行： curl http://192.168.1.193:6875
  2. 检查您的API令牌是否正确
  3. 确保令牌具有足够的权限

权限问题

如果你收到403个错误：

  • 您的API令牌可能缺少必要的权限
  • 创建具有管理员或适当角色权限的新令牌

服务器未启动

如果Python服务器无法启动：

  • 检查Python版本： python --version （必须为3.8+）
  • 验证依赖关系： pip list | grep fastmcp
  • 检查中的错误 .env 文件

发展

要使用更多工具扩展此服务器，请执行以下操作：

  1. 添加装饰有新功能 @mcp.tool()
  2. 使用 BookStackClient 用于API调用
  3. 遵循现有工具的模式

例子：

@mcp.tool()
async def bookstack_custom_operation(param: str) -> str:
    """Your custom tool description"""
    client = get_client()
    result = await client.request("GET", f"endpoint/{param}")
    return str(result)

api参考

BookStack API文档：https://www.bookstackapp.com/docs/api/

许可证

这个项目是开源的，可以修改和使用。

相关 MCP