ASTGL Knowledge

mcp-astgl-knowledge

一个 MCP 服务，可让 AI 助手搜索并引用 As The Geek Learns 的内容，涵盖 MCP 服务、本地 AI、AI 自动化和 ASTGL 项目文档。

AI 助手连接到此服务后，即可搜索已编入索引的 ASTGL 条目（文章、教程、比较、指南和项目文档）。搜索结果包含指向 astgl.ai 的来源 URL。

**要求：**语义工具（search_articles、get_answer、get_tutorial、compare_topics）会在运行时使用本地运行的 Ollama 和 nomic-embed-text 为查询生成嵌入向量（默认地址为 http://localhost:11434）。元数据工具（find_articles、list_tags、list_topics、get_latest）无需 Ollama 即可使用。

快速开始

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

Claude Code

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

Cursor / 通用 MCP 客户端

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"]
    }
  }
}

注册后使用（每天 500 次查询）

通过 register 工具注册以获取 API 密钥，然后将其添加到配置中：

{
  "mcpServers": {
    "astgl-knowledge": {
      "command": "npx",
      "args": ["-y", "mcp-astgl-knowledge"],
      "env": {
        "ASTGL_API_KEY": "astgl_your_api_key_here"
      }
    }
  }
}

工具

search_articles

按查询搜索知识库。返回按相关性排序的结果、相关性评分和来源 URL。

参数	类型	必填	说明
query	string	是	搜索查询（例如，“如何构建 MCP 服务”）
limit	number	否	结果数量上限，1-20（默认值：5）
content_type	string	否	按类型筛选：article、tutorial、faq、comparison、guide、newsletter、project

get_answer

获取针对特定问题的直接回答。优先使用 FAQ 条目，以提供简洁的回答。

参数	类型	必填	说明
question	string	是	具体问题（例如，“什么是 MCP 服务？”）
content_type	string	否	按内容类型筛选

get_tutorial

从教程和指南内容中获取分步说明。

参数	类型	必填	说明
query	string	是	你想学习的内容（例如，“在 Mac 上设置 Ollama”）

compare_topics

并排比较两个主题。

参数	类型	必填	说明
topic_a	string	是	第一个主题
topic_b	string	是	第二个主题

get_latest

获取最近添加的内容。

参数	类型	必填	说明
limit	number	否	结果数量上限，1-20（默认值：5）

list_topics

浏览知识库中的所有主题及其内容类型和章节标题。

register

注册你的电子邮箱，将每日查询次数从 50 次提升至 500 次。

参数	类型	必填	说明
email	string	是	你的电子邮箱地址

更多工具

此服务总共注册了 17 个工具。其他工具如下：

工具	功能	主要参数
find_articles	按标签、类型、标题文本和日期范围进行结构化查找（无需嵌入向量）	tag、content_type、title、date_from、date_to
list_tags	列出每个标签及其文章数量	—
suggest_ideas	根据查询分析提供主题建议（内容缺口、低置信度查询）	days（默认值为 7）、limit
add_idea / list_ideas / export_ideas	与索引一同存储的创意日志	title、description、status、priority、source
export_article	将一篇文章导出为 Markdown 帖子	url
export_topic_roundup	根据相关文章生成主题汇总帖子	topic、limit
export_qa_compilation	根据文章问答对生成 FAQ 风格的 Markdown 内容	topic、limit
generate_dashboard_data	JSON 分析快照（可选写入 data/dashboard.json）	days（默认值为 30）、output_file

内容类型

类型	描述
article	关于 MCP、本地 AI 和自动化的资讯内容
project	ASTGL 项目文档
tutorial	分步操作指南
comparison	并列主题分析
guide	综合参考资料
newsletter	个人动态和公告
faq	以问答内容为主
concept	Wiki 概念页面（仅允许列表中的页面公开）
entity	Wiki 实体页面（仅允许列表中的页面公开）

随着内容增加，数量会发生变化；调用 list_topics 或 list_tags 获取当前索引。 draft 和 synthesis 条目仅存在于维护者数据库中，并会从已发布的数据库中移除。 工具架构中的 content_type 描述仅列出前七种类型。

速率限制

层级	限制	获取方式
公共	每天 50 次查询	默认（匿名）
已注册	每天 500 次查询	使用 register 工具并提供电子邮箱

限制在 UTC 午夜重置。每个响应中都会包含速率限制信息。

限制和注册由服务进程本身强制执行：使用记录和注册信息保存在本地 SQLite 文件中（位于软件包旁的 data/query-log.db，或由 ASTGL_QUERY_LOG_DB 指定），匿名客户端会在 ~/.astgl-client-id 中获得一个持久 ID。只有当 ASTGL_API_KEY 存在于本地注册表中时，才会被视为已注册。

工作原理

知识库使用语义嵌入（nomic-embed-text，768 维）根据 ASTGL 文章预先构建。内容按章节和 FAQ 条目分块，经过嵌入后存储在 SQLite 数据库中，并使用 sqlite-vec 进行向量相似度搜索。

