AI导哈

知识库管理系统

一个兼具CLI工具和MCP服务器功能的企业级知识库管理系统，提供安全框架、合规性支持和多租户功能，适用于团队协作和AI工具集成。

  • by moikas-code
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 moikas-code/kb-mcp

使用说明

KB-MCP-企业知识库管理系统

一个知识库管理系统，既可以作为CLI工具，也可以作为MCP（模型上下文协议）服务器。具有企业就绪的安全框架，旨在通过SOC2合规路线图实现可扩展性。

🌟 主要特点

安全与合规

免责声明： 虽然下面描述的大多数安全和合规功能都是在代码库中实现的，但由于关键错误或部分实现，有些功能还没有完全准备好投入生产（请参阅 docs/COMPREHENSIVE_AUDIT_REPORT.md).强烈建议用户在部署到生产环境之前查看审计结果并解决任何悬而未决的问题。

  • 🔐 企业级安全：AES-256-GCM加密、安全身份验证、速率限制
  • 📋 SOC2就绪框架：审计日志记录、数据保留和访问控制结构到位
  • 🛡️ GDPR就绪：PII检测、数据匿名化、删除权
  • 🔑 多因素身份验证：基于TOTP的MFA、API密钥管理
  • 🚦 速率限制：DDoS保护，每个资源的可配置限制

双模式操作

  • 💻 CLI工具：用于本地知识库管理的强大命令行界面
  • 🤖 MCP服务器：与Claude Desktop和其他人工智能工具集成
  • 📱 REST API：用于web集成的可选HTTP API
  • 🔄 实时同步：保持团队间知识库的同步

企业功能

  • 📊 版本控制：Git与自动提交的集成
  • 💾 备份和恢复：自动备份，时间点恢复
  • 🌍 多租户：每个团队/项目的独立知识库
  • 📈 监控：普罗米修斯指标，OpenTetry跟踪
  • 🚨 告警：PagerDuty、Slack、电子邮件通知

开发者体验

  • 🎯 类型安全：具有严格类型的完全TypeScript支持
  • 🧪 测试良好：具有安全测试的全面测试套件
  • 📚 已记录：大量文件和示例
  • 🔧 可配置的：具有环境覆盖的YAML/JSON配置
  • 🎨 模板：针对不同用例的预配置模板

🚀 快速开始

作为全局CLI工具安装

npm install -g @moiaks/kb-mcp

# Note: If you encounter installation issues with native dependencies, try:
# npm install -g kb-mcp --ignore-scripts
# or use the installation script:
# curl -sSL https://raw.githubusercontent.com/moikas-code/kb-mcp/master/scripts/install-global.sh | bash

# Initialize a new knowledge base
kb init --template enterprise

# Optional: Use graph database for advanced AI features
kb init --template enterprise
# > Select "Graph Database" when prompted
# > Database containers start automatically!

# Start using it
kb write docs/welcome.md
kb list
kb search "important"
kb serve  # Start MCP server

在项目中安装

npm install @moiaks/kb-mcp

# Or with yarn
yarn add @moiaks/kb-mcp

# Or with pnpm
pnpm add @moiaks/kb-mcp

从源代码安装

git clone https://github.com/moikas-code/kb-mcp.git
cd kb-mcp
npm install
npm run build
npm link  # Makes 'kb' command available globally

🛠️ 安装和故障排除（Sharp和Native模块）

先决条件

  • Node.js v18+（请与 node -v)
  • npm v8+（请与 npm -v)
  • Linux/WSL2用户：
    如果没有构建工具，请安装：
    sudo apt-get update
sudo apt-get install -y build-essential python3 make g++

全局安装（推荐）

curl -fsSL https://raw.githubusercontent.com/moikas/kb-mcp/main/scripts/install-global.sh | bash

或手动：

npm install -g @moikas/kb-mcp@latest --ignore-scripts
npm rebuild -g sharp --unsafe-perm

故障排除

  • 如果您看到以下错误 sharp 或本地模块：
    • 确保你使用的是npm，而不是Bun或Yarn。
    • 确保安装了构建工具（见上文）。
    • 尝试重建sharp：
      npm rebuild -g sharp --unsafe-perm
  • 如果全局安装失败，请使用本地安装：
    git clone https://github.com/moikas/kb-mcp.git
