知识库知识管理协同办公后端前端【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址https://gitcode.com/GitHub_Trending/ou/outline点击查看免费下载导读Outline 是面向成长型团队的开源知识库knowledge base其服务端内置了一个完整的 Model Context ProtocolMCP服务器让 Claude 等 AI 客户端能够通过统一的工具接口检索、创建和更新知识库中的文档、集合、评论、模板与附件。本文以仓库内 server/mcp/README.md 为骨架结合server/mcp/tools/与server/mcp/skills/下的源码实现系统讲解 MCP 服务器的目录结构、工具注册机制、权限过滤模型、每个工具的输入参数与返回值以及本地开发联调时的证书配置。读完本文你将掌握 Outline MCP 服务器的完整工具清单、每个工具的调用方式与适用场景并能据此在 Claude 等 MCP 客户端中安全地操作 Outline 工作区。一、目录结构与核心定位server/mcp/目录是 Outline 的 MCP 服务器实现所在其中 HTTP 入口位于 server/routes/mcp。整个目录分为两个核心子模块tools/—— MCP 客户端可直接调用的工具集合每个工具是一个自包含的功能单元负责执行一项具体任务skills/—— 通过 skills 扩展skills/list、skills/get对外提供的技能包本质上是给 Agent 的操作手册。每个工具都被设计为自包含self-contained它独立完成参数校验、权限校验、业务执行与结果格式化不依赖其他工具的中间状态。这种设计使得 AI 客户端可以按需调用任意工具而无需维护复杂的调用顺序。从源码结构看工具按领域划分为 7 个注册函数统一在 server/mcp/index.ts 中被装配到同一个McpServer实例上attachmentTools(server, scopes); collectionTools(server, scopes); commentTools(server, scopes); documentTools(server, scopes); fetchTool(server, scopes); templateTools(server, scopes); userTools(server, scopes);服务器元信息与能力声明createMcpServer 负责创建服务器实例声明了name: outline、title: Outline、version取自 package.json 的版本号websiteUrl当前部署的 origin用于生成绝对资源地址icons192×192 与 512×512 两种尺寸的服务器图标指向public/images/icon-192.png与icon-512.pngcapabilities声明支持tools、resources以及extensions注册了io.modelcontextprotocol/skills扩展instructions一段默认的使用说明书告诉 AI 客户端如何正确操作文档详见下文内置指令一节。二、HTTP 入口与认证链路MCP 服务通过 server/routes/mcp/index.ts 暴露为单端点 POST/mcp限流应用了RateLimiterStrategy.OneThousandPerHour策略每小时 1000 次请求认证允许MCP、OAuth、API三种认证类型由auth中间件解析出user、token与scope团队开关若当前团队未开启TeamPreference.MCP偏好直接返回 404拒绝服务标记用户为调用用户设置UserFlag.MCP标志并持久化按 token 的 OAuth scope 创建服务器实例将scope数组传入createMcpServer工具注册时据此过滤见下一节传输层使用 SDK 的StreamableHTTPServerTransport流式 HTTP 传输并把手请求上下文中的认证信息注入为extra.authInfo供工具处理器通过getActorFromContext取回当前用户。值得注意的是RFC 9728 / MCP auth 规范要求/mcp端点在返回 401 时必须附带WWW-Authenticate头指向 OAuth 受保护资源元数据文档并声明所需 scope以便客户端自主启动授权流程——该中间件已完整实现这一行为。三、权限模型按 OAuth Scope 动态过滤工具Outline MCP 服务器最核心的设计是工具按 OAuth scope 动态注册。每个注册函数如documentTools、collectionTools内部都通过 AuthenticationHelper.canAccess 判断当前 token 是否拥有对应 scope只有授权后才调用server.registerToolif (AuthenticationHelper.canAccess(documents.list, scopes)) { server.registerTool(list_documents, { ... }); }这意味着同一部署、不同 token 看到不同的工具清单。例如只有documents.createscope 的 token 不会在tools/list中看到create_document统一入口工具fetch采用至少具备一类信息 scope 才注册的规则见 fetch.ts并据此动态拼装resource枚举只暴露当前 token 能读取的资源类型。在授权之上每个工具内部还会再执行一层行级权限校验policy check例如list_documents在按 collection 过滤时会先authorize(user, readDocument, collection)documents.tsdelete_document会区分archive与delete两种动作分别授权。因此即便 token 拥有对应 scope也仍受团队/集合/文档级别的成员权限约束形成scope 管功能、policy 管数据的双层防护。四、内置指令AI 客户端的行为准则createMcpServer会把一段defaultInstructions注入到服务器配置index.tsMCP 客户端如 Claude会将其作为系统提示的一部分。这段指令定义了四条关键约定理解它有助于推断工具的预期用法文档正文不允许以 H1 开头——标题作为独立字段存储应通过title参数设置正文从段落或更低层级标题开始提及语法——文档与集合的 Markdown 支持Display Name形式可通过list_users工具查询用户 ID附件读取方式——图片与附件用fetch工具设resource: attachment并传入附件 ID 或/api/attachments.redirect?id...URL将返回用于下载的签名 URLHTML 与图片导入——从包含图片/视频的 HTML 创建文档时应以format: html传入标记远程 URL 与 base64 媒体会自动导入为附件不要先把 HTML 转成 Markdown也不要把 HTML 文件本身作为附件上传。此外创建文档时若用户要求按模板创建应先用list_templates找到匹配模板结果已包含模板 Markdown 正文原样使用则把其 ID 作为templateId传给create_document需改造则修改返回正文后作为text传入——两种方式都无需额外的 fetch 调用。五、Tools 工具集全览5.1 文档工具documentTools文档工具是最核心的一组定义于 server/mcp/tools/documents.ts覆盖文档生命周期工具名对应 scope功能关键参数list_documentsdocuments.list全文搜索文档无 query 时列出最近文档可选按集合过滤、包含已归档query,collectionId,includeArchived,offset(默认 0),limit(默认 25最大 100)list_collection_documentscollections.documents返回集合内完整层级文档树含嵌套子文档不含草稿与归档collectionIdcreate_documentdocuments.create从 Markdown 或 HTML 创建文档可用模板预填充title,text,format(markdown/html),sourceFileName,collectionId/parentDocumentId,templateId,icon,color,publish(默认 true),fullWidthmove_documentdocuments.move移动文档或调整同级顺序id,collectionId或parentDocumentId,index(零基)update_documentdocuments.update更新标题/正文/图标/颜色等支持四种编辑模式id,title,text,editMode,findText,icon,color,publish,fullWidthdelete_documentdocuments.delete移入回收站可恢复或归档id,archive,reasonrestore_documentdocuments.restore恢复归档/删除的文档可指定新集合id,collectionId几个值得展开的实现细节搜索与精确匹配。list_documents在提供 query 时走全文搜索提供商SearchProviderManager.getProvider()即 PostgreSQL 全文搜索或插件实现的搜索服务。若 query 形似文档 ID 或 urlIdUrlHelper.SLUG_URL_REGEX会先做精确查找并置于结果顶部避免 AI 按 ID 查找时结果被埋没documents.ts。搜索请求还会被记录为SearchQuerySource.MCP类型的搜索历史且只在首页offset 0记录避免翻页产生重复记录documents.ts。四种编辑模式editMode。update_document的editMode取自 shared/types 的TextEditModereplace默认整体替换文档内容append/prepend在文末/文首追加patch按findText精确匹配 Markdown 子串只替换该部分保留文档其余部分无法用 Markdown 表达的富格式高亮、评论、表格宽度等。工具描述明确建议编辑既有文档内容时优先用patch模式。patch模式成功后会把更新后的完整 Markdown 正文作为第二个 content 块回传供调用方核对实际应用结果documents.ts。空更新失败校验。update_document通过比对revisionCount判断是否真的发生了持久化——每次保存都会递增该计数若计数未变则返回错误而不是伪造成功documents.ts。HTML 导入走任务队列。create_document在format: html时不会在主进程解析 DOM会阻塞事件循环而是交给DocumentImportTask.scheduleAndWait异步处理documents.ts。5.2 集合工具collectionTools定义于 server/mcp/tools/collections.ts对应collections.list/collections.create/collections.update/collections.delete四个 scope工具名功能关键参数list_collections列出当前用户可访问的集合可按名称搜索、分页query,offset,limitcreate_collection创建集合用于组织文档name,description(Markdown),icon,colorupdate_collection按 ID 更新集合仅更新提供的字段id,name,description,icon(可传 null 移除),colordelete_collection删除集合其中未归档文档一并删除或归档id,archive,reason实现要点list_collections会同时过滤deletedAt与archivedAt均为空且集合 ID 必须在用户可见集合内user.collectionIds()排序采用index collate C加updatedAt DESCcollections.ts与文档搜索一致query 形似集合 ID/urlId 时也会做精确匹配并置顶返回的集合对象包含Markdown 格式的 description而非 ProseMirror JSON方便 AI 客户端直接阅读presentCollection使用includeText: trueupdate_collection与update_document一样有无变化即报错的防护collection.changed()为空时返回错误。5.3 评论工具commentTools定义于 server/mcp/tools/comments.ts覆盖评论的增删改查工具名功能关键参数list_comments按文档或集合列出评论可按父评论/解决状态过滤documentId或collectionId至少其一,parentCommentId,statusFilter,offset,limitcreate_comment在文档上创建评论Markdown 正文可回复他人或锚定到文档片段documentId,text,parentCommentId,anchorText,anchorPrefix,anchorSuffixupdate_comment更新评论正文或解决/取消解决整个线程id,text,status(resolved/unresolved)delete_comment删除评论需为作者或团队管理员id最值得注意的能力是行内评论锚定inline comment anchoringcreate_comment支持传入anchorText文档中的纯文本子串服务端会通过ProsemirrorHelper.applyCommentMarkByText在 ProseMirror 文档状态中定位该文本并应用评论标记comments.ts。当anchorText在文档中出现多次时可用anchorPrefix/anchorSuffix锁定特定一次出现。锚定过程会先对文档行加Transaction.LOCK.UPDATE锁防止并发评论标记覆盖状态更新。若无法匹配返回ValidationError。评论响应中的text字段由comment.toMarkdown()生成同样避免了 AI 解析 ProseMirror JSON 的负担。5.4 附件工具attachmentTools定义于 server/mcp/tools/attachments.ts目前只有一个工具create_attachmentscopeattachments.create——为上传请求预签名 URL。参数为contentTypeMIME 类型、name含扩展名的文件名、size字节数。服务端会校验文件大小不超过AttachmentPreset.DocumentAttachment预设的上限超限返回人类可读的错误信息生成附件记录与存储 key根据环境变量AWS_S3_UPLOAD_METHOD分支put返回预签名 PUT URL 及 headers并附带可直接执行的curlCommandpost默认返回uploadUrl与 multipart 表单字段附带 POST 形式的curlCommand。返回值中的attachment.url即文档中可直接引用的附件地址。工具描述明确提示用返回的uploadUrl/表单字段通过 multipart POST例如 curl直传文件无需经过 Outline 服务器中转。若存储后端不支持 PUT 上传会返回InvalidRequestError提示改用post。5.5 模板工具templateTools定义于 server/mcp/tools/templates.tslist_templatesscopetemplates.list——列出用户可访问的文档模板包括工作区级模板与可访问集合内的模板。参数collectionId可选过滤、offset、limit。每个结果都包含模板正文的 Markdowntext字段由DocumentHelper.toMarkdown渲染不含标题因此可以直接把id作为templateId传给create_document原样套用或先修改正文再作为text传入——无需额外 fetchtemplates.ts。查询逻辑上草稿模板仅对创建者可见publishedAt为空且createdById非当前用户时排除未传collectionId时返回工作区级模板collectionId为空加上用户可见集合内的模板templates.ts。5.6 用户工具userTools定义于 server/mcp/tools/users.tslist_usersscopeusers.list——列出工作区用户用于解析 提及所需的用户 ID。参数query按姓名/邮箱搜索、roleadmin/member/viewer/guest、filteractive/suspended/invited/all默认 active、offset、limit。权限细节非管理员默认无法看到被暂停用户suspendedAt非空即排除filter: suspended仅对管理员生效姓名/邮箱搜索使用 PostgreSQLunaccent函数做不区分重音与大小写的模糊匹配users.ts返回结果按姓名升序邮箱与详细字段是否返回取决于当前用户对目标用户的readEmail/readDetails策略。5.7 统一资源读取工具fetchTool定义于 server/mcp/tools/fetch.ts是唯一一个覆盖多资源类型的瑞士军刀fetch——按resource类型读取单个实体resource枚举document/collection/user/attachment/template由当前 token 的 info scope 动态拼装。id参数既接受纯 ID也接受完整 URL——extractId 会从 URL 中提取id查询参数或最后一段路径作为 slug。各资源返回差异document返回文档元信息JSON content 块完整 Markdown 正文第二个 content 块并附带breadcrumb、公开分享shareUrl、评论数collection返回集合信息 完整层级文档树presentNavigationNode数组userid为self/me/current_user不区分大小写时返回当前认证用户attachment返回name、contentType、size与短期有效的签名下载 URLsignedUrl附件属于工作区团队而非单个文档因此同一团队任何成员均可读取跨团队访问抛出AuthorizationErrortemplate返回模板元信息 Markdown 正文。六、Skills 扩展给 Agent 的操作手册除了可调用的工具MCP 服务器还通过 skills 扩展io.modelcontextprotocol/skillsSEP-2640对外暴露一组技能。实现位于 server/mcp/skills/index.ts每个技能目录必须包含SKILL.md以 YAML frontmatter 声明name须匹配目录名与description启动时从server/mcp/skills读取全部目录并缓存含各文件的 sha256 digest 与字节数每个文件注册为skill://outline/dir/file资源skills/list返回全部技能清单skills/get按 URI 返回单个技能文本文件按 UTF-8 文本返回二进制文件按 base64 blob 返回。仓库内置 4 个技能server/mcp/skillsfind-and-cite从知识库检索答案并引用源文档——示范了list_documentsfetchlist_collection_documents的组合用法与引用规则collection-digest生成集合内容摘要meeting-notes整理会议纪要capture-conversation把对话沉淀为文档。以find-and-cite为例SKILL.md它的快速开始五步法本质上是工具编排的最佳实践先用list_documents的context片段挑选候选再用fetch读取全文回答时引用原文并附文档 URL文档冲突时展示各自的updatedAt让用户判断时效。这类技能让 AI 客户端在不额外编写代码的情况下获得领域化的使用范式。七、工具响应与错误约定所有工具统一使用 server/mcp/util.ts 中的两个辅助函数格式化结果success(data)将结果包装为 JSON 文本 content 块空数组返回单个[]文本块避免部分 MCP 客户端拒绝content: []导致零结果与响应异常无法区分util.tserror(err)返回isError: true的文本块内容为错误消息字符串util.ts。两个重要的入参约定optionalString()对可选字符串字段ID、query 等做→undefined的转换兼容 MCP 客户端对想省略的字段发送空字符串的行为而正文/描述类字段空字符串是合法值如清空描述应使用z.string().optional()直接声明util.ts分页参数offset/limit统一使用z.coerce.number()以兼容字符串形式的数字入参limit上界为 100。所有处理器都被withTracing包裹util.ts每次调用在 Datadog 追踪中生成一个outline-mcp服务下的 span资源名为工具名并打上mcp.tool、request.userId、request.teamId标签便于按用户/团队排查问题。八、本地开发用 Claude 联调 MCPserver/mcp/README.md 给出了本地联调的关键前提开发环境使用 mkcert 签发本地 HTTPS 证书Claude 桌面客户端默认不信任 mkcert 的根 CA因此启动时必须注入根证书路径否则 MCP 连接会因 TLS 校验失败而中断NODE_EXTRA_CA_CERTS$(mkcert -CAROOT)/rootCA.pem claude$(mkcert -CAROOT)会展开为 mkcert 根 CA 目录rootCA.pem即其中的根证书。该命令适用于在开发环境直接用 Claude 客户端连接本地 Outline 的 MCP 端点做端到端调试。九、测试与验证MCP 工具均有配套的集成测试例如 server/mcp/tools/documents.test.ts1113 行通过buildOAuthUsercallMcpTool的组合模拟 OAuth token 调用各工具验证了list_documents返回最近文档且 URL 为绝对地址、不包含模板文档、可按集合过滤权限边界不同 scope/角色下工具可见性与数据可见性分页、搜索上下文、精确匹配置顶等行为。fetch.test.ts、collections.test.ts、comments.test.ts、attachments.test.ts、util.test.ts以及路由层的 server/routes/mcp/index.test.ts 覆盖了其余工具与认证链路。需要本地跑测试时可参照 package.json 中定义的测试脚本在仓库内执行。十、小结安全、一致、可组合的工具设计回顾整个 Outline MCP 工具子系统可以提炼出三个贯穿始终的设计原则安全默认OAuth scope 决定能调什么工具policy 决定能读哪些数据双层校验确保 AI 客户端只能在其权限范围内操作未开启 MCP 偏好的团队直接 404。一致性约定所有工具统一走success/error响应封装、统一的分页参数offset/limit、上限 100、统一的optionalString空值处理、统一的 Datadog 追踪AI 客户端几乎不需要为不同工具适配不同协议细节。面向 Agent 的可组合性fetch提供统一读取入口list_templates直接返回模板正文update_document的patch模式保护富格式而skills/进一步把常用工具编排固化为可复用的操作手册——三者结合使 AI 能在 Outline 知识库上完成从检索 → 阅读 → 引用 → 新建/更新 → 评论协作的完整工作流。赞分享知识库知识管理协同办公后端前端【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址https://gitcode.com/GitHub_Trending/ou/outline点击查看免费下载相关推荐browser-use 集成指南MCP 服务器、Skills 与文档 MCP 全配置详解browser use 集成指南MCP 服务器、Skills 与文档 MCP 全配置详解 导读 本文围绕 browser use 开源项目的集成能力展开系统人工智能AI Agent浏览器控制GUI 自动化MCP 服务如何在移动设备上部署高性能AI模型MiniCPM-V Redmi K70端侧优化实战指南如何在移动设备上部署高性能AI模型MiniCPM V Redmi K70端侧优化实战指南 你是否曾因为GPU内存不足而无法运行大型多模态AI模型是否渴望在移人工智能大模型多模态计算机视觉NLP微调openBMB如何通过Mods与MCP服务器集成扩展AI命令行工具能力的完整指南如何通过Mods与MCP服务器集成扩展AI命令行工具能力的完整指南 在命令行环境中使用AI工具时你是否遇到过功能受限、资源不足的问题 Mods 作为一款轻AI 应用CLI大模型上一篇终极指南jsPDF批量处理API如何一次生成多个PDF文档下一篇如何用jsPDF创建夜间阅读友好的PDF暗模式完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 发送类型安全的 GraphQL 文档)
