Ahu Knowledge Base - 阿虎教育知识库 MCP 工具

这是为阿虎教育公司开发的基于 Model Context Protocol (MCP) 的知识库管理工具，专门用于存储、管理和查询各类开发规范文档，包括代码评审规范、开发规范、SQL 规范、安全规范等。

⚠️ 重要说明

所有知识库访问都必须通过 HTTP 服务器完成！

• ✅ 必须启动 HTTP 服务器（npm run server:http）才能访问知识库
• ❌ 不再支持直接文件访问，即使知识库文件在本地
• 🔒 所有访问都通过 HTTP API，确保统一管理和安全控制
• 📡 stdio 模式通过 HTTP 客户端访问，必须确保 HTTP 服务器已启动

详细说明请查看 HTTP_ONLY_MODE.md

功能特性

知识库管理工具 (Tools)

1. search_knowledge - 搜索知识库

   • 支持按关键词、分类、标签搜索规范文档
   • 示例：search_knowledge({ query: "代码评审", category: "code-review" })

2. get_knowledge - 获取指定文档

   • 根据文档 ID 获取完整的规范文档内容
   • 示例：get_knowledge({ id: "code-review-1234567890" })

3. list_knowledge - 列出所有文档

   • 列出知识库中的所有文档，可按分类过滤
   • 示例：list_knowledge({ category: "security" })

4. add_knowledge - 添加新文档

   • 向知识库添加新的规范文档
   • 示例：add_knowledge({ title: "代码评审规范", category: "code-review", content: "# 代码评审规范\n\n..." })

5. update_knowledge - 更新文档

   • 更新已存在的规范文档
   • 示例：update_knowledge({ id: "...", content: "更新后的内容..." })

6. delete_knowledge - 删除文档

   • 从知识库中删除指定的文档
   • 示例：delete_knowledge({ id: "..." })

7. get_knowledge_stats - 获取统计信息

   • 获取知识库的统计信息，包括文档总数、分类数量等

知识库资源 (Resources)

• knowledge://stats - 知识库统计信息
• knowledge://index - 所有文档的索引
• knowledge://{id} - 单个文档内容
• knowledge://category/{category} - 分类下的所有文档

安装

# 安装依赖
npm install

# 构建项目
npm run build

开发

# 开发模式（使用 tsx 直接运行）
npm run dev

# 监听模式（自动重新编译）
npm run watch

快速开始

1. 安装依赖

npm install

2. 构建项目

npm run build

3. 启动 HTTP 服务器（必须）

npm run server:http

重要：必须启动 HTTP 服务器才能访问知识库！

4. 在 Cursor 中使用

配置 Cursor MCP（见下方配置说明），然后重启 Cursor。stdio 模式会自动通过 HTTP 客户端连接 HTTP 服务器。

4. 配置认证（可选）

如果需要启用 API Key 认证：

# 生成 API Key
npm run generate-keys

# 配置环境变量（在 Cursor 配置中）
export AHU_KB_REQUIRE_AUTH=true
export AHU_KB_API_KEY=your-generated-api-key

5. 在 Cursor 中配置

方式1: 使用 npx（需要先发布到 npm）

{
  "mcpServers": {
    "ahu-knowledge-base": {
      "command": "npx",
      "args": [
        "-y",
        "ahu-knowledge-base@latest",
        "--api-key=your-api-key",
        "--server-url=http://your-server:3000"
      ],
      "env": {}
    }
  }
}

⚠️ 重要：

• 需要先发布到 npm 才能使用此方式（npm publish）
• 如果包未发布，会报错 Package not found
• 如果还未发布，请使用方式2（本地路径）

发布步骤请查看 NPM_PUBLISH.md

方式2: 使用本地路径

{
  "mcpServers": {
    "ahu-knowledge-base": {
      "command": "node",
      "args": ["/Users/zhuanzmima0000/project.public/self-developed/self-mcp/dist/index.js"],
      "cwd": "/Users/zhuanzmima0000/project.public/self-developed/self-mcp",
      "env": {
        "AHU_KB_API_KEY": "your-api-key-here"
      }
    }
  }
}

注意：

• 请将路径替换为你的实际项目路径
• 必须启动 HTTP 服务器才能使用
• 如果配置了 AHU_KB_API_KEY，自动启用认证（内部逻辑）

详细配置说明请查看：

• NPX_DEPLOYMENT.md - NPX 部署详细说明
• MCP_CONFIG.md - MCP 配置指南

6. 开始使用

配置完成后，重启 Cursor，然后就可以通过 AI 助手来管理知识库了：

• "请添加一个代码评审规范"
• "搜索关于 SQL 注入的安全规范"
• "列出所有开发规范文档"

使用方式

在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件（通常在 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ahu-knowledge-base": {
      "command": "node",
      "args": ["/path/to/ahu-knowledge-base/dist/index.js"]
    }
  }
}

知识库模式

本地模式（默认）

知识库文档存储在 knowledge-base/ 目录下，按分类组织：