cd kb-mcp
npm install
npx kb serve

备注

  • 做 不 使用Bun或Yarn 1.x进行全局安装。
  • 如果您使用的是WSL2，请确保您拥有最新的Windows和WSL更新。

注： 由于依赖冲突，项目需要 sharp@^0.32.0 与兼容 @xenova/transformers。如果您遇到安装问题，请确保您使用的是此版本的sharp。请参阅下面的故障排除。

📖 用法

命令行接口命令模式

初始化知识库

# Basic setup
kb init

# Enterprise setup with encryption and audit logging
kb init --template enterprise --encrypt

# Interactive setup
kb init --interactive

基本命令

# Create or update a file
kb write guides/setup.md --content "# Setup Guide"
kb write guides/setup.md --file existing-doc.md
kb write guides/setup.md --template guide --interactive

# Read a file
kb read guides/setup.md
kb cat guides/setup.md --metadata  # Show only metadata

# List contents
kb list                    # List root directory
kb list docs              # List specific directory
kb ls -r                  # Recursive listing
kb ls -l                  # Long format with details

# Search
kb search "configuration"          # Search all files
kb search "security" -d docs      # Search in specific directory
kb find "error" --limit 50        # Limit results

# Delete (with backup)
kb delete old-file.md
kb rm old-file.md --force --no-backup

高级命令

# Authentication
kb auth login                      # Interactive login
kb auth login -u admin            # Login with username
kb auth logout                    # Clear session
kb auth status                    # Check auth status

# API Key Management
kb auth create-api-key "CI/CD Key" --permissions read,write
kb auth list-api-keys
kb auth revoke-api-key <key-id>

# Audit Log Management
kb audit query --from 2024-01-01 --to 2024-12-31
kb audit export --format csv --output audit-report.csv
kb audit verify                   # Verify log integrity

# Backup and Restore
kb backup --output backups/kb-backup.tar.gz --encrypt
kb backup --incremental          # Only changed files
kb restore backups/kb-backup.tar.gz --verify

# Configuration
kb config get security.mfa_required
kb config set security.mfa_required true
kb config list                   # Show all settings

# Import/Export
kb export --format json --output kb-export.json
kb import kb-export.json --merge --validate

MCP服务器模式

启动服务器

# Start as MCP server (stdio transport)
kb serve

# Start with specific configuration
kb serve --config production.yaml

# Start with TLS
kb serve --tls --cert server.crt --key server.key

# Start on specific port (for HTTP transport)
kb serve --port 8080 --http

Claude桌面集成

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

选项1：使用包装器（推荐）

包装器会自动检测项目配置：

{
  "mcpServers": {
    "kb-mcp": {
      "command": "kb-mcp-wrapper",
      "args": ["serve"]
    }
  }
}
选项2：项目特定配置

对于特定项目：

{
  "mcpServers": {
    "kb-mcp": {
      "command": "kb",
      "args": ["serve"],
      "env": {
        "KB_CONFIG_PATH": "/path/to/your/project/.kbconfig.yaml"
      }
    }
  }
}

项目隔离

要确保kb-mcp仅在您的项目目录中工作：

  1. 创建一个 .kbconfig.yaml 在项目根目录中：

    type: filesystem
filesystem:
  root_path: ./kb  # Relative to project root
  enable_versioning: true

  2. 使用 kb-mcp-wrapper 自动查找项目配置的命令

  3. 每个项目都维护着自己独立的知识库

环境变量

# Core Settings
KB_CONFIG_PATH="/path/to/config.yaml"     # Configuration file path
KB_STORAGE_PATH="/path/to/kb"             # Knowledge base location
KB_LOG_LEVEL="info"                       # Logging level

# Security
KB_ENCRYPTION_KEY="your-secret-key"       # Encryption key (use secrets manager)
KB_JWT_SECRET="your-jwt-secret"           # JWT signing secret
KB_MFA_REQUIRED="true"                    # Require MFA

# Compliance
KB_AUDIT_ENABLED="true"                   # Enable audit logging
KB_AUDIT_RETENTION_DAYS="548"             # 18 months

