AI Documentation & Guru Knowledge MCP Server

知识中心

一个 Model Context Protocol (MCP) 服务，为 AI 助手提供跨多个平台统一访问组织知识的能力。此服务连接 AI 工具与组织的知识库，让你能够在本地文档、Guru 和 Notion 中智能地创建、检索和管理文档。

🚀 这是什么？

Knowledge Hub 是一个可用于生产环境的 MCP 服务，提供：

• 🧠 Guru 知识库集成 - 搜索、读取和管理 Guru 卡片与集合
• 📝 Notion 数据库管理 - 在 Notion 数据库中创建、查询、更新和管理文档
• 🔍 高级查询与搜索 - 跨所有平台提供强大的筛选、排序和搜索功能
• 🛠️ 内容创建与管理 - 将 Markdown 转换为 Notion 页面，并设置适当的元数据和代码块验证
• 🔄 双向同步 - 将 Notion 页面导出回 Markdown 格式
• 🏗️ 开发与生产模式 - 为不同环境提供灵活的部署选项

🏗️ 架构

使用 TypeScript/Node.js（≥20.0.0）、MCP SDK v1.12.0 和 Zod 验证构建，确保类型安全。采用清晰的模块化架构，各项职责彼此分离：

src/
├── index.ts              # Main MCP server entry point
├── server.ts             # Server configuration and tool registration
├── services/             # API services (Notion, Guru)
├── tools/                # MCP tool implementations
├── types/                # TypeScript type definitions
└── utils/                # Conversion utilities and helpers

🛠️ 可用工具（共 9 个）

🧠 Guru 知识库（3 个工具）

• guru-list-cards - 使用高级查询搜索和筛选 Guru 卡片
• guru-read-card - 以格式化形式读取完整的卡片内容
• guru-get-card-attachments - 列出并下载卡片附件

📝 Notion 数据库管理（5 个工具）

• list-database-pages - 使用按类别、标签、状态筛选的高级查询和搜索
• create-page-from-markdown - 根据 Markdown 创建页面，并设置元数据和代码块验证
• update-page - 更新现有页面（内容和／或元数据）
• archive-page - 将页面移至废纸篓以进行归档
• export-page-to-markdown - 将页面导出为简洁的 Markdown 格式

🔧 实用工具（1 个工具）

• hello - 展示 MCP 功能的示例工具

⚙️ 配置与设置

🚀 安装

# Clone and install
git clone https://github.com/LaserFocused-ee/ai-docs-mcp.git
cd ai-docs-mcp/mcp_server
npm install

# Development
npm run dev

# Production build
npm run build && npm start

🔗 Claude Desktop 集成

开发配置

{
  "mcpServers": {
    "ai-knowledge-hub-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DEV_HOME": "/path/to/your/mcp_server",
        "GURU_TOKEN": "username:token",
        "NOTION_TOKEN": "your-notion-token",
        "NOTION_MCP_DATABASE_ID": "your-database-id"
      }
    }
  }
}

生产配置

{
  "mcpServers": {
    "ai-knowledge-hub": {
      "command": "npx",
      "args": ["ai-knowledge-hub"],
      "env": {
        "GURU_TOKEN": "username:token",
        "NOTION_TOKEN": "your-notion-token",
        "NOTION_MCP_DATABASE_ID": "your-database-id"
      }
    }
  }
}

🔑 API 凭据

Guru：登录 Guru → Settings → API Access → Generate token → 格式为 username:token

Notion：前往 Notion 集成 → 创建集成 → 获取 API 密钥 → 将数据库分享给集成 → 从 URL 复制数据库 ID

📁 文档结构

本地文档整理在 docs/ 目录中：

docs/
├── code_guidelines/
│   ├── flutter/architecture/    # Flutter architecture patterns
│   ├── react/                   # React best practices
│   ├── nestjs/                  # NestJS guidelines
│   └── git/                     # Git workflows
└── service-docs/                # API guides and references

🌟 主要功能

📄 Markdown ↔ Notion 转换

• 代码块验证：自动验证代码块是否符合 Notion 的 2000 字符限制
• 智能错误处理：在保留逻辑边界的同时，为拆分大型代码块提供具体指导
• 丰富的格式支持：表格、列表、标题、链接、代码块等
• 保留元数据：类别、标签、描述和状态值

🔍 高级查询系统

• 多平台搜索：跨本地文档、Guru 和 Notion 进行统一搜索
• 智能筛选：按类别、标签、状态和日期筛选，并支持灵活排序
• 分页支持：高效处理大型数据集

🛠️ 开发支持

• 环境检测：自动切换开发／生产模式
• 热重载：开发模式下监视文件变化
• MCP Inspector 集成：全面的测试工具
• 类型安全：完整的 TypeScript 与 Zod 验证

🧪 测试与验证

快速测试

# Interactive UI testing
npm run inspect

# Basic validation
npm run validate

# Comprehensive test suite
npm run test:inspector

工具调用示例

# List available documentation
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name legacy-list-docs

# Search Notion pages
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name list-database-pages \
  --tool-arg search="testing" --tool-arg limit=5

# Search Guru knowledge
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name guru-list-cards \
  --tool-arg searchTerms="API documentation" --tool-arg maxResults=5

💡 使用模式

本地文档

legacy-list-docs()  # Discover available docs
legacy-read-doc(category="code_guidelines/flutter", name="best-practices")

Notion 管理

# Context-aware search
list-database-pages(search="testing", tags=["react"], status="published")

# Create with metadata
create-page-from-markdown(
  markdown="# API Guide\n\nDocumentation...",
  metadata={category: "api-reference", tags: ["api", "rest"]}
)

Guru 知识访问

guru-list-cards(searchTerms="troubleshooting", maxResults=10)
guru-read-card(cardId="card-uuid")

🚀 发布与分发

此软件包使用自动化 GitHub Actions 工作流进行专业的发布管理。

📦 面向用户

• 安装最新稳定版本：npx ai-knowledge-hub
• 查看所有版本发布： GitHub Releases
• 查看 npm 版本： npm Package

🛠️ 面向贡献者/维护者

• 自动发布：使用 GitHub Actions 实现安全、经过验证的发布
• 版本管理：支持语义化版本控制（patch/minor/major）
• 质量保证：发布前自动进行测试和验证

📋 完整设置指南：请参阅 RELEASE_SETUP.md，了解以下内容的完整说明：

• 设置 npm 令牌和 GitHub 密钥
• 使用自动发布工作流
• 了解语义化版本控制
• 排查常见问题

🔒 安全与要求

• Node.js：要求 ≥20.0.0
• 安全凭据：仅通过环境变量处理
• 文件访问：限制在 docs 目录内
• 输入验证：对所有参数进行 Zod 架构验证
• API 速率限制：自动处理

📄 许可证

MIT License - 详情请参阅 package.json。

---

Knowledge Hub 将静态文档、机构知识和内容管理转变为面向 AI 助手的智能、可查询生态系统。它通过统一而强大的 API，在多个平台上提供上下文感知的开发指导、全面的文档管理，并让用户无缝访问组织的集体知识。