# Stdio 模式
npx @dyyz1993/kb-mcp --stdio

# HTTP 模式
npx @dyyz1993/kb-mcp --http --port 19877

npm install -g @dyyz1993/kb-mcp
kb-mcp --stdio

git clone https://github.com/dyyz1993/knowledge-base-mcp.git
cd knowledge-base-mcp
bun install

bun run -e '
import { pipeline, env } from "@huggingface/transformers"
import { join } from "node:path"
import { homedir } from "node:os"
env.localModelPath = join(homedir(), ".cache/huggingface/local-models")
env.allowLocalModels = true
await pipeline("feature-extraction", "Xenova/paraphrase-multilingual-MiniLM-L12-v2", { dtype: "fp32" })
console.log("Model downloaded")
'

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "local",
        "command": ["npx", "@dyyz1993/kb-mcp", "--stdio"]
      }
    }
  }
}

npx @dyyz1993/kb-mcp --http --port 19877

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "streamable-http",
        "url": "http://your-server:19877/mcp"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "knowledge-base": {
        "type": "sse",
        "url": "http://your-server:19877/sse"
      }
    }
  }
}

{
  "mcpServers": {
    "knowledge-base": {
      "command": "npx",
      "args": [
        "@dyyz1993/kb-mcp",
        "--stdio"
      ],
      "type": "stdio"
    }
  }
}

npx @dyyz1993/kb-mcp --http --web --port 19877

{
  "mcpServers": {
    "knowledge-base": {
      "url": "http://localhost:19877/sse",
      "type": "sse"
    }
  }
}

# 一条命令同时启动 MCP API + Web UI
npx @dyyz1993/kb-mcp --http --web --port 19877

{
  title: string              // 文档标题
  content: string            // 正文（Markdown）
  tags: string[]             // 标签：tutorial / document / analysis / guide / snippet / best-practice / reference / architecture / troubleshooting / decision
  keywords: string[]         // 关键词，用于检索
  intent: string             // 创建意图或使用场景
  project_description: string // 当前项目简要描述
  source_project?: string    // 来源项目路径（自动填充）
  source_worktree?: string   // 来源 worktree 路径（自动填充）
}

{
  path: string           // 文件绝对路径
  offset?: number        // 起始行号（默认 0）
  limit?: number         // 读取行数（默认 2000）
}

{
  path: string           // 文件绝对路径
  pattern: string       // 搜索文本或正则表达式
  case_sensitive?: boolean  // 是否区分大小写（默认 false）
  regex?: boolean       // 是否使用正则表达式（默认 true）
}

{
  path: string           // 文件/目录绝对路径
}

{
  query: string                // 自然语言查询
  max_web_results?: number     // 联网搜索最大结果数（默认 3，当前未使用）
  auto_save?: boolean          // 是否自动存入知识库（默认 true，当前未使用）
}

{
  url: string                  // 来源 URL
  title: string                // 文档标题
  content: string              // 页面内容（Markdown 格式）
  tags?: string[]              // 标签（默认 ["reference", "auto-ingested"]）
  keywords?: string[]          // 关键词（不填则从标题自动提取）
}

{
  repo: string                 // GitHub 仓库（owner/repo 格式，如 oven-sh/bun）
  max_files?: number           // 最多读取文件数（默认 20）
}

{
  hours?: number               // 查询最近多少小时（默认 24）
  limit?: number               // 最大返回数量（默认 50）
  include_content?: boolean    // 是否返回完整内容（默认 false）
}

{
  limit?: number               // 返回建议数量（默认 10）
}

{}  // 无参数，自动检查所有带 related_files 的文档

{
  doc_id?: string              // 指定文档 ID（不指定则分析最近 10 篇）
  threshold?: number           // 语义相似度阈值 0-1（默认 0.7）
}

用户查询 → kb_ask
  ├── KB 命中（score ≥ 40）→ 直接返回，无需联网
  └── KB 未命中 → 返回 Miss Task
        ├── suggested_workflow:
        │     step_1: web-search-prime(query)
        │     step_2: web-reader(url)
        │     step_3: kb_ingest_url(url, title, content)
        └── alternative_workflows:
              • GitHub: zread(repo) → kb_ingest_url()
              • JS 渲染: agent-browser → kb_ingest_url()
              • 本地项目: kb_ingest_repo(repo_url)

Agent 执行搜索 → kb_ingest_url 存储 → resolveMiss → 下次查询直接命中
kb_suggest 分析高频 miss → 推荐预抓取主题

查询 → ┌─ P0: 文本匹配（标题/关键词/意图） ──── 权重 0.2
       ├─ P1: TF-IDF（加权词频 + 余弦相似度） ── 权重 0.3
       └─ P2: 语义向量（384维 embedding + 余弦相似度） ── 权重 0.5
         ↓
       加权融合 → 排序返回 TopK

~/.knowledge/
├── index.json              # 文档索引
├── vectors.json            # 语义向量缓存
├── outlines/               # 项目大纲
│   └── {project-slug}.json
├── {id}-{title-slug}.md    # 文档文件（YAML frontmatter + Markdown 正文）
└── ...

---
id: "abc123xyz"
title: "React Hooks 最佳实践"
tags: ["best-practice"]
keywords: ["react", "hooks", "useEffect"]
intent: "React 开发中 hooks 的常见模式和陷阱"
project_description: "前端组件库项目"
source_project: "/Users/x/project-frontend"
created_at: 1746012345678
---

## 使用 useEffect 的注意事项
...

bun test