企业官网建设流程全解析

OpenContext是一款面向 AI 编程 Agent 的个人上下文/知识库管理工具，它的 MCP Server 能让 Cursor、Claude Code、Codex 等任意支持 MCP 的客户端，把"搜索知识、创建文档、生成稳定链接"等操作变成一键调用的工具。本教程带你从零完成 MCP 配置，告别每次向 AI 重复解释项目背景的日子。

一、为什么需要 MCP 配置？

如果你用过 AI 编程助手，大概率遇到过这些痛点：

核心原理很简单：OpenContext 通过 src/mcp/server.js 内置了一个stdio 传输的 MCP Server（基于@modelcontextprotocol/sdk实现），AI 客户端只要按 MCP 协议启动它，就能像调用函数一样调用你的知识库能力。MCP 服务端源码位于 src/mcp/ 目录，配置文件示例见 mcp.example.json。

二、配置前准备：安装 oc CLI

整个 MCP 配置都围绕oc命令行展开，先安装（要求 Node.js >= 18）：

npm install -g @aicontextlab/cli

然后在你的项目目录里执行初始化。它会交互式询问要接入哪些工具，并自动帮你写好用户级 MCP 配置：

cd your-project oc init

oc init除了写入 MCP 配置，还会生成用户级 Skills 和斜杠命令（如~/.cursor/skills/opencontext-*/SKILL.md），非交互式安装可用--tools cursor,claude,codex指定目标工具。

想理解它如何替你改配置，可以看 src/core/agents.js 中的ensureUserMcpConfigs逻辑：它会安全地把opencontext条目 upsert 进各客户端的mcp.json，已有相同配置时不会重复写入。

三、一键配置方法：各客户端的 mcp.json 写入位置

不同 AI 客户端的 MCP 配置文件路径不同，oc init会自动处理，这里列出来方便你核对或手动配置：

• Cursor：~/.cursor/mcp.json
• Claude Code：~/.claude/mcp.json（或$CLAUDE_CONFIG_DIR/mcp.json）
• Codex：~/.codex/mcp.json（或$CODEX_HOME/mcp.json）

配置文件内容非常简洁，如下（完整示例见仓库根目录的 mcp.example.json）：

{ "mcpServers": { "opencontext": { "command": "oc", "args": ["mcp"], "cwd": "$HOME" } } }

三个字段各管一摊：

保存后重启客户端，在工具列表里看到oc_search、oc_manifest等工具，就代表配置成功了 ✅

四、配置完成后：AI 客户端获得了哪 9 个工具？

配置完成后，OpenContext 会向客户端注册以下 9 个工具（定义见 src/mcp/server.js），覆盖知识库的"读、搜、写、引用"全流程：

📂 浏览与发现

• oc_list_folders— 列出知识库目录，scope=all可返回所有子目录
• oc_list_docs— 列出指定目录下的文档，支持recursive递归
• oc_manifest— 输出目录文档的 JSON 清单（含路径），供 Agent 按路径读取上下文

🔍 搜索与索引

• oc_search— 按关键词或自然语言搜索文档，支持hybrid（默认混合）、vector、keyword三种模式
• oc_index_status— 检查搜索索引是否已构建，Agent 可据此决定是否降级处理

✍️ 创建与更新

• oc_create_doc— 在指定目录创建文档（可附带描述）
• oc_folder_create— 创建目录，目录已存在时调用也安全
• oc_set_doc_desc— 更新文档描述，让后续搜索/筛选更准

🔗 稳定引用

• oc_resolve— 用stable_id（UUID）解析出文档当前路径，文档移动/改名后引用依然有效
• oc_get_link— 生成oc://doc/<stable_id>稳定链接，方便在文档间交叉引用

💡 实用技巧：oc_search在索引未构建时会返回结构化的INDEX_NOT_AVAILABLE错误并提示先运行oc index build，而不是直接崩溃，Agent 可以据此优雅降级到oc_manifest。注意索引构建可能产生外部 embedding 调用费用，建议手动触发。

五、验证配置是否生效

方法 1：命令行快速自检

oc mcp --test

--test参数会让 MCP Server 启动后自动退出（见 bin/oc.js 中的mcp命令定义），能正常结束就说明 Server 可被正常拉起。

方法 2：客户端内实测

在 Cursor / Claude Code 中直接对 AI 说："用 oc_list_docs 看看我的知识库顶层有什么"，观察工具调用是否成功返回。也可以试试让它"搜索一下 XX 相关的文档"，触发oc_search。

如果oc_search提示索引不可用，先执行：

oc index build

再让 AI 重试即可。

六、常见问题速查（FAQ）

Q1：AI 客户端里看不到 opencontext 工具？检查mcp.json路径是否正确（对照第三节）、保存后是否重启了客户端；用oc mcp --test排除 Server 本身的问题。

Q2：多个客户端指向同一份知识库会冲突吗？不会。所有客户端共享同一份用户级数据（默认~/.opencontext/，可用环境变量OPENCONTEXT_ROOT自定义，见 src/core/store/index.js 中的路径常量），这正符合"一份知识库，多个 Agent 复用"的设计。

Q3：只想给某个项目临时接入怎么办？把mcp.example.json里的配置写到项目级 MCP 配置中（各客户端均支持），不想要了删掉即可，不影响全局。

写在最后

配置完成后，你的 AI 编程助手就拥有了一支"记忆外挂"：开工前先oc_search加载历史背景，完工后用oc_create_doc沉淀新知识，跨项目、跨会话、跨 Agent 都能复用。整个过程只需安装 CLI、执行oc init、重启客户端三步，强烈建议每个重度使用 AI 编程工具的开发者都花 5 分钟完成这套 OpenContext MCP 配置。

核心资料入口：

• MCP 服务端源码：src/mcp/server.js
• 标准配置示例：mcp.example.json
• 自动写配置的初始化逻辑：src/core/agents.js
• 项目总览：README.md