knowledge-base/
├── index.json              # 文档索引（自动生成）
├── code-review/            # 代码评审规范
│   └── *.md
├── development/            # 开发规范
│   └── *.md
├── sql/                    # SQL 规范
│   └── *.md
├── security/               # 安全规范
│   └── *.md
└── ...

每个文档都是 Markdown 格式，包含完整的规范内容。

自动判断：如果没有数据库配置，自动使用本地模式

云端模式（待实现）

知识库文档存储在数据库中（MySQL/PostgreSQL/MongoDB），支持：

• 集中管理和备份
• 多客户端并发访问
• 事务支持
• 全文搜索

自动判断：如果配置了数据库连接（AHU_KB_DB_TYPE 等），自动使用云端模式

详细说明请参考 CLOUD_KNOWLEDGE_BASE.md

使用示例

添加规范文档

通过 AI 助手添加新的规范：

请使用 add_knowledge 工具添加一个代码评审规范：
- 标题：代码评审检查清单
- 分类：code-review
- 内容：[你的规范内容]
- 标签：["代码质量", "评审"]

查询规范

请搜索关于 SQL 注入的安全规范

请列出所有代码评审相关的文档

更新规范

请更新 ID 为 xxx 的文档，添加新的检查项

扩展开发

添加新的分类

知识库会自动识别新的分类。只需在添加文档时使用新的分类名称即可：

await knowledgeBase.addOrUpdateDocument(
  "新规范标题",
  "new-category",  // 新分类会自动创建
  "规范内容...",
  ["标签1", "标签2"]
);

自定义知识库路径（本地模式）

可以在创建 KnowledgeBase 实例时指定自定义路径：

const knowledgeBase = new KnowledgeBase("./custom/path", true);

知识库模式自动判断

// 自动判断：有数据库配置用云端，否则用本地
const knowledgeBase = new KnowledgeBase("./knowledge-base");

// 检查当前模式
if (knowledgeBase.isUsingLocal()) {
  console.log("使用本地知识库");
} else {
  console.log("使用云端知识库");
}

项目结构

ahu-knowledge-base/
├── src/
│   ├── index.ts              # 主服务器代码（stdio 模式）
│   ├── http-server-entry.ts  # HTTP 服务器入口（云端模式）
│   ├── knowledge-base.ts     # 知识库管理模块
│   ├── auth.ts               # 认证模块（API Key）
│   ├── config.ts             # 配置管理
│   ├── http-server.ts         # HTTP 服务器实现
│   └── mcp-setup.ts           # MCP 服务器设置
├── knowledge-base/           # 知识库存储目录（本地模式，自动创建）
│   ├── index.json            # 文档索引
│   └── [category]/           # 各分类目录
├── scripts/
│   ├── generate-keys.ts       # 生成 API Key 工具
│   └── add-*.ts              # 知识库训练脚本
├── dist/                     # 编译输出目录
├── package.json              # 项目配置
├── tsconfig.json             # TypeScript 配置
├── config.example.json       # 配置示例
├── README.md                 # 本文档
└── docs/                     # 文档目录
    ├── HTTP_ONLY_MODE.md     # HTTP 服务器模式说明
    ├── MCP_CONFIG.md         # MCP 配置指南
    ├── START_GUIDE.md        # 启动指南
    ├── USAGE.md              # 使用指南
    ├── QUERY_GUIDE.md        # 查询指南
    ├── DEBUG.md              # 调试指南
    ├── TROUBLESHOOTING.md    # 故障排查
    ├── SERVICE_MANAGEMENT.md # 服务管理
    ├── DEPLOYMENT.md         # 部署和安全配置指南
    ├── CLOUD_KNOWLEDGE_BASE.md # 云端知识库部署指南
    └── PROMPT.md             # 项目提示词（供 AI 理解项目）

技术栈

• TypeScript - 类型安全的 JavaScript
• @modelcontextprotocol/sdk - MCP 官方 SDK
• Node.js - 运行环境
• 存储：
  • 本地模式：文件系统（Markdown + JSON）
  • 云端模式：数据库（MySQL/PostgreSQL/MongoDB，待实现）

安全特性

• API Key 认证：如果配置了 API Key，自动启用认证，每次请求需要携带（内部逻辑）
• 知识库模式：自动判断，有数据库配置用云端，否则用本地（内部逻辑）
• HTTPS 支持：生产环境可启用 SSL/TLS 加密

详细说明请参考 DEPLOYMENT.md

相关文档

• README.md - 项目说明文档
• HTTP_ONLY_MODE.md - HTTP 服务器模式说明
• MCP_CONFIG.md - MCP 配置指南
• START_GUIDE.md - 启动指南
• USAGE.md - 使用指南和训练建议
• QUERY_GUIDE.md - 查询指南
• DEBUG.md - 调试指南
• TROUBLESHOOTING.md - 故障排查
• SERVICE_MANAGEMENT.md - 服务管理
• DEPLOYMENT.md - 部署和安全配置指南
• CLOUD_KNOWLEDGE_BASE.md - 云端知识库部署指南
• PROMPT.md - 项目提示词（帮助 AI 理解项目背景和计划）

关于

• 公司：阿虎教育
• 项目名称：ahu-knowledge-base
• 版本：1.0.0

许可证

MIT