星战科技xingzhan.cloud
返回市场
书栈-mcp服务器

书栈-mcp服务器

作者：Derron-Knox3 星标更新：2025-05-25
安装使用来源：spider==github.com

项目介绍

技术文档摘要

📚 BookStack MCP Server

TypeScript Node.js Docker License

一个专业级别的模型上下文协议（MCP）服务器，无缝连接AI助手与BookStack知识管理系统。通过智能自动化改进您的文档工作流程。

由Derron Knox创建 | 展示企业级软件架构和最佳实践

🚀 概述

这个基于TypeScript的MCP服务器提供了一个强大的、生产就绪的接口，用于AI助手与BookStack实例之间的交互。设计时考虑了企业的可扩展性、安全性和可维护性，展示了先进的软件工程原则和现代开发实践。

✨ 主要特性

  • 🛡️ 企业级安全性：基于令牌的身份验证和安全凭证管理
  • 🏗️ 模块化架构：使用TypeScript接口实现职责分离
  • 🔄 完整的CRUD操作：对BookStack内容进行全生命周期管理
  • 🐳 容器就绪：优化的生产Docker设置，支持多阶段构建
  • ⚡ 高性能：优化的API调用，带有适当的错误处理和超时机制
  • 📋 类型安全：完整的TypeScript实现，带有严格的类型检查
  • 🔍 智能搜索：高级的内容发现和过滤功能
  • 📖 智能解析：名称到ID的解析，便于用户操作

🛠️ 可用工具

页面管理

  • create_page - 创建包含HTML/Markdown内容的新页面
  • get_page_content - 根据ID或名称检索页面内容
  • update_page - 修改现有页面（内容、位置、元数据）
  • delete_page - 从BookStack中删除页面

内容发现

  • search_items - 在架子、书籍、章节和页面之间搜索
  • list_books - 列出书籍，支持过滤和分页
  • list_shelves - 浏览架子集合，带有高级选项

书籍管理

  • read_book - 根据ID或名称获取特定书籍的详细信息
  • create_book - 创建新书籍
  • update_book - 修改现有书籍（内容、元数据）
  • delete_book - 从BookStack中删除书籍

高级功能

  • 灵活的目标定位：所有操作均可使用ID或名称
  • 上下文感知解析：自动名称到ID转换
  • 层次导航：支持书籍/章节/页面关系
  • 元数据管理：标签、优先级和组织功能

🏃‍♂️ 快速开始

先决条件

  • Node.js 20+
  • Docker & Docker Compose（用于容器化部署）
  • 具有API访问权限的BookStack实例
  • BookStack API令牌（令牌ID及密钥）

1. 环境配置

# 克隆并配置
git clone <repository-url>
cd bookstack/
cp .env.example .env

# 配置您的BookStack凭证
cat > .env << EOF
BOOKSTACK_URL="https://your-bookstack-instance.com"
BOOKSTACK_API_TOKEN_ID="your_token_id_here"
BOOKSTACK_API_TOKEN_SECRET="your_token_secret_here"
EOF

2. 安装选项

选项A：Docker部署（推荐）

# 生产就绪的容器化部署
docker-compose up --build -d

# 监控日志
docker-compose logs -f bookstack-mcp-server

选项B：本地开发

# 安装依赖
npm install

# 开发模式，支持热重载
npm run watch

# 生产构建
npm run build
npm start

3. 与Claude Desktop集成

添加到您的Claude Desktop配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "bookstack-mcp-server": {
      "command": "node",
      "args": ["/path/to/bookstack/build/index.js"],
      "env": {
        "BOOKSTACK_URL": "https://your-bookstack-instance.com",
        "BOOKSTACK_API_TOKEN_ID": "your_token_id",
        “BOOKSTACK_API_TOKEN_SECRET”: "your_token_secret"
      }
    }
  }
}

🏗️ 架构与最佳实践

项目结构

bookstack/
├── src/
│   ├── types.ts              # TypeScript接口定义
│   ├── utils/
│   │   ├── validation.ts     # 输入验证与净化
│   │   └── api.ts           # API实用程序与辅助函数
│   ├── tools/
│   │   ├── definitions.ts    # 工具模式定义
│   │   └── handlers.ts      # 业务逻辑实现
│   └── index.ts             # 主服务器与编排
├── build/                   # 编译后的JavaScript输出
├── Dockerfile              # 多阶段容器构建
├── docker-compose.yml      # 生产部署配置
└── package.json            # 依赖项与脚本

工程原理展示

🎯 干净架构

  • 职责分离：验证层、业务逻辑层和API交互层分明
  • 依赖注入：模块化设计，清晰的接口
  • 单一责任：每个模块有一个明确的目的