# Performance
KB_RATE_LIMIT_PER_MINUTE="100"           # Rate limiting
KB_CACHE_TTL="300"                       # Cache TTL in seconds

🔧 配置

配置文件（.kbconfig.yaml）

# Security Configuration
security:
  encryption:
    algorithm: AES-256-GCM
    key_rotation_days: 90
  authentication:
    providers: [jwt, oauth2, api_key]
    mfa_required: true
    session_timeout: 3600
  rate_limiting:
    enabled: true
    max_requests_per_minute: 100

# Compliance Configuration
compliance:
  audit:
    enabled: true
    retention_days: 548  # 18 months
    destinations: [file, siem, s3]
  gdpr:
    pii_detection: true
    anonymization_delay: 24h

# Storage Configuration
storage:
  primary: filesystem  # or s3, gcs, azure
  encryption_at_rest: true
  versioning: true
  backup:
    enabled: true
    schedule: "0 2 * * *"  # Daily at 2 AM
    retention_days: 30

# Monitoring Configuration
monitoring:
  metrics:
    enabled: true
    provider: prometheus
  tracing:
    enabled: true
    provider: opentelemetry
  alerts:
    channels: [pagerduty, slack]

模板

基本模板

  • 简单身份验证
  • 基于文件的存储
  • 基本审计日志记录
  • 适合个人使用

企业模板

  • 完整的身份验证套件（JWT、OAuth2、SAML）
  • 带备份的加密存储
  • 符合SOC2的审计日志记录
  • GDPR合规功能
  • 生产监控

按项目配置

创建 .kbconfig 在项目根目录中：

extends: ~/.kb-mcp/config.yaml
storage:
  path: ./docs/kb
compliance:
  audit:
    enabled: false  # Disable for local development

🔒 安全

安全功能

输入验证

  • 路径遍历预防
  • XSS/注射保护
  • 文件类型限制
  • 内容大小限制
  • 恶意模式检测

加密

  • 安息：存储文件的AES-256-GCM加密
  • 运输中：TLS 1.3适用于所有通信
  • 密钥管理：自动钥匙旋转，HSM支持
  • 现场级别：审计日志中的敏感字段加密

身份验证和授权

  • 多因素身份验证（TOTP）
  • 基于JWT的会议
  • API密钥管理
  • 基于角色的访问控制（RBAC）
  • OAuth2/SAML集成

审计与合规

  • 防篡改审计日志
  • 哈希链完整性
  • 自动保留策略
  • GDPR合规性（PII处理）
  • SOC2证据收集

安全最佳实践

  1. 从不提交加密密钥

    # Use environment variables or secrets manager
export KB_ENCRYPTION_KEY=$(aws secretsmanager get-secret-value --secret-id kb-key)

  2. 启用MFA进行生产

    security:
  authentication:
    mfa_required: true

  3. 定期按键轮换

    kb rotate-keys --confirm

  4. 监控审核日志

    kb audit query --event-type security --severity high

🏢 生产部署

Docker部署

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:20-alpine
RUN apk add --no-cache tini
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Security: Run as non-root
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nodejs -u 1001
USER nodejs

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node dist/health-check.js || exit 1

ENTRYPOINT ["tini", "--"]
CMD ["node", "dist/cli/index.js", "serve"]

# Build and run
docker build -t kb-manager:latest .
docker run -d \
  --name kb-manager \
  -p 3000:3000 \
  -v /path/to/kb:/app/kb \
  -v /path/to/config:/app/config \
  --env-file .env.production \
  kb-manager:latest

Kubernetes部署

# kb-manager-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kb-manager
  labels:
    app: kb-manager
spec:
  replicas: 3
  selector:
    matchLabels:
      app: kb-manager
  template:
    metadata:
      labels:
        app: kb-manager
    spec:
      serviceAccountName: kb-manager
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      containers:
      - name: kb-manager
        image: kb-manager:latest
        imagePullPolicy: Always
        ports:
        - containerPort: 3000
          name: http
        env:
        - name: KB_ENCRYPTION_KEY
          valueFrom:
            secretKeyRef:
              name: kb-secrets
              key: encryption-key
        - name: KB_JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: kb-secrets
              key: jwt-secret
        volumeMounts:
        - name: kb-storage
          mountPath: /app/kb
        - name: config
          mountPath: /app/config
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
      - name: kb-storage
        persistentVolumeClaim:
          claimName: kb-storage-pvc
      - name: config
        configMap:
          name: kb-config