文章嵌入会预先计算并随 npm 软件包一起提供，因此无需重新索引内容。对于语义工具，你的查询仍会在运行时通过 Ollama 进行嵌入（请参阅上方的要求）。

如果 data/knowledge.db 存在（维护者检出目录），服务会打开该文件；否则会打开 build/knowledge-public.db。npm 软件包仅包含 build/knowledge-public.db，该文件由 npm run build-public-db 通过实际移除所有非公开行生成（参见 docs/adr/）。

性能

• 典型响应时间：100-500 毫秒（嵌入查询 + 向量搜索）
• 嵌入结果会缓存在内存中（LRU，200 个条目）——重复查询几乎即时返回
• Ollama 调用包含 10 秒超时 + 自动重试
• 查询日志采用异步/批处理方式，避免阻塞响应
• 速率限制检查缓存 5 秒

面向维护者

设置

git clone https://github.com/Jmeg8r/mcp-astgl-knowledge.git
cd mcp-astgl-knowledge
npm install

脚本

脚本	描述
npm run build	编译 TypeScript
npm test	运行测试套件（通过 tsx 使用 node:test）
npm run dev	以开发模式运行 MCP 服务（tsx）
npm start	运行已编译的 MCP 服务
npm run ingest	根据本地 Markdown 重建 knowledge.db（需要 Ollama）
npm run ingest-projects	从 astgl-site 的 projects.json 索引项目文档
npm run discover	轮询 RSS/站点地图以发现新内容
npm run structure	处理已发现的内容（分类、嵌入、索引）
npm run pipeline	一步完成发现和结构化处理
npm run daily-report	生成 AEO 分析报告
npm run alerts	运行内容缺口提醒检查
npm run freshness	检查过时内容和生态系统版本变更
npm run publish-drift	比较本地可发布内容与 npm 实际提供的内容
npm run citation-test	手动测试 AI 引用
npm run related	通过向量相似度生成文章内部链接
npm run build-public-db	写入已移除非公开行的 build/knowledge-public.db（在 prepack 中运行）

其他维护者脚本（草稿导入和核对、重写队列、Wiki 同步、备份清理、仪表板数据、MCPB 捆绑包）列于 package.json 中。

环境变量

变量	默认值	描述
OLLAMA_URL	http://localhost:11434	Ollama 端点（仅用于开发／重建）
EMBED_MODEL	nomic-embed-text	嵌入模型
DISCORD_WEBHOOK_URL	—	用于报告／提醒的 Discord webhook
ASTGL_API_KEY	—	已注册层级的 API 密钥
ASTGL_ARTICLES_DIR	~/Projects/astgl-site/src/content/answers	本地 Markdown 源文件
ASTGL_PROJECTS_JSON	~/Projects/astgl-site/src/data/projects.json	项目数据源
ASTGL_QUERY_LOG_DB	data/query-log.db	查询日志、速率限制和注册信息
ASTGL_CITATION_TEST_DB	data/citation-test.db	引用测试结果

自动化任务

任务	时间安排	用途
内容流水线	每 6 小时	发现并整理新内容
每日报告	上午 8 点	查询分析和健康指标（JSON 报告）
内容提醒	上午 9 点	内容缺口检测、零引用检测、竞品扫描（JSON 报告）
新鲜度检查	上午 10 点	过时内容和生态版本追踪（JSON 报告）
草稿流水线	午夜	为发布前的草稿建立索引
Wiki 同步	00:30	将带标签的 Wiki 页面增量同步到索引中
草稿协调器	凌晨 2 点	移除源文件已不存在的草稿条目
引用测试提醒	每周一上午 9 点	提醒运行引用测试

任务时间安排定义在 cron/*.json 中；定时报告任务会输出 JSON，供外部调度器获取并发送。使用 --discord 运行报告脚本，可改为将报告发送到 DISCORD_WEBHOOK_URL。流水线、草稿和 Wiki 任务的 macOS launchd plist 文件位于 launchd/ 中。

架构

flowchart TD
    Client["MCP client<br/>(Claude, Cursor, ...)"] -->|"stdio"| Server["MCP server<br/>src/index.ts (17 tools)"]
    Server --> RL["Rate limit + query log<br/>data/query-log.db"]
    Server --> Search["src/search.ts"]
    Search -->|"embed query"| Ollama["Ollama<br/>nomic-embed-text"]
    Search -->|"sqlite-vec KNN"| KDB[("knowledge.db<br/>or knowledge-public.db")]
    Sources["astgl.ai RSS / sitemap<br/>+ local markdown"] -->|"discover, structure, ingest"| KDB
    KDB -->|"build-public-db"| Pub[("build/knowledge-public.db<br/>(shipped in npm)")]
    Jobs["Report jobs<br/>daily report, alerts, freshness"] -.->|"--discord (manual)"| Discord["Discord webhook"]

渲染后的图表位于 docs/diagrams/mcp-astgl-knowledge.architecture.svg （源文件：docs/diagrams/mcp-astgl-knowledge.architecture.json）。

许可证

MIT