基于MCP协议构建AI知识库：Alexandria项目部署与核心工作流解析

1. 项目概述让AI拥有自己的“亚历山大图书馆”如果你和我一样长期与各种AI助手比如Claude、Cursor、Codex打交道肯定会遇到一个头疼的问题知识无法沉淀。今天你花半小时教会AI助手某个项目的架构细节明天新开一个会话它又忘得一干二净一切得从头再来。或者你和AI协作产出了一堆有价值的代码片段、设计思路和会议纪要它们散落在各个聊天记录里像一座座信息孤岛难以检索和复用。这正是graypirate/Alexandria项目要解决的核心痛点。你可以把它理解为一个专为AI打造的、可自主维护的“活”知识库系统。它不是一个简单的笔记软件而是一套基于MCPModel Context Protocol的服务端和一套可移植的Agent技能SKILL.md目标是把一次性的对话知识变成结构化、可搜索、可被AI主动维护和更新的持久化资产。想象一下你为AI配备了一位专业的图书管理员。这位管理员即Alexandria服务器不仅帮你把零散的资料代码、文档、想法分门别类地归档到“图书馆”wiki的书架上还建立了一套完整的卡片索引系统搜索索引。更重要的是它还能教会AI助手Agent一套“图书管理技能”SKILL.md让AI自己知道什么时候该去查资料、什么时候该更新目录、什么时候该清理过时的信息。这样一来AI就不再是每次会话都“白纸一张”而是拥有了一个不断成长的、属于你们协作项目的长期记忆体。这个项目特别适合开发者、技术写作者、项目经理或任何需要与AI进行深度、持续协作的从业者。无论你是想管理个人技术栈的文档还是想维护一个跨团队的项目知识库Alexandria提供了一套轻量但强大的基础设施让AI从被动的问答机器转变为能主动管理知识的协作伙伴。2. 核心设计哲学技能与工具分离Alexandria的架构设计非常清晰遵循着“技能Skill与工具Tool分离”的原则。理解这一点是掌握其精髓的关键。2.1 MCP工具提供原子化能力MCPModel Context Protocol是Anthropic提出的一套协议旨在为AI模型提供访问外部工具和数据源的标准化方式。在Alexandria中MCP服务器暴露了一系列工具Tools这些是底层的、原子化的操作能力就像图书馆管理员手头的具体工具扫描仪、索引机、书架整理器等。项目提供的核心MCP工具包括工具名称功能描述类比与理解search基于BM25算法和PageRank的全文搜索支持标题、标题、正文等多级权重。图书馆的检索系统。你告诉它关键词它从所有书籍wiki页面中找出最相关的那几本并且会考虑书籍之间的引用关系PageRank来提升权威页面的排名。index_build重建整个知识库的搜索索引。图书管理员重新制作所有书籍的索引卡片。通常在批量新增或修改书籍后必须进行。lint_structural进行结构检查发现孤页、死链、过时页面和索引缺失。图书馆的定期巡检。检查有没有书放错了位置、目录里提到的书是否还在、有没有书太久没人碰需要清理。scaffold为一个新项目脚手架式地创建完整的wiki目录结构。为新图书馆规划区域、设立分类书架、准备好空白目录册和日志本。detect_new扫描raw/目录找出尚未被归档到wiki中的新文件。检查图书馆的“待处理”篮子看看有没有新到的、还没上架的书。extract_session生成一个用于手动归档会话内容的提示词Prompt。图书管理员给你一张标准的“信息归档表单”让你把刚才讨论的内容按格式填进去方便后续整理上架。这些工具本身是“沉默”的它们只提供API接口并不知道何时、为何被调用。这就是“技能”登场的时候。2.2 SKILL.md技能定义调用时机与逻辑技能Skills是告诉AI助手**“在什么情况下应该使用哪个工具”**的说明书。它们以纯文本的SKILL.md文件形式存在存放在.agents/skills/目录下。这种设计使其具有极强的可移植性可以被复制或链接到任何支持该格式的AI主机如Claude Code、Cursor、Windsurf等的技能目录中。Alexandria内置了四个核心技能wiki-init: 初始化技能。当AI检测到用户想要为一个新项目建立知识库时触发此技能。它会引导AI调用scaffold工具创建一整套wiki骨架。wiki-ingest: 内容摄取技能。当用户提出“把这段对话/这个文件保存到知识库”时或当detect_new工具发现有未处理文件时触发。它会引导AI使用extract_session工具生成归档提示并可能后续调用index_build。wiki: 通用查询技能。当用户询问与项目知识相关的问题时如“我们之前是怎么处理X问题的”触发此技能。它会引导AI调用search工具查找相关信息并将结果整合到回答中。wiki-lint: 维护技能。可以定期或在用户要求时触发调用lint_structural工具检查知识库健康度并生成修复建议报告。这种分离的好处显而易见主机无关性MCP工具是标准协议任何兼容MCP的AI客户端都能调用。逻辑可定制技能文件是纯文本你可以根据自己团队的工作流轻松修改或创建新的技能。比如你可以创建一个wiki-weekly-review技能让它每周一自动触发 lint 和生成知识库周报。关注点分离工具开发者只需关注功能的正确性和性能技能编写者则专注于AI的协作逻辑和用户体验。实操心得技能即“工作流触发器”不要把SKILL.md想得太复杂。它本质上就是一个更智能、更场景化的“快捷指令”或“自动化脚本”。它的核心内容是描述触发条件例如“当用户问及项目历史决策时”和预期动作“调用搜索工具并将结果以总结形式呈现”。在Alexandria中这些技能已经为你写好你只需要“安装”它们AI就学会了在合适的时候充当你的图书管理员。3. 从零开始部署与配置Alexandria理论讲完了我们动手把它跑起来。以下步骤假设你使用的是 macOS 或 Linux 系统并且对命令行有基本了解。Windows用户可以通过WSL获得类似体验。3.1 环境准备与依赖安装首先Alexandria 使用Bun作为运行时和包管理器。如果你还没安装Bun这是第一步。# 安装Bun (如果尚未安装) curl -fsSL https://bun.sh/install | bash # 安装完成后重启你的终端或按照提示更新shell配置接下来获取Alexandria的源代码。推荐使用Git克隆到你的本地开发目录。# 克隆仓库 git clone https://github.com/graypirate/Alexandria.git cd Alexandria进入项目目录后安装必要的Node.js/TypeScript依赖。Alexandria的package.json已经定义好了。# 安装项目依赖 bun install这个命令会读取package.json和bun.lockb安装所有必需的包包括MCP服务器框架、文本处理库等。3.2 启动MCP服务器并连接到AI主机安装完依赖Alexandria的MCP服务器就已经准备好了。你可以直接运行它但更重要的是让它被你的AI助手“发现”并连接。方法一直接运行用于测试bun run src/index.ts运行后服务器会在本地启动。但AI助手还无法自动找到它你需要通过配置来建立连接。方法二注册到AI主机以Claude Code为例这是推荐的方式让你的AI助手在每次启动时都能自动连接上你的知识库。Claude CodeCodex通过一个配置文件来管理MCP服务器。首先找到你的Codex配置目录。通常在~/.codex/下。编辑或创建MCP服务器配置文件。# 使用你喜欢的编辑器例如VSCode code ~/.codex/mcp_servers.toml # 或者用nano nano ~/.codex/mcp_servers.toml在mcp_servers.toml文件中添加Alexandria服务器的配置[mcp_servers.alexandria] command bun args [/绝对/路径/到/Alexandria/src/index.ts]请务必将/绝对/路径/到/Alexandria替换为你电脑上实际的Alexandria项目路径。例如/Users/yourname/Projects/Alexandria。保存文件后重启你的Claude Code应用。重启后Codex会读取配置启动并连接到你的Alexandria服务器。你可以在Codex的日志或MCP服务器管理界面中查看连接状态。注意事项路径与权限绝对路径使用args参数时必须提供Bun可执行文件和TypeScript入口文件的绝对路径。相对路径在后台服务上下文中可能无法解析。Bun路径如果bun命令不在系统的标准PATH中你可能也需要在command字段使用绝对路径如/Users/yourname/.bun/bin/bun。端口冲突MCP服务器通常使用标准或动态端口。如果启动失败检查是否有其他进程占用了相关端口。Alexandria的默认配置通常能避免冲突。3.3 安装技能文件到AI主机服务器连接好了接下来要让AI学会“技能”。技能文件位于项目内的.agents/skills/目录。你需要将它们“安装”到AI主机能读取的位置。对于大多数兼容.agents/skills目录结构的主机如一些开源Agent框架可以创建一个全局的技能目录软链接# 确保全局技能目录存在 mkdir -p ~/.agents/skills # 为每个技能创建软链接 ln -sf /绝对/路径/到/Alexandria/.agents/skills/wiki ~/.agents/skills/wiki ln -sf /绝对/路径/到/Alexandria/.agents/skills/wiki-init ~/.agents/skills/wiki-init ln -sf /绝对/路径/到/Alexandria/.agents/skills/wiki-ingest ~/.agents/skills/wiki-ingest ln -sf /绝对/路径/到/Alexandria/.agents/skills/wiki-lint ~/.agents/skills/wiki-lint使用ln -sf-f表示强制-s表示符号链接可以覆盖旧的链接。对于不同的AI主机技能加载路径可能不同。例如Cursor可能需要将技能文件复制到 Cursor 应用数据目录下的特定文件夹。Claude Desktop可能需要通过其插件或技能市场机制安装。你需要查阅你所用的AI主机的文档确认其技能文件的加载路径和格式。Alexandria的SKILL.md是通用格式但放置的目录是关键。3.4 初始化你的第一个知识库一切就绪后你就可以在你的AI助手会话中初始化知识库了。打开一个新的会话例如在Claude Code中你可以直接“告诉”AI你的意图。触发方式一直接对话你可以输入“请为当前这个项目初始化一个Alexandria知识库。”如果技能安装正确AI应该能识别这个意图并触发wiki-init技能。它会引导你确认wiki的根目录通常就是当前项目根目录然后调用scaffold工具。触发方式二使用命令或快捷指令有些AI主机支持斜杠命令。例如理论上配置好后你可以输入/wiki-init来直接触发。初始化完成后你的项目根目录下会生成一系列文件和文件夹结构如下your-project/ ├── .alexandria.json # Alexandria的配置文件 ├── index.md # 知识库的首页/目录 ├── log.md # 知识库的更新日志 ├── CLAUDE.md # 给Claude的上下文指引可适配其他AI ├── AGENTS.md # 给其他AI Agent的指引 ├── raw/ # 原始材料暂存区 │ └── assets/ # 图片等静态资源 ├── wiki/ # 结构化知识存放区 │ └── [focus]/ # 按主题分类的目录 └── search-index.json # 搜索索引初始为空或基础结构至此你的AI专属的“亚历山大图书馆”就建好了地基可以开始使用了。4. 核心工作流实战知识的摄入、检索与维护知识库建好了关键在于日常使用。Alexandria设计了几个核心的工作流对应着不同的技能。我们来逐一拆解看看在实际协作中如何操作。4.1 知识摄入从对话到持久化存储这是最常用的场景。你和AI经过一番深入的讨论解决了一个复杂的技术难题或者设计了一个精妙的架构。你希望把这些智慧结晶保存下来而不是留在滚动条上游的聊天记录里。传统做法手动复制对话打开一个文档粘贴再费力地整理格式。Alexandria做法触发wiki-ingest技能。操作步骤结束一个有价值的会话段落。向AI发出指令例如“请将我们刚才关于‘用户认证微服务设计’的讨论归档到知识库。”AI响应AI识别指令触发wiki-ingest技能。该技能会 a. 调用extract_sessionMCP工具。这个工具不会直接保存内容而是生成一个结构化的提示词Prompt。这个提示词就像一个填空题模板引导AI或你将非结构化的对话内容提取成标题、摘要、关键点、代码片段等结构化信息。 b. AI将生成的提示词呈现给你并等待你的确认或补充。有时AI会直接根据提示词和当前对话历史尝试自己填写一部分内容。确认与编辑你审查AI提取的内容进行必要的修正、润色并指定一个存放路径比如wiki/backend/authentication.md。执行归档AI或你根据交互方式将最终确定的内容写入指定的Markdown文件。更新索引内容写入后AI会自动或在你确认后调用index_build工具重建搜索索引确保新内容能被搜到。实操心得利用raw/目录作为缓冲对于非文本文件或尚未想好如何归类的文本你可以直接把它们丢进raw/目录。之后你可以通过触发wiki-ingest技能或者直接让AI“检查raw目录中是否有新内容需要处理”AI会调用detect_new工具列出文件并引导你进行归档。这就像一个“收件箱”非常适合处理临时性的参考资料。4.2 知识检索让AI成为项目“百事通”当你在后续开发中遇到问题比如“我们当初为什么选择MongoDB而不是PostgreSQL”时你不再需要自己去翻找陈旧的文档或聊天记录。操作步骤直接提问在AI会话中像问一个同事一样提问“我们项目里关于数据库选型的决策是怎么考虑的”AI自动检索wiki技能被触发。AI在后台调用searchMCP工具将你的问题转换为搜索查询词如“数据库 选型 MongoDB PostgreSQL”。智能排序与整合search工具利用BM25算法和PageRank从wiki/下的所有Markdown文件中找出相关性最高的页面。它会优先匹配标题、标题然后才是正文。同时被其他页面引用越多的页面PageRank越高排名也会越靠前。上下文注入与回答AI将搜索到的核心片段作为上下文整合到它的回答中。它可能会说“根据知识库中wiki/architecture/database-decision.md的记录我们当时选择MongoDB主要是基于以下三点考虑1. ... 2. ... 3. ...”提供引用来源一个设计良好的回答通常会附上引用链接文件路径方便你直接点击查看原文。这个过程几乎是隐形的你感受到的是一个拥有“长期记忆”的、更专业的AI助手。4.3 知识维护保持图书馆的整洁有序任何知识库如果不维护很快就会变得混乱、过时。Alexandria通过wiki-lint技能和lint_structural工具将维护工作自动化。定期巡检 你可以定期比如每周一或随时对AI说“请检查一下知识库的健康状态。” AI会触发wiki-lint技能调用lint_structural工具。该工具会扫描整个wiki目录并生成一份报告通常包括孤页Orphans没有被任何其他页面通过链接引用的页面。它们可能是被遗忘的草稿。死链Broken Links指向不存在的wiki页面或外部资源的链接。过时页面Stale超过一定时间可在配置中设定未被更新的页面可能需要复审。索引缺失Index Gaps搜索索引中可能缺失的关键词。基于报告的维护 AI不仅会给出报告还会根据报告提出具体的行动建议。例如“发现孤页wiki/experimental/old-idea.md是否考虑将其链接到index.md或相关页面或删除它”“wiki/api/gateway.md中有一个指向wiki/api/auth-v1.md的链接但后者已重命名为wiki/api/authentication.md需要修复。” 你可以授权AI直接执行某些修复如重命名文件、更新链接或由你手动处理。手动触发索引重建 如果你通过Git拉取了同事更新的wiki内容或者批量修改了大量文件记得告诉AI“知识库有大量更新请重建搜索索引。” AI会调用index_build工具确保搜索功能的准确性。5. 搜索索引的深度解析与调优Alexandria的搜索体验之所以流畅其核心在于那个预构建的search-index.json文件。它不是一个简单的关键词列表而是一个精心设计的数据结构。理解它有助于你调优搜索效果。5.1 索引结构里面到底存了什么当你运行index_build后会在wiki根目录生成一个search-index.json文件。它的结构大致如下为简洁做了简化{ “pages”: { “wiki/backend/auth.md”: { “title”: “用户认证微服务设计”, “headings”: [“概述”, “技术选型”, “API设计”, “安全考量”], “firstParagraph”: “本文档描述了XX系统的用户认证模块...” “body”: “完整的Markdown正文内容...”, “updated”: “2023-10-27T08:30:00Z”, “links”: [“wiki/architecture/decisions.md”, “wiki/frontend/sdk.md”] } // ... 其他所有页面 }, “termIndex”: { “认证”: { “wiki/backend/auth.md”: 5, “wiki/api/spec.md”: 2 }, “微服务”: { “wiki/backend/auth.md”: 3, “wiki/architecture/overview.md”: 10 }, “JWT”: { “wiki/backend/auth.md”: 8 } // ... 所有分词后的词项 }, “pageRank”: { “wiki/backend/auth.md”: 0.85, “wiki/architecture/overview.md”: 1.42, // ... 所有页面的PageRank分数 } }pages对象存储了每个页面的元数据和快照。注意body字段存储了全文用于高亮和详细匹配。termIndex倒排索引这是搜索速度的关键。它记录了每个词项如“认证”出现在哪些文档auth.md中以及出现的频率5次。搜索时直接查找词项就能立即知道相关文档无需遍历所有页面。pageRank对象借鉴Google的算法根据页面间的链接关系links字段计算出的权重。被越多重要页面链接的页面得分越高。5.2 排名算法结果如何排序当你在搜索框输入“认证 微服务”时search工具会分词将查询拆分为 [“认证” “微服务”]。检索从termIndex中找出包含这些词的所有页面。计算BM25相关性分数这是一个信息检索领域的经典算法综合考虑了词频在该文档中出现的次数、逆文档频率该词在所有文档中的常见程度和文档长度。简单说一个词在某个文档中出现得越多且这个词本身越不常见那么这个文档对该词的BM25分数就越高。应用权重和PageRank词出现在标题title中权重 ×10。词出现在标题headings中权重 ×5。词出现在首段firstParagraph中权重 ×3。词出现在正文body中权重 ×1。然后将加权后的BM25分数与页面的PageRank分数结合最终分数 BM25总分 * (1 alpha * PageRank)。其中alpha是一个可调参数默认可能为0.5用于控制PageRank的影响力。排序将所有候选页面按最终分数降序排列返回Top N个结果。5.3 调优实战让你的搜索更精准如果你发现某些重要的页面总是搜不到或者排名靠后可以尝试以下方法优化页面标题和标题这是提升权重最有效的方法。确保核心关键词出现在# 标题和## 二级标题中。构建内部链接网络多使用[[wiki/path/to/other-page]]这样的维基链接。这不仅能帮助读者导航更能提升被链接页面的PageRank使其在搜索结果中排名更高。一个被多处引用的“核心概念”页面自然会成为权威页面。首段摘要要精炼在文档开头用一段话概括核心内容并包含关键词。这能利用“首段权重×3”的加成。审视.alexandria.json配置未来版本可能会开放排名算法参数如权重因子、alpha值的配置。你可以根据自己知识库的特点进行调整。例如一个代码库文档可能希望正文中的代码片段权重更高。定期重建索引任何手动修改了wiki/下的文件或者通过非Alexandria工具更新了内容务必运行index_build来保证索引最新。踩坑记录索引与内容不同步我最开始犯的一个错误是直接在文件系统中复制或重命名了wiki文件但没有触发索引重建。导致搜索时要么找不到新文件要么点击链接是404。黄金法则任何对wiki/目录的改动最后一步都应该是通过AI调用index_build或者直接运行bun run src/index.ts --tool index_build如果服务器以独立模式运行。最好将索引更新作为归档工作流的最后一个强制步骤。6. 常见问题排查与进阶技巧即使设计再精良在实际使用中也可能遇到各种小问题。这里汇总了一些常见情况及解决方法以及一些能提升效率的进阶思路。6.1 连接与配置问题问题现象可能原因排查步骤与解决方案AI助手完全无法识别Alexandria技能如输入指令无反应。1. MCP服务器未启动或连接失败。2. 技能文件未放置在AI主机正确的加载路径。1.检查MCP服务器在终端直接运行bun src/index.ts看是否有错误输出。确保配置的路径正确。2.检查技能路径确认~/.agents/skills/或主机指定路径下的符号链接有效 (ls -la)。尝试直接cat一个SKILL.md文件确保内容可读。3.重启AI主机许多主机只在启动时加载配置和技能。AI提示“找不到MCP工具”或调用工具失败。1. MCP服务器运行异常。2. 工具名称拼写错误主机端调用问题。3. 服务器与主机协议版本不兼容。1.查看主机日志AI主机通常有日志窗口查看MCP通信错误信息。2.验证工具列表有些MCP客户端支持列出所有可用工具。检查search,index_build等工具是否在列表中。3.更新版本确保Alexandria和你的AI主机都是较新版本。搜索返回结果慢或索引重建耗时很长。wiki文档数量非常多例如上千个。1.这是预期行为索引构建需要读取和分词所有文件。对于大型知识库考虑在夜间或空闲时执行index_build。2.优化文档避免单个Markdown文件过大。按主题拆分成多个小文件。3.硬件确保项目位于SSD硬盘上。6.2 内容与工作流问题问题现象可能原因排查步骤与解决方案新归档的内容在搜索中找不到。索引未更新。search工具读取的是旧的search-index.json。手动触发索引重建明确对AI说“请立即重建知识库搜索索引。” 或直接调用index_build工具。维基链接[[...]]点击无效或跳转错误。1. 链接的页面不存在大小写、路径错误。2. 某些编辑器或预览工具不支持此语法。1. 运行lint_structural工具它能检测出死链。2. 使用支持Wiki语法的Markdown编辑器如Obsidian、VSCode配合Wiki Links插件。3. 确保链接路径相对于wiki根目录且不含.md后缀例如[[wiki/backend/auth]]。extract_session工具生成的提示词模板不符合我的需求。默认的提取模板是通用的可能不适合特定类型的内容。自定义提示词这是进阶用法。你可以直接修改src/tools/extract-session.ts中生成提示词的逻辑。或者更优雅的方式是在prompts/目录下创建你自己的session-end-custom.md然后在调用工具时让AI参考你的自定义模板。这需要对项目代码有一定了解。6.3 进阶技巧与扩展思路多知识库支持Alexandria默认管理当前目录下的一个知识库。但你可以运行多个Alexandria服务器实例每个实例指向不同的目录通过环境变量或启动参数并在AI主机中配置多个MCP服务器。这样你可以在不同项目间切换不同的知识库。只需在提问时指明“请在项目A的知识库中搜索...”。与Git集成将整个wiki目录包括search-index.json纳入版本控制如Git。search-index.json是衍生文件可能会产生合并冲突。一个策略是在.gitignore中忽略它而在项目启动或构建脚本中自动重建索引。更协作友好的方式是将索引重建作为CI/CD的一个步骤。自定义技能开发现有的四个技能是起点。你可以模仿它们的格式创建自己的SKILL.md。例如wiki-meeting-minutes.md: 专门用于提取和格式化会议纪要的技能。wiki-code-review.md: 将代码审查意见自动归档到相关模块文档下的技能。 技能的本质是文本指令发挥你的想象力定义属于你团队的最佳实践。备份与恢复定期备份wiki/目录和.alexandria.json配置文件。search-index.json可以丢失因为可以重建。最重要的资产是你的Markdown内容。性能监控随着文档增长关注index_build的时间。如果过长可以考虑只对变更的文件进行增量索引但这需要修改源码。对于超大型知识库可能需要考虑换用更专业的全文搜索引擎后端如MeiliSearch、Typesense但这会大幅增加复杂性。我个人在几个项目中深度使用Alexandria后最大的体会是它带来的最大价值不是检索速度而是改变了人与AI协作的心智模型。我不再觉得AI是“健忘的”而是把它当作一个配备了外部大脑的伙伴。我会习惯性地在讨论复杂问题前说一句“让我们先看看知识库里有什么”也会在讨论结束后自然地进行“归档”。这个过程逐渐沉淀下来的是一个真正活着的、与项目共同成长的知识体而不仅仅是堆砌的文档。