---
apiVersion: v1
kind: Service
metadata:
  name: kb-manager
spec:
  selector:
    app: kb-manager
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

AWS部署

# Using AWS ECS with Fargate
aws ecs create-cluster --cluster-name kb-manager-cluster

# Create task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json

# Create service
aws ecs create-service \
  --cluster kb-manager-cluster \
  --service-name kb-manager \
  --task-definition kb-manager:1 \
  --desired-count 3 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxx],securityGroups=[sg-xxx]}"

监控设置

# prometheus.yml
scrape_configs:
  - job_name: 'kb-manager'
    static_configs:
      - targets: ['kb-manager:3000']
    metrics_path: '/metrics'

# Grafana Dashboard Import
curl -X POST http://grafana:3000/api/dashboards/import \
  -H "Content-Type: application/json" \
  -d @kb-manager-dashboard.json

🧪 测试

运行测试

# All tests
npm test

# Security tests only
npm run test:security

# Compliance tests
npm run test:compliance

# Coverage report
npm test -- --coverage

# Integration tests
npm run test:integration

安全性测试

# OWASP dependency check
npm audit --production

# Static analysis
npm run lint:security

# Penetration testing
npm run test:pentest

🚨 故障排除

常见问题

认证失败

# Reset credentials
kb auth reset --confirm

# Check session status
kb auth status --verbose

加密密钥丢失

# Recover from backup (if configured)
kb recover --backup-key <backup-key>

# Export unencrypted data (requires admin)
kb export --decrypt --admin-override

性能问题

# Check metrics
kb metrics --component storage

# Optimize database
kb optimize --vacuum --reindex

# Clear cache
kb cache clear --all

MCP连接问题

# Test MCP server
kb serve --test

# Check Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp-server.log  # macOS

# Validate configuration
kb config validate --mcp

调试模式

# Enable debug logging
export DEBUG=kb:*
kb --debug <command>

# Trace mode for detailed logs
kb --trace <command>

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发设置

# Clone the repository
git clone https://github.com/yourusername/kb-manager.git
cd kb-manager

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build
npm run build

代码规范

  • TypeScript严格模式
  • 100%类型覆盖
  • 安全第一的方法
  • 综合测试
  • 清晰的文件

🧪 测试

该项目包括一个全面的测试套件，涵盖：

  • 单元测试：验证单个功能和模块。
  • 集成测试：确保组件按预期协同工作。
  • 安全测试：检查漏洞和合规性。
  • 符合性测试：验证SOC2、GDPR和其他要求。

要运行测试，请执行以下操作：

npm test                # All tests
npm run test:security   # Security tests only
npm run test:compliance # Compliance tests
npm test -- --coverage  # Coverage report
npm run test:integration # Integration tests

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

MIT许可证

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

⚠️ 重要免责声明

  • 生产准备： 该项目正在积极开发中。虽然实现了许多企业功能，但有些组件可能还没有完全准备好投入生产。用户在部署到生产环境之前，应在自己的环境中彻底测试和审查系统。

  • 合规与认证： 本项目中存在SOC2、GDPR、HIPAA、ISO 27001和OWASP Top 10功能并不构成正式认证。要达到这些标准的合规性，除了这里提供的技术控制之外，还需要额外的组织流程、文件和第三方审计。

  • 安全责任： 安全功能是作为基础提供的，但安全部署、配置和密钥管理的最终责任在于用户或部署组织。始终遵循秘密管理、访问控制和定期安全审查的最佳实践。

  • 第三方依赖关系： 该项目依赖于多个第三方库和服务。用户负责审查、更新和监控这些依赖关系的漏洞和许可合规性。

  • 社区支持： 这个项目是开源和社区驱动的。虽然我们努力及时解决问题并撤回请求，但除非您有单独的企业协议，否则无法保证商业支持或响应时间。

  • 实验特点： 一些功能（如高级图搜索、向量嵌入或SAML集成）可能是实验性的或不完整的。使用这些功能的风险由您自行承担，并监控更新。

相关 MCP