🔒 安全第一

  • 环境变量管理：安全的凭证处理
  • 输入验证：全面的参数净化
  • 错误边界：恰当的异常处理，防止信息泄露

🚀 生产就绪

  • 容器优化：多阶段Docker构建以最小化镜像大小
  • 健康检查：内置容器健康监控
  • 优雅关闭：适当的信号处理以实现干净终止
  • 全面的日志记录：结构化的错误报告和调试

📊 代码质量

  • TypeScript严格模式：全面的类型安全，带有完整的接口
  • 模块化设计：可复用组件，清晰的API
  • 错误处理：健壮的异常管理，带有用户友好的消息

🔧 配置选项

环境变量

变量描述是否必需示例
BOOKSTACK_URLBookStack实例URL✅https://wiki.company.com
BOOKSTACK_API_TOKEN_ID来自BookStack的API令牌ID✅abc123def456
BOOKSTACK_API_TOKEN_SECRET来自BookStack的API令牌密钥✅xyz789uvw012

Docker配置

  • 健康检查：每30秒检查一次，最多重试3次
  • 日志轮转：最大文件大小10MB，保留5个文件
  • 安全性：非root用户执行
  • 资源优化：多阶段构建以提高生产效率

🔍 使用示例

创建内容

// 在特定书籍中创建页面
await createPage({
  name: "API 文档",
  markdown: "# API 指南\n\n综合API文档...",
  book_name: "开发指南",
  tags: [
    { name: "类别", value: "api" },
    { name: "优先级", value: "高" }
  ]
});

内容发现

// 跨所有内容类型搜索
await searchItems({
  query: "Kubernetes 部署",
  count: 20
});

// 根据上下文查找页面
await getPageContent({
  page_name: "部署指南",
  book_name: "基础设施文档"
});

内容管理

// 更新页面内容
await updatePage({
  page_name: "入门指南",
  book_name: "用户手册",
  markdown: "# 更新的入门指南\n...",
  tags: [{ name: "状态", value: "更新" }]
});

🚀 部署选项

生产部署

Docker Swarm

# 在多个节点上扩展
docker stack deploy -c docker-compose.yml bookstack-mcp

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bookstack-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: bookstack-mcp-server
  template:
    metadata:
      labels:
        app: bookstack-mcp-server
    spec:
      containers:
      - name: bookstack-mcp-server
        image: bookstack-mcp-server:latest
        env:
        - name: BOOKSTACK_URL
          valueFrom:
            secretKeyRef:
              name: bookstack-credentials
              key: url

开发工作流

# 开发模式，支持自动重载
npm run watch

# 类型检查
npx tsc --noEmit

# 使用MCP Inspector调试
npm run inspector

🐛 调试与故障排除

MCP Inspector

# 启动调试界面
npm run inspector
# 通过提供的URL在浏览器中访问

常见问题

连接问题

# 验证BookStack的可达性
curl -H "Authorization: Token $BOOKSTACK_API_TOKEN_ID:$BOOKSTACK_API_TOKEN_SECRET" \
     "$BOOKSTACK_URL/api/books"

容器问题

# 检查容器健康状况
docker-compose ps
docker-compose logs bookstack-mcp-server

# 使用新的构建重启
docker-compose down && docker-compose up --build

📋 依赖项

生产依赖项

  • @modelcontextprotocol/sdk: ^0.6.0 - MCP协议实现
  • axios: ^1.9.0 - 用于BookStack API的HTTP客户端

开发依赖项

  • typescript: ^5.3.3 - 类型安全的JavaScript开发
  • @types/node: ^20.11.24 - Node.js类型定义

系统要求

  • Node.js: 20+（推荐长期支持版本）
  • 内存: 最小256MB，推荐512MB
  • 存储: 应用程序需要100MB，额外空间用于日志

🎯 专业展示

此项目展示了以下领域的专业知识：

后端开发

  • RESTful API集成与设计
  • 微服务架构模式
  • 错误处理和弹性模式

DevOps与基础设施

  • 使用Docker的容器化
  • 生产部署策略
  • 配置管理
  • 健康监测与可观测性

软件工程

  • 清晰代码原则
  • 设计模式（策略、工厂、依赖注入）
  • 测试驱动开发思维
  • 文档与可维护性

现代JavaScript/TypeScript

  • 高级TypeScript特性
  • 异步/等待模式
  • ES2022+现代语法
  • Node.js最佳实践

🤝 贡献

欢迎贡献！可以增强的领域包括：

  • 扩展单元测试覆盖率
  • 添加更多的BookStack API端点
  • 性能优化
  • 增强错误恢复

📞 联系

Derron Knox - 软件工程师与解决方案架构师

此项目展示了企业级软件开发实践，体现了在现代网络技术、云原生开发和可扩展系统架构方面的熟练程度。