数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/ChatLab/ChatLab点击查看免费下载导读本文围绕 ChatLab 仓库中的packages/mcp-server子包npm 包名chatlab-mcp完整讲解如何将本地优先的 ChatLab 聊天记录通过 Model Context ProtocolMCP以只读方式暴露给 ClaudeCode、Cursor、Codex、OpenClaw 等 MCP 客户端。读完本文你将掌握npx -y chatlab-mcp的启动方式、MCP 客户端 JSON 配置、数据目录与只读约束、全部可用工具与资源的调用语义并能通过源码理解其工具注册、SQL 安全边界与输出格式化原理。一、chatlab-mcp 是什么chatlab-mcp是 ChatLab 仓库中独立发布的一个 npm 包位于 packages/mcp-server它把本地已导入的 ChatLab 聊天会话数据通过 MCP 协议暴露给外部 AI 代理通过stdio传输层与 MCP 客户端通信提供只读访问会话发现session discovery、关键词搜索、成员统计、时间分析、SQL 查询、会话上下文工具包描述明确为 ChatLab MCP Server — shared core for CLI and Desktop, also usable standalone via npx即它同时是 CLI 与桌面端共用的 MCP 核心也可独立使用。从仓库源码看这个包的核心职责由三部分组成入口与运行时初始化bin.ts 读取配置、初始化数据目录与数据库管理器然后调用startMcpServerMCP 服务核心server.ts 负责把openchatlab/tools注册为 MCP 工具、把会话数据注册为 MCP 资源并通过StdioServerTransport连接公开 APIindex.ts 导出startMcpServer、resolveMcpLocale以及相关类型。二、快速开始一行命令启动使用 npx 直接运行无需预先安装npx -y chatlab-mcp该命令会启动一个 MCP stdio 服务器并等待 MCP 客户端接入。它不会打印帮助界面——因为 stdout 被保留给 MCP 协议消息使用所有日志一律输出到 stderr这一点在 bin.ts 的注释中有明确说明All logs go to stderr; stdout is reserved for MCP protocol communication。启动流程源码可见于 bin.tsloadConfig()加载 ChatLab 配置含用户自定义数据目录等initStandaloneMcpRuntime(version, userDataDir)完成运行时初始化startMcpServer(...)注册工具与资源并开始监听任何致命错误会写入 stderr 并以退出码 1 结束进程。三、MCP 客户端配置3.1 使用 npx 方式推荐在 MCP 客户端如 Claude Code、Cursor、Codex 等的配置中将chatlab加入mcpServers{ mcpServers: { chatlab: { command: npx, args: [-y, chatlab-mcp] } } }3.2 使用全局安装方式如果已将chatlab-mcp全局安装可直接使用二进制名对应 package.json 中bin: { chatlab-mcp: bin/chatlab-mcp.js }{ mcpServers: { chatlab: { command: chatlab-mcp } } }四、数据目录与只读约束4.1 数据来源chatlab-mcp读取与 ChatLab 相同的本地数据目录~/.chatlab/如果你在~/.chatlab/config.toml中配置了自定义 ChatLab 数据目录MCP 服务器会自动使用该配置——对应 bin.ts 中的loadConfig()与config.data.user_data_dir逻辑。4.2 只读原则服务器是只读的它只打开已存在的 ChatLab 会话数据库不修改任何聊天数据。同时工具层面的 SQL 查询被限定为只读 SELECT详见下文SQL 查询小节从数据库访问与工具语义两个层面共同保证数据安全。4.3 运行时实现细节standalone-runtime.ts 展示了独立模式下的初始化逻辑NodePathProvider负责数据目录定位并ensureAllDirs()确保目录存在assertDataDirCompatible(pathProvider, runtime)校验数据目录与运行时版本兼容DatabaseManager作为数据库管理器同时满足 types.ts 中定义的McpDatabaseManager契约listSessionIds()与open(sessionId)。五、可用能力工具与资源全景5.1 工具清单从注册表看完整能力MCP 服务器注册的工具来自 packages/tools/src/registry.ts 中的MCP_TOOL_REGISTRY。该注册表是面向外部 AI 代理的精简集由两部分组成MCP 专属工具list_sessions会话发现、get_session_info会话信息共享核心与分析工具SHARED_TOOLSget_chat_overview、search_messages、deep_search_messages、get_recent_messages、get_message_context、get_segment_messages、get_members、get_schema、get_member_stats、get_time_stats、get_member_name_history、get_conversation_between、get_segment_summaries、response_time_analysis、keyword_frequency、render_chart、execute_sql。注册表注释registry.ts明确说明省略了声明式 SQL 便捷工具以降低工具 schema 的 token 开销约节省 40%LLM 需要自定义查询时可以直接使用execute_sqlget_schema。在 server.ts 中每个工具都会以chatlab_前缀注册为 MCP 工具名如chatlab_list_sessions并在参数中统一注入session_id除list_sessions外和可选的format参数。5.2 工具功能分类对应原文档Available Capabilities工具按用途可分为能力类别对应工具会话发现list_sessions、get_session_info会话元数据与库结构get_chat_overview、get_schema消息与关键词搜索search_messages、deep_search_messages最近消息与上下文get_recent_messages、get_message_context、get_segment_messages、get_segment_summaries成员与成员活动get_members、get_member_stats、get_member_name_history、get_conversation_between时间与活跃分析get_time_stats、response_time_analysis、keyword_frequency只读 SQL 查询execute_sql、get_schema可视化辅助render_chart5.3 资源Resources注册除工具外server.ts 还注册了三个 MCP 资源便于客户端直接读取结构化数据chatlab://sessions所有已导入会话的列表JSON含 id、name、platform、typechatlab://sessions/{sessionId}/meta会话元信息合并getSessionMeta与getSessionOverview结果chatlab://sessions/{sessionId}/schema会话数据库的表结构getDatabaseSchema。5.4 输出格式text 与 json每个工具都支持可选的format参数text或json其中execute_sql与get_schema默认输出json见JSON_DEFAULT_TOOLSserver.ts其余工具默认输出text由 format.ts 中的formatToolResultAsText把 JSON 结果转换为紧凑文本包括消息列表按发送者连续合并 截断输出单条内容上限 200 字符、合并内容上限 400 字符MAX_CONTENT_LENGTH/MAX_MERGED_CONTENT_LENGTH会话列表输出为N sessions:形式的清单关键词/排名数组输出为编号列表。此外isValidMessageformat.ts会过滤噪声消息占位符图片/语音/视频/文件/表情/红包等、纯 emoji、过短无意义文本如 ok、lol、群系统消息邀请/退群/撤回等从而为 LLM 节省 token 并提升分析信噪比。六、工具详解与调用语义6.1 会话发现list_sessions定义见 packages/tools/src/definitions/sessions.ts。参数仅一个可选的keyword用于按会话名称筛选。返回每个会话的 id、名称、平台、消息数与成员数等概览信息并以{ total, sessions }的 JSON 结构返回。6.2 SQL 查询execute_sql 与 get_schema定义见 packages/tools/src/definitions/sql-query.tsexecute_sql参数sql必填与max_rows可选默认 1000。工具描述明确要求只读 SELECT 查询结果行数会被max_rows二次截断clampSqlResultRows防止过大结果集污染上下文get_schema无参数返回所有表的 CREATE TABLE 语句用于辅助编写 SQL。使用建议来自工具描述原文先调用get_schema查看表结构再编写 SELECT 查询并显式添加LIMIT。6.3 其他核心工具的参数速查以下参数说明取自 tool-metadata.ts 中的英文元数据非中文 locale 时向 LLM 展示工具关键参数search_messageskeywords必填、sender_id、limit、start_time/end_timeYYYY-MM-DD HH:mmdeep_search_messages同上使用更慢的子串匹配适合精确短语或常规搜索漏检的场景get_message_contextmessage_ids、context_size默认 20每条消息前后各取多少条get_memberssearch、limitget_member_statstopget_time_statstypehourly / weekday / daily / monthly、start_time、end_timeget_conversation_betweenmember_id_1、member_id_2、limit、时间范围response_time_analysistop_n默认 10、时间范围基于回复间隔的中位数与均值keyword_frequencytop_n默认 50、时间范围通过 NLP 分词统计高频词get_segment_summarieskeywords、limit默认 20、时间范围get_session_infoinclude_members是否包含成员列表默认 false6.4 本地化描述工具的描述与参数说明会根据 locale 自动切换中英文server.ts 调用getLocalizedToolMetadata当配置语言或系统 locale 为中文时使用中文描述否则使用英文描述tool-metadata.ts。resolveMcpLocalestandalone-runtime.ts优先取配置中locale.lang未配置时回退到系统 locale。七、运行要求与依赖原文档 Requirements 部分明确Node.js 22.19 或更高版本——对应 package.json 中engines: { node: 22.19.0 }已有 ChatLab 数据位于~/.chatlab/。依赖说明同样可在 package.json 确认better-sqlite3^12.4.6是运行时依赖在缺少对应预编译二进制的平台上npm 可能需要本地编译工具来构建原生模块node-rs/jieba^2.0.1是可选依赖用于改进关键词频率工具的中文分词效果如果不可用MCP 核心功能仍然正常工作。其余核心依赖包括modelcontextprotocol/sdk^1.12.1、zod^3.24.4用于参数校验、smol-toml^1.3.1用于读取 TOML 配置。八、包级 API进阶用法高级调用方可以直接导入共享的服务核心index.tsimport { startMcpServer } from chatlab-mcpstartMcpServer接受McpServerOptionstypes.tsversion暴露给客户端的服务器版本号name服务器名称默认chatlabdbManager满足McpDatabaseManager契约listSessionIds/open的数据库管理器CLI 的DatabaseManager与桌面端 helper 均可满足locale决定工具描述使用中文还是英文默认英文。多数用户应优先使用npx -y chatlab-mcp命令行方式包级 API 主要面向需要在自有进程中嵌入 MCP 服务的场景。九、安全与设计要点小结stdout 专用stdio 传输下 stdout 只承载 MCP 协议消息日志全部走 stderr避免污染协议只读边界数据库层只打开既有会话库工具层仅允许只读 SELECTsession_id不存在时返回Session not found错误server.tstoken 优化精简工具注册表省约 40% schema token、输出压缩与噪声过滤、max_rows截断都是为降低外部 AI 代理的上下文开销而设计兼容层设计McpDatabaseManager抽象使同一 MCP 核心可被 CLI 与桌面端复用这也是包描述中 shared core for CLI and Desktop 的含义。十、进一步阅读MCP 服务核心实现packages/mcp-server/src/server.ts独立运行时初始化packages/mcp-server/src/standalone-runtime.ts工具注册表含 MCP 精简集说明packages/tools/src/registry.ts输出格式化与噪声过滤packages/mcp-server/src/format.ts工具定义目录packages/tools/src/definitions包配置与依赖packages/mcp-server/package.json赞分享数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能【免费下载链接】ChatLabLocal-first chat history analyzer with AI. | 本地优先的 AI 聊天记录分析工具项目地址https://gitcode.com/ChatLab/ChatLab点击查看免费下载相关推荐ChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录ChatLab 本地 CLI 查询指南用 clb 命令与外部 AI Agent 分析聊天记录 ChatLab 提供一套面向 AI Agent 与命令行用户设计数据分析人工智能AI 应用AI Agent桌面应用CLIMCP 服务AI 技能本地部署CUDA 动态并行CDP实战入门解析 cdpSimplePrint 示例的 GPU 递归内核启动CUDA 动态并行CDP实战入门解析 cdpSimplePrint 示例的 GPU 递归内核启动 CUDA Dynamic ParallelismCDPQuantDinger MCP 接入实战把 Agent Gateway 变成 Agent 可调用的 MCP 工具集QuantDinger MCP 接入实战把 Agent Gateway 变成 Agent 可调用的 MCP 工具集 QuantDinger MCP Serve后端金融科技人工智能AI 应用AI AgentMCP 服务上一篇abogen 怎么用 TTS 把 EPUB 变成带同步字幕的有声书下一篇CSA 农场会员订单乱局怎么破用 Awesome-Selfhosted 搭一套自己的自托管社区农场管理系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考