Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(opencode): add hook-only installation mode (#3734)

Valorfdb4b571ca25
diff --git a/examples/opencode-plugin/INSTALL-ZH.md b/examples/opencode-plugin/INSTALL-ZH.md
index a02bc6a90..06da6bad8 100644
--- a/examples/opencode-plugin/INSTALL-ZH.md
+++ b/examples/opencode-plugin/INSTALL-ZH.md
@@ -92,6 +92,7 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
```json
{
"enabled": true,
+ "mcp": { "enabled": true },
"timeoutMs": 30000,
"repoContext": { "enabled": true, "cacheTtlMs": 60000 },
"autoRecall": {
@@ -130,6 +131,19 @@ user/admin API key 的 API_KEY mode 时应留空。
高级场景可以用 `OPENVIKING_PLUGIN_CONFIG` 指向其他配置文件路径。
+### 仅 Hooks 模式
+
+如果其他 MCP server 已经提供 OpenViking,可以关闭本插件附带的 MCP 注册,同时保留生命周期 hooks:
+
+```json
+{
+ "mcp": { "enabled": false }
+}
+```
+
+repository context、自动 recall、消息 capture 和生命周期 commit 会继续工作,也不会添加或覆盖
+OpenCode 的 `mcp.openviking` 配置。
+
## 验证
修改插件或 OpenViking 配置后,需要重启 OpenCode。
diff --git a/examples/opencode-plugin/INSTALL.md b/examples/opencode-plugin/INSTALL.md
index 87a70fa1d..afbac0077 100644
--- a/examples/opencode-plugin/INSTALL.md
+++ b/examples/opencode-plugin/INSTALL.md
@@ -92,6 +92,7 @@ Example configuration:
```json
{
"enabled": true,
+ "mcp": { "enabled": true },
"timeoutMs": 30000,
"repoContext": { "enabled": true, "cacheTtlMs": 60000 },
"autoRecall": {
@@ -126,6 +127,20 @@ API keys are resolved from environment variables or `~/.openviking/ovcli.conf` a
For advanced setups, use `OPENVIKING_PLUGIN_CONFIG` to point to another configuration file path.
+### Hook-only mode
+
+If another MCP server already exposes OpenViking, set the bundled MCP registration to `false` while
+keeping this plugin's lifecycle hooks active:
+
+```json
+{
+ "mcp": { "enabled": false }
+}
+```
+
+Repository context, automatic recall, message capture, and lifecycle commits remain enabled. This
+does not add or overwrite OpenCode's `mcp.openviking` entry.
+
## Verify
Restart OpenCode after changing plugin or OpenViking configuration.
diff --git a/examples/opencode-plugin/README.md b/examples/opencode-plugin/README.md
index 3df590bd7..9c99b331c 100644
--- a/examples/opencode-plugin/README.md
+++ b/examples/opencode-plugin/README.md
@@ -114,6 +114,7 @@ Create `~/.config/opencode/openviking-config.json`:
```json
{
"enabled": true,
+ "mcp": { "enabled": true },
"timeoutMs": 30000,
"repoContext": { "enabled": true, "cacheTtlMs": 60000 },
"autoRecall": {
@@ -163,6 +164,20 @@ and `OPENVIKING_PEER_ID` take precedence over values in this file.
For advanced setups, `OPENVIKING_PLUGIN_CONFIG` can point to another config file path.
+### Hook-only mode
+
+When OpenViking is already exposed through another MCP server, retain the lifecycle hooks while
+skipping this plugin's bundled MCP registration:
+
+```json
+{
+ "mcp": { "enabled": false }
+}
+```
+
+This leaves repository context, automatic recall, message capture, and lifecycle commits enabled.
+It does not add or overwrite OpenCode's `mcp.openviking` entry.
+
OpenCode's local `read`, `glob`, and `grep` tools cannot read `viking://` URIs.
When the agent accidentally tries that, the plugin blocks the filesystem tool
call and points it to the OpenViking MCP tools.
diff --git a/examples/opencode-plugin/index.mjs b/examples/opencode-plugin/index.mjs
index 9c1e59eee..bc5934588 100644
--- a/examples/opencode-plugin/index.mjs
+++ b/examples/opencode-plugin/index.mjs
@@ -44,8 +44,15 @@ export async function OpenVikingPlugin({ client, directory }) {
return {
config: async (opencodeConfig) => {
- const injected = injectOpenVikingMcpConfig(opencodeConfig, pluginRoot)
- log(injected ? "INFO" : "WARN", "mcp", injected ? "Registered OpenViking MCP server" : "OpenViking MCP server was not registered")
+ const injected = injectOpenVikingMcpConfig(opencodeConfig, pluginRoot, config.mcp.enabled)
+ const hookOnly = !config.mcp.enabled
+ log(
+ injected || hookOnly ? "INFO" : "WARN",
+ "mcp",
+ injected ? "Registered OpenViking MCP server" :
+ hookOnly ? "Skipped bundled MCP registration in hook-only mode" :
+ "OpenViking MCP server was not registered",
+ )
},
event: async ({ event }) => {
diff --git a/examples/opencode-plugin/lib/config.mjs b/examples/opencode-plugin/lib/config.mjs
index 77f834e11..20e4552b8 100644
--- a/examples/opencode-plugin/lib/config.mjs
+++ b/examples/opencode-plugin/lib/config.mjs
@@ -21,6 +21,9 @@ const DEFAULT_CONFIG = {
// it has to be switchable from the client that pays the latency.
recallQueryExpansion: "auto",
enabled: true,
+ mcp: {
+ enabled: true,
+ },
timeoutMs: 30000,
runtime: {
dataDir: "",
@@ -120,6 +123,12 @@ function applyLegacyConnection(config, fileConfig) {
function applyBehaviorConfig(config, fileConfig = {}) {
if (fileConfig.enabled !== undefined) config.enabled = fileConfig.enabled !== false
+ const mcp = fileConfig.mcp && typeof fileConfig.mcp === "object" ? fileConfig.mcp : {}
+ config.mcp = {
+ ...DEFAULT_CONFIG.mcp,
+ ...mcp,
+ enabled: mcp.enabled !== false,
+ }
if (fileConfig.timeoutMs !== undefined) config.timeoutMs = fileConfig.timeoutMs
config.runtime = {
...DEFAULT_CONFIG.runtime,
diff --git a/examples/opencode-plugin/lib/mcp-config.mjs b/examples/opencode-plugin/lib/mcp-config.mjs
index a5188b161..4a6d67512 100644
--- a/examples/opencode-plugin/lib/mcp-config.mjs
+++ b/examples/opencode-plugin/lib/mcp-config.mjs
@@ -11,8 +11,9 @@ export function createOpenVikingMcpConfig(pluginRoot) {
}
}
-export function injectOpenVikingMcpConfig(config, pluginRoot) {
+export function injectOpenVikingMcpConfig(config, pluginRoot, enabled = true) {
if (!config || typeof config !== "object") return false
+ if (!enabled) return false
config.mcp = config.mcp && typeof config.mcp === "object" ? config.mcp : {}
const current = config.mcp[OPENCODE_MCP_NAME]
if (current?.enabled === false) return false
diff --git a/examples/opencode-plugin/tests/config.test.mjs b/examples/opencode-plugin/tests/config.test.mjs
index 2529d53ee..445a7af6c 100644
--- a/examples/opencode-plugin/tests/config.test.mjs
+++ b/examples/opencode-plugin/tests/config.test.mjs
@@ -1,9 +1,11 @@
import test from "node:test"
import assert from "node:assert/strict"
+import { createServer } from "node:http"
import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises"
import { tmpdir } from "node:os"
import { join } from "node:path"
import { loadConfig } from "../lib/config.mjs"
+import { OpenVikingPlugin } from "../index.mjs"
async function withTempDir(prefix, fn) {
const dir = await mkdtemp(join(tmpdir(), prefix))
@@ -14,6 +16,25 @@ async function withTempDir(prefix, fn) {
}
}
+async function withHealthServer(fn) {
+ const server = createServer((request, response) => {
+ response.setHeader("Content-Type", "application/json")
+ if (request.url === "/health") {
+ response.end(JSON.stringify({ status: "ok" }))
+ return
+ }
+ response.statusCode = 404
+ response.end(JSON.stringify({ status: "error" }))
+ })
+ await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve))
+ try {
+ const { port } = server.address()
+ return await fn(`http://127.0.0.1:${port}`)
+ } finally {
+ await new Promise((resolve) => server.close(resolve))
+ }
+}
+
function restoreOpenVikingEnv(snapshot) {
for (const key of Object.keys(process.env)) {
if (key.startsWith("OPENVIKING_")) delete process.env[key]
@@ -142,6 +163,65 @@ test("loadConfig can disable workspace peer", async () => {
})
})
+test("loadConfig supports hook-only mode without registering the bundled MCP server", async () => {
+ const snapshot = { ...process.env }
+ await withTempDir("ov-oc-hook-only-", async (dir) => {
+ try {
+ for (const key of Object.keys(process.env)) {
+ if (key.startsWith("OPENVIKING_")) delete process.env[key]
+ }
+ const project = join(dir, "project")
+ await mkdir(join(project, ".opencode"), { recursive: true })
+ await writeFile(join(project, ".opencode", "openviking-config.json"), JSON.stringify({
+ mcp: { enabled: false },
+ }))
+
+ const cfg = loadConfig(dir, project)
+ assert.equal(cfg.enabled, true)
+ assert.equal(cfg.mcp.enabled, false)
+ } finally {
+ restoreOpenVikingEnv(snapshot)
+ }
+ })
+})
+
+test("OpenVikingPlugin keeps lifecycle hooks without mutating MCP config in hook-only mode", async () => {
+ const snapshot = { ...process.env }
+ await withTempDir("ov-oc-hook-only-runtime-", async (dir) => {
+ await withHealthServer(async (endpoint) => {
+ try {
+ for (const key of Object.keys(process.env)) {
+ if (key.startsWith("OPENVIKING_")) delete process.env[key]
+ }
+ const configPath = join(dir, "openviking-config.json")
+ await writeFile(configPath, JSON.stringify({
+ mcp: { enabled: false },
+ runtime: { dataDir: join(dir, "runtime") },
+ repoContext: { enabled: false },
+ autoRecall: { enabled: false },
+ autoCapture: false,
+ }))
+ process.env.OPENVIKING_PLUGIN_CONFIG = configPath
+ process.env.OPENVIKING_URL = endpoint
+
+ const plugin = await OpenVikingPlugin({ client: {}, directory: dir })
+ assert.equal(typeof plugin.event, "function")
+ assert.equal(typeof plugin["chat.message"], "function")
+ assert.equal(typeof plugin.dispose, "function")
+
+ const opencodeConfig = { mcp: { external: { type: "remote", url: "https://example.com/mcp" } } }
+ await plugin.config(opencodeConfig)
+ assert.deepEqual(opencodeConfig, {
+ mcp: { external: { type: "remote", url: "https://example.com/mcp" } },
+ })
+ await plugin.dispose()
+ } finally {
+ restoreOpenVikingEnv(snapshot)
+ }
+ })
+ })
+})
+
test("loadConfig preserves an explicit zero commit keep recent count", async () => {
const snapshot = { ...process.env }
await withTempDir("ov-oc-keep-recent-zero-", async (dir) => {
diff --git a/examples/opencode-plugin/tests/mcp-config.test.mjs b/examples/opencode-plugin/tests/mcp-config.test.mjs
index a227e940e..c4e65c0f8 100644
--- a/examples/opencode-plugin/tests/mcp-config.test.mjs
+++ b/examples/opencode-plugin/tests/mcp-config.test.mjs
@@ -26,10 +26,20 @@ test("injectOpenVikingMcpConfig respects explicit disabled MCP server", () => {
assert.deepEqual(config.mcp.openviking, { enabled: false })
})
+test("injectOpenVikingMcpConfig leaves OpenCode MCP config untouched in hook-only mode", () => {
+ const config = { mcp: { external: { type: "remote", url: "https://example.com/mcp" } } }
+
+ assert.equal(injectOpenVikingMcpConfig(config, "/tmp/openviking-plugin", false), false)
+ assert.deepEqual(config, {
+ mcp: { external: { type: "remote", url: "https://example.com/mcp" } },
+ })
+})
+
test("OpenCode plugin keeps tools on MCP rather than native tool hook", async () => {
const source = await readFile(join(testDir, "../index.mjs"), "utf8")
assert.match(source, /injectOpenVikingMcpConfig/)
+ assert.match(source, /injectOpenVikingMcpConfig\(opencodeConfig, pluginRoot, config\.mcp\.enabled\)/)
assert.doesNotMatch(source, /createMemoryTools/)
assert.doesNotMatch(source, /createCodeTools/)
assert.doesNotMatch(source, /\btool:\s*\{/)