Local-first π§ memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly π΄ dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
feat: add native OpenClaw plugin support with JS entry point (v0.5.1)
Sol Aitken934d9be13976
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex bcf07c89..951573f5 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.5.0",+ "version": "0.5.1","description": "Plugin-first second brain package for AI agents and humans.","author": "Open Second Brain contributors","license": "MIT",diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.jsonindex 44ec7db8..5bb4a254 100644--- a/.codex-plugin/plugin.json+++ b/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "open-second-brain",- "version": "0.5.0",+ "version": "0.5.1","description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.","skills": "./skills","keywords": ["second-brain", "obsidian", "agents", "skills", "event-log", "mcp"]diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex b9ba6d81..1e9e8912 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -82,6 +82,16 @@ jobs:bash -n scripts/vault-logscripts/o2b doctor --vault . --repo .+ - name: Validate OpenClaw packaging+ shell: bash+ run: |+ set -euo pipefail+ python -m json.tool package.json >/dev/null+ node -e "const pkg = require('./package.json'); if (!pkg.openclaw?.extensions?.length) throw new Error('missing openclaw.extensions')"+ for entry in $(node -e "console.log(require('./package.json').openclaw.extensions.join(' '))"); do+ [ -f "$entry" ] || { echo "Missing entry: $entry"; exit 1; }+ done+- name: Build source and wheel distributionsrun: |python -m pip install --upgrade pip builddiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4389e50a..2b515ec0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+## [0.5.1] - 2026-05-07++### Added++- Root `package.json` with `openclaw.extensions` so OpenClaw can install the+ plugin via `git:` and `npm-pack:` resolvers without errors.+- `openclaw/index.js` runtime entry that registers five native OpenClaw tools+ (`second_brain_status`, `second_brain_query`, `second_brain_capture`,+ `event_log_append`, `vault_health`) through `definePluginEntry` and+ `api.registerTool`. Tool execution spawns `python3 -m open_second_brain.cli`+ with `PYTHONPATH` pointing at the plugin's `src/` directory.+- `openclaw/o2b-runner.js` subprocess helper for calling Python from the JS+ entry.+- `tool-call` CLI subcommand that bridges MCP tool handlers to the command+ line, enabling the JS entry to invoke tools like `second_brain_query` and+ `second_brain_capture` without running a full MCP server.+- `check_openclaw_installability` doctor checks that validate `package.json`+ exists, has `openclaw.extensions`, and each extension file is present.+- `uiHints` and `activation` fields in `openclaw.plugin.json`.+- OpenClaw packaging validation step in the CI release workflow.++### Changed++- Bumped package, plugin, and manifest versions to 0.5.1.+- `install.md` OpenClaw branch now uses `openclaw config set` for vault+ configuration instead of manual MCP registration β tools are registered+ natively by the plugin entry.+- `mcpEnabled` default changed to `false` in `openclaw.plugin.json` because+ native tool registration makes the MCP server unnecessary for most OpenClaw+ setups.+- `docs/architecture.md` OpenClaw adapter section now describes the JS entry ++ Python bridge pattern instead of the Bundle-only approach.+## [0.5.0] - 2026-05-07### Added@@ -134,7 +167,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- Sandbox vault and plugin manifest fixtures for tests.- GitHub release workflow for tag-based and manually dispatched releases.-[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.5.0...HEAD+[unreleased]: https://github.com/itechmeat/open-second-brain/compare/v0.5.1...HEAD+[0.5.1]: https://github.com/itechmeat/open-second-brain/compare/v0.5.0...v0.5.1[0.5.0]: https://github.com/itechmeat/open-second-brain/compare/v0.4.2...v0.5.0[0.4.2]: https://github.com/itechmeat/open-second-brain/compare/v0.4.1...v0.4.2[0.4.1]: https://github.com/itechmeat/open-second-brain/compare/v0.4.0...v0.4.1diff --git a/README.md b/README.mdindex 0a545580..afe03ac3 100644--- a/README.md+++ b/README.md@@ -60,12 +60,12 @@ o2b doctor --vault /path/to/vault --repo .### Install in OpenClaw-OpenClaw supports this project through the **Bundle format**: OpenClaw auto-detects the `.claude-plugin/` and `.codex-plugin/` adapter directories and maps them to OpenClaw features. The `openclaw.plugin.json` manifest at the project root provides static discovery metadata.+OpenClaw supports this project through the **Native plugin format**: a root `package.json` with `openclaw.extensions` pointing to a JS entry that registers tools natively inside OpenClaw's Node.js process. The JS entry spawns the Python CLI as a subprocess, so no MCP server is needed for basic operation.Install from Git:```bash-openclaw plugins install git:github.com/itechmeat/[email protected]+openclaw plugins install git:github.com/itechmeat/[email protected]```Or from a local checkout:@@ -74,13 +74,14 @@ Or from a local checkout:openclaw plugins install ./open-second-brain```-After installing, register the MCP tool server so OpenClaw can route tool calls:+After installing, configure the vault path:```bash-o2b mcp --vault /path/to/vault+openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'+openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'```-The MCP server exposes five tools: `second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`. OpenClaw discovers these through the MCP protocol at runtime. The `openclaw.plugin.json` `contracts.tools` field declares them for cold discovery when the MCP server is not yet running.+Tools are registered natively by the JS plugin entry β no MCP registration is needed. The five tools (`second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`) are available immediately after install and gateway restart. The optional MCP server (`o2b mcp`) can still be enabled for runtimes that prefer the MCP protocol.## First rundiff --git a/after-install.md b/after-install.mdindex c48277f3..d03ff4ea 100644--- a/after-install.md+++ b/after-install.md@@ -82,23 +82,32 @@ yourself with normal filesystem tools if that is what you want.## OpenClawIf you are using OpenClaw instead of (or in addition to) Hermes, the plugin-is already discoverable through the Bundle format. OpenClaw auto-detects the-`.claude-plugin/` and `.codex-plugin/` directories.+is now installed as a **native OpenClaw plugin**. Tools are registered+automatically by the JS entry (`openclaw/index.js`) β no MCP server setup is+required.-The `openclaw.plugin.json` manifest at the project root declares the plugin ID-(`open-second-brain`), a configuration schema, and the five tool names the MCP-server exposes. To register the MCP server with OpenClaw, follow the same-pattern as Hermes β point OpenClaw's MCP configuration at the `o2b mcp`-command:+The `package.json` at the project root declares `openclaw.extensions` pointing+to the JS entry. The `openclaw.plugin.json` manifest provides static discovery+metadata (plugin ID, configuration schema, declared tool names).++To configure the vault path:```bash-o2b mcp --vault /path/to/vault+openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'+openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'```-Run the doctor to verify the OpenClaw manifest is valid:+Run the doctor to verify the OpenClaw manifest and packaging are valid:```basho2b doctor --vault /path/to/vault --repo .```-The doctor output should include `[OK] openclaw_manifest`.+The doctor output should include `[OK] openclaw_manifest`, `[OK] openclaw_package_json`, and `[OK] openclaw_package_json_extensions`.++If you want to also expose an MCP stdio server (e.g. for another runtime),+the `o2b mcp` command is still available:++```bash+o2b mcp --vault /path/to/vault+```diff --git a/docs/architecture.md b/docs/architecture.mdindex 3bb4e46f..5c00ec9f 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -76,31 +76,37 @@ v0 should keep Codex support simple: plugin manifest plus shared skills and scri### OpenClaw adapter-OpenClaw recognizes two plugin formats: **Native** (TypeScript/JS runtime module with `openclaw.plugin.json`) and **Bundle** (adapter directories like `.codex-plugin/`, `.claude-plugin/` mapped to OpenClaw features).+OpenClaw recognizes two plugin formats: **Native** (JS runtime module with `package.json` + `openclaw.plugin.json`) and **Bundle** (adapter directories like `.codex-plugin/`, `.claude-plugin/` mapped to OpenClaw features).-Since Open Second Brain is a Python project, it uses the **Bundle format** combined with a static `openclaw.plugin.json` manifest:+Open Second Brain uses the **Native format** with a JS entry that bridges to the Python CLI:```text-openclaw.plugin.json # static discovery metadata (id, configSchema, contracts.tools)-.claude-plugin/ # auto-detected by OpenClaw Bundle format-.codex-plugin/ # auto-detected by OpenClaw Bundle format-scripts/o2b # CLI entry point-src/open_second_brain/mcp.py # MCP server (runtime tool bridge)+package.json # openclaw.extensions β ./openclaw/index.js+openclaw/+ index.js # JS entry: definePluginEntry + api.registerTool+ o2b-runner.js # Subprocess helper: spawns python3 -m open_second_brain.cli+openclaw.plugin.json # Static discovery metadata (id, configSchema, contracts.tools)+src/open_second_brain/+ cli.py # Python CLI (includes tool-call bridge subcommand)+ mcp.py # MCP server (optional, for runtimes that prefer MCP)+.claude-plugin/ # Auto-detected by OpenClaw Bundle format+.codex-plugin/ # Auto-detected by OpenClaw Bundle format```-The OpenClaw integration does **not** add a TypeScript entry point or `package.json`. Instead:+The integration flow:-1. **Cold discovery**: `openclaw.plugin.json` declares the plugin ID, version, configuration schema, and the list of tool names the MCP server provides.-2. **Feature mapping**: OpenClaw auto-detects `.claude-plugin/` and `.codex-plugin/` directories and maps their commands and skills to OpenClaw features.-3. **Runtime bridge**: The MCP server (`o2b mcp`) serves as the tool runtime. OpenClaw discovers tool schemas and executes tool calls through the MCP protocol (stdio JSON-RPC 2.0).+1. **Discovery**: OpenClaw reads `package.json`, finds `openclaw.extensions`, and loads `openclaw/index.js`.+2. **Tool registration**: The JS entry calls `api.registerTool()` for each of the five tools (`second_brain_status`, `second_brain_query`, `second_brain_capture`, `event_log_append`, `vault_health`).+3. **Runtime bridge**: Each tool's `execute()` spawns `python3 -m open_second_brain.cli` with `PYTHONPATH` set to the plugin's `src/` directory. For tools with direct CLI equivalents (`status`, `append-event`, `doctor`), it calls the relevant subcommand. For tools without (`second_brain_query`, `second_brain_capture`), it uses the `tool-call` bridge subcommand which invokes the MCP tool handlers directly.+4. **Config**: `api.getConfig()` provides the vault path and instance name from OpenClaw's plugin config.Installation:```bash-openclaw plugins install git:github.com/itechmeat/[email protected]+openclaw plugins install git:github.com/itechmeat/[email protected]```-The OpenClaw adapter must not introduce Node.js/TypeScript dependencies, must not add `package.json`, and must remain compatible with the Hermes, Claude Code, and Codex adapters.+The OpenClaw adapter must remain compatible with the Hermes, Claude Code, and Codex adapters. The `o2b mcp` MCP server is still available for runtimes that prefer the MCP protocol.## Configuration modeldiff --git a/install.md b/install.mdindex 3eb812c6..c8ffeaf7 100644--- a/install.md+++ b/install.md@@ -1,6 +1,6 @@# open-second-brain β Agent Installation Guide-> **Version 0.5.0**+> **Version 0.5.1**> Repository: https://github.com/itechmeat/open-second-brainThis guide is written for an **AI agent**, not a human. It contains the exact commands and decision logic needed to install and configure the **open-second-brain** plugin autonomously. Follow exactly one of the two branches below based on the target runtime (Hermes or OpenClaw). Complete every step in the chosen branch.@@ -88,7 +88,7 @@ The vault and its Markdown files are never deleted by the uninstall process.From Git (pin to a version tag):```bash-openclaw plugins install git:github.com/itechmeat/[email protected]+openclaw plugins install git:github.com/itechmeat/[email protected]```Or from a local checkout:@@ -111,16 +111,15 @@ Replace `/path/to/vault` with the actual vault path.o2b init --vault /path/to/vault --name "My Second Brain"```-### 3. Register the MCP server+### 3. Configure the vault path-The MCP server is started via:+Tools are registered natively by the JS plugin entry β no MCP registration is needed. Set the vault path in the OpenClaw plugin config:```bash-o2b mcp --vault /path/to/vault+openclaw config set plugins.entries.open-second-brain.config.vault '"/path/to/vault"'+openclaw config set plugins.entries.open-second-brain.config.instanceName '"My Second Brain"'```-Point the OpenClaw MCP configuration at this command. The exact config method depends on the OpenClaw MCP setup in use β register `o2b mcp` as an stdio MCP server with the `--vault` argument.-### 4. Verify the installation```bashdiff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 7cc05df1..7f1b5fa3 100644--- a/openclaw.plugin.json+++ b/openclaw.plugin.json@@ -1,8 +1,10 @@{"id": "open-second-brain","name": "Open Second Brain",- "description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Provides vault management, event logging, wiki indexing, and an MCP tool server.",- "version": "0.5.0",+ "description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",+ "version": "0.5.1",+ "activation": { "onStartup": true },+ "skills": ["./skills"],"contracts": {"tools": ["second_brain_status",@@ -26,9 +28,23 @@},"mcpEnabled": {"type": "boolean",- "default": true,- "description": "Whether to enable the MCP tool server."+ "default": false,+ "description": "Whether to also expose an MCP stdio server (optional)."}}+ },+ "uiHints": {+ "vault": {+ "label": "Vault Path",+ "help": "Absolute path to the Obsidian-compatible vault directory."+ },+ "instanceName": {+ "label": "Instance Name",+ "help": "Human-readable name for this second brain instance."+ },+ "mcpEnabled": {+ "label": "Enable MCP Server",+ "help": "Expose Open Second Brain as an MCP stdio server (optional)."+ }}}diff --git a/openclaw/index.js b/openclaw/index.jsnew file mode 100644index 00000000..0588fc18--- /dev/null+++ b/openclaw/index.js@@ -0,0 +1,195 @@+/**+ * OpenClaw native plugin entry for Open Second Brain.+ *+ * Imports `definePluginEntry` from the OpenClaw host runtime and registers+ * five tools that delegate to the Python CLI via `runPython()`. The JS+ * entry runs inside OpenClaw's Node.js process; it never imports Python+ * directly β it spawns `python3 -m open_second_brain.cli` with PYTHONPATH+ * pointed at the plugin's `src/` directory.+ *+ * Tool parameter schemas are taken from `src/open_second_brain/mcp.py`.+ */++import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";+import { runPython } from "./o2b-runner.js";++/**+ * Escape a single shell argument so it can be safely joined into a+ * command string. Wraps the value in single-quotes and escapes any+ * embedded single-quotes.+ */+function shArg(value) {+ return "'" + String(value).replace(/'/g, "'\\''") + "'";+}++export default definePluginEntry({+ async register(api) {+ // ββ second_brain_status ββββββββββββββββββββββββββββββββββββββββββββ+ api.registerTool({+ name: "second_brain_status",+ description: "Report Open Second Brain configuration and vault status.",+ parameters: {+ type: "object",+ properties: {},+ additionalProperties: false,+ },+ async execute(_id, _params) {+ const config = api.getConfig();+ const vault = config?.vault || process.env.VAULT_DIR || ".";+ const result = await runPython(["status", "--vault", vault]);+ return { content: [{ type: "text", text: result }] };+ },+ });++ // ββ second_brain_query βββββββββββββββββββββββββββββββββββββββββββββ+ api.registerTool({+ name: "second_brain_query",+ description:+ "List vault pages with optional title substring filter.",+ parameters: {+ type: "object",+ properties: {+ pattern: {+ type: "string",+ description:+ "Optional case-insensitive substring matched against page titles.",+ },+ limit: {+ type: "integer",+ minimum: 1,+ maximum: 500,+ description:+ "Maximum number of matched pages to return (default 50).",+ },+ },+ additionalProperties: false,+ },+ async execute(_id, params) {+ const config = api.getConfig();+ const vault = params.vault || config?.vault || process.env.VAULT_DIR || ".";+ const args = ["tool-call", "--vault", vault, "second_brain_query"];+ if (params.pattern) args.push("--tool-arg", `pattern=${params.pattern}`);+ if (params.limit != null) args.push("--tool-arg", `limit=${params.limit}`);+ const result = await runPython(args);+ return { content: [{ type: "text", text: result }] };+ },+ });++ // ββ second_brain_capture βββββββββββββββββββββββββββββββββββββββββββ+ api.registerTool({+ name: "second_brain_capture",+ description:+ "Write a new Markdown note to AI Wiki/notes/ with frontmatter.",+ parameters: {+ type: "object",+ properties: {+ title: {+ type: "string",+ description: "Human-readable note title.",+ },+ content: {+ type: "string",+ description: "Markdown body of the note.",+ },+ tags: {+ type: "array",+ items: { type: "string" },+ description: "Optional list of tag strings.",+ },+ overwrite: {+ type: "boolean",+ description:+ "Allow overwriting an existing note with the same slug.",+ },+ },+ required: ["title", "content"],+ additionalProperties: false,+ },+ async execute(_id, params) {+ const config = api.getConfig();+ const vault = config?.vault || process.env.VAULT_DIR || ".";+ const args = [+ "tool-call", "--vault", vault, "second_brain_capture",+ "--tool-arg", `title=${params.title}`,+ "--tool-arg", `content=${params.content}`,+ ];+ if (params.tags && params.tags.length > 0) {+ args.push("--tool-arg", `tags=${JSON.stringify(params.tags)}`);+ }+ if (params.overwrite) {+ args.push("--tool-arg", "overwrite=true");+ }+ const result = await runPython(args);+ return { content: [{ type: "text", text: result }] };+ },+ });++ // ββ event_log_append βββββββββββββββββββββββββββββββββββββββββββββββ+ api.registerTool({+ name: "event_log_append",+ description:+ "Append a single-line event to the daily Markdown event log.",+ parameters: {+ type: "object",+ properties: {+ message: {+ type: "string",+ description: "Single-line event message.",+ },+ agent: {+ type: "string",+ description: "Agent name (default 'agent').",+ },+ date: {+ type: "string",+ description: "Optional event date in YYYY.MM.DD format.",+ },+ time: {+ type: "string",+ description: "Optional event time in 24-hour HH:MM format.",+ },+ },+ required: ["message"],+ additionalProperties: false,+ },+ async execute(_id, params) {+ const config = api.getConfig();+ const vault = config?.vault || process.env.VAULT_DIR || ".";+ const args = ["append-event", "--vault", vault];+ if (params.agent) args.push("--as", params.agent);+ if (params.date) args.push("--date", params.date);+ if (params.time) args.push("--time", params.time);+ args.push("--");+ args.push(params.message);+ const result = await runPython(args);+ return { content: [{ type: "text", text: result }] };+ },+ });++ // ββ vault_health βββββββββββββββββββββββββββββββββββββββββββββββββββ+ api.registerTool({+ name: "vault_health",+ description:+ "Run vault, config, and plugin manifest health checks.",+ parameters: {+ type: "object",+ properties: {+ repo: {+ type: "string",+ description:+ "Optional repository root to validate plugin manifests.",+ },+ },+ additionalProperties: false,+ },+ async execute(_id, params) {+ const config = api.getConfig();+ const vault = config?.vault || process.env.VAULT_DIR || ".";+ const args = ["doctor", "--vault", vault];+ if (params.repo) args.push("--repo", params.repo);+ const result = await runPython(args);+ return { content: [{ type: "text", text: result }] };+ },+ });+ },+});diff --git a/openclaw/o2b-runner.js b/openclaw/o2b-runner.jsnew file mode 100644index 00000000..2657928b--- /dev/null+++ b/openclaw/o2b-runner.js@@ -0,0 +1,41 @@+/**+ * Subprocess helper for calling the Open Second Brain Python CLI from+ * the OpenClaw JS plugin entry.+ *+ * Spawns `python3 -m open_second_brain.cli` with PYTHONPATH pointed at the+ * plugin's `src/` directory so the package is importable even when `o2b`+ * is not on PATH (e.g. after a `git:` or `npm-pack:` install).+ */++import { execFile } from "node:child_process";+import { fileURLToPath } from "node:url";+import path from "node:path";++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const PLUGIN_ROOT = path.resolve(__dirname, "..");+const PYTHON_SRC = path.join(PLUGIN_ROOT, "src");++/**+ * Run a Python CLI command and return stdout.+ *+ * @param {string[]} args - Arguments forwarded to `python3 -m open_second_brain.cli`.+ * @param {number} [timeout=30000] - Maximum execution time in milliseconds.+ * @returns {Promise<string>} Trimmed stdout from the subprocess.+ */+export function runPython(args, timeout = 30000) {+ return new Promise((resolve, reject) => {+ const env = { ...process.env, PYTHONPATH: PYTHON_SRC };+ execFile(+ "python3",+ ["-m", "open_second_brain.cli", ...args],+ { env, timeout, maxBuffer: 1024 * 1024 },+ (err, stdout, stderr) => {+ if (err) {+ reject(new Error(stderr || err.message));+ return;+ }+ resolve(stdout.trim());+ },+ );+ });+}diff --git a/package.json b/package.jsonnew file mode 100644index 00000000..d477f6c1--- /dev/null+++ b/package.json@@ -0,0 +1,28 @@+{+ "name": "open-second-brain",+ "version": "0.5.1",+ "type": "module",+ "private": false,+ "description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",+ "license": "MIT",+ "homepage": "https://github.com/itechmeat/open-second-brain",+ "repository": {+ "type": "git",+ "url": "https://github.com/itechmeat/open-second-brain.git"+ },+ "keywords": ["second-brain", "obsidian", "agents", "openclaw-plugin", "mcp"],+ "files": [+ "openclaw/",+ "src/",+ "skills/",+ "scripts/",+ "plugins/",+ "openclaw.plugin.json",+ "README.md",+ "LICENSE",+ "pyproject.toml"+ ],+ "openclaw": {+ "extensions": ["./openclaw/index.js"]+ }+}diff --git a/plugin.yaml b/plugin.yamlindex 251dc937..c90b4cbd 100644--- a/plugin.yaml+++ b/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.5.0"+version: "0.5.1"description: "Hermes plugin entrypoint for OpenSecondBrain vault health checks and the optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yamlindex cb601865..97b9ed63 100644--- a/plugins/hermes/plugin.yaml+++ b/plugins/hermes/plugin.yaml@@ -1,5 +1,5 @@name: open-second-brain-version: "0.5.0"+version: "0.5.1"description: "Hermes adapter for OpenSecondBrain vault health checks and optional MCP tool server."author: "OpenSecondBrain contributors"kind: standalonediff --git a/pyproject.toml b/pyproject.tomlindex 6c32a4f3..820c89d9 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"[project]name = "open-second-brain"-version = "0.5.0"+version = "0.5.1"description = "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw."readme = "README.md"requires-python = ">=3.11"diff --git a/src/open_second_brain/__init__.py b/src/open_second_brain/__init__.pyindex f8433b4e..75bac37d 100644--- a/src/open_second_brain/__init__.py+++ b/src/open_second_brain/__init__.py@@ -1,3 +1,3 @@"""Open Second Brain core package."""-__version__ = "0.5.0"+__version__ = "0.5.1"diff --git a/src/open_second_brain/cli.py b/src/open_second_brain/cli.pyindex ed6f8b47..dac10b3e 100644--- a/src/open_second_brain/cli.py+++ b/src/open_second_brain/cli.py@@ -6,11 +6,13 @@ import osimport sysfrom pathlib import Path+import json as _json+from open_second_brain.config import default_config_path, discover_config, redact_mappingfrom open_second_brain.doctor import doctorfrom open_second_brain.event_log import append_eventfrom open_second_brain.init import bootstrap_vault-from open_second_brain.mcp import run_cli_command as run_mcp_server+from open_second_brain.mcp import MCPServer, run_cli_command as run_mcp_serverfrom open_second_brain.uninstall import plan_uninstall, render_planfrom open_second_brain.vault import list_vault_pages, write_frontmatter@@ -21,6 +23,8 @@ def build_parser() -> argparse.ArgumentParser:status = subcommands.add_parser("status", help="Show Open Second Brain configuration status")status.add_argument("--config", type=Path, default=None, help="Config file path")+ status.add_argument("--vault", type=Path, default=None, help="Vault directory path")+ status.add_argument("--json", action="store_true", help="Output as JSON")init_cmd = subcommands.add_parser("init", help="Initialize a vault profile with required files")init_cmd.add_argument("--vault", type=Path, required=True, help="Vault directory path")@@ -80,17 +84,43 @@ def build_parser() -> argparse.ArgumentParser:),)+ tool_call_cmd = subcommands.add_parser(+ "tool-call",+ help="Invoke an MCP tool handler from the CLI and print JSON to stdout.",+ )+ tool_call_cmd.add_argument("--vault", type=Path, default=None, help="Vault directory path")+ tool_call_cmd.add_argument("tool_name", help="MCP tool name to invoke")+ tool_call_cmd.add_argument(+ "--tool-arg",+ action="append",+ default=[],+ dest="tool_args",+ help="Tool argument as key=value (repeatable)",+ )+return parserdef command_status(args: argparse.Namespace) -> int:result = discover_config(args.config)- print(f"config_path: {result.path}")- print(f"config_exists: {str(result.exists).lower()}")- if result.data:- print("config_keys:")- for key in sorted(result.data):- print(f"- {key}")+ if getattr(args, "json", False):+ output = {+ "config_path": str(result.path),+ "config_exists": result.exists,+ }+ if result.data:+ output["config_keys"] = sorted(result.data.keys())+ vault = getattr(args, "vault", None)+ if vault:+ output["vault"] = str(vault)+ print(json.dumps(output, indent=2, sort_keys=True))+ else:+ print(f"config_path: {result.path}")+ print(f"config_exists: {str(result.exists).lower()}")+ if result.data:+ print("config_keys:")+ for key in sorted(result.data):+ print(f"- {key}")return 0@@ -211,6 +241,37 @@ def command_uninstall(args: argparse.Namespace) -> int:return 0+def command_tool_call(args: argparse.Namespace) -> int:+ """Bridge: invoke an MCP tool handler from the CLI and print JSON to stdout."""+ vault = args.vault or Path(os.environ.get("VAULT_DIR", "."))+ config = default_config_path()+ repo_root: Path | None = None++ server = MCPServer(vault=vault, config_path=config, repo_root=repo_root)++ tool_name = args.tool_name+ if tool_name not in server._tools:+ print(f"error: unknown tool: {tool_name}", file=sys.stderr)+ return 1++ # Parse --tool-arg key=value pairs into a dict+ arguments: dict[str, object] = {}+ for pair in args.tool_args:+ if "=" not in pair:+ print(f"error: --tool-arg must be key=value, got: {pair}", file=sys.stderr)+ return 1+ key, value = pair.split("=", 1)+ # Attempt JSON decode for non-string types (arrays, numbers, booleans)+ try:+ arguments[key] = _json.loads(value)+ except (_json.JSONDecodeError, ValueError):+ arguments[key] = value++ result = server._handle_tools_call({"name": tool_name, "arguments": arguments})+ print(_json.dumps(result, ensure_ascii=False, indent=2))+ return 0++def main(argv: list[str] | None = None) -> int:parser = build_parser()args = parser.parse_args(argv)@@ -230,6 +291,8 @@ def main(argv: list[str] | None = None) -> int:return command_mcp(args)if args.command == "uninstall":return command_uninstall(args)+ if args.command == "tool-call":+ return command_tool_call(args)raise AssertionError(f"unhandled command: {args.command}")diff --git a/src/open_second_brain/doctor.py b/src/open_second_brain/doctor.pyindex 3ced1dd0..f50ee1e5 100644--- a/src/open_second_brain/doctor.py+++ b/src/open_second_brain/doctor.py@@ -160,6 +160,64 @@ def check_openclaw_manifest(path: Path) -> CheckResult:return CheckResult("openclaw_manifest", True, f"valid OpenClaw manifest: {path}")+def check_openclaw_installability(repo_root: Path) -> list[CheckResult]:+ """Check that the OpenClaw native plugin packaging is valid.++ Validates:+ - Root ``package.json`` exists and is valid JSON.+ - ``package.json`` has an ``openclaw.extensions`` array.+ - Each extension entry file exists on disk.+ """+ results: list[CheckResult] = []+ pkg_path = repo_root / "package.json"++ result, data = _load_json_manifest(pkg_path, "openclaw_package_json")+ results.append(result)+ if data is None:+ return results++ # Check openclaw.extensions+ extensions = data.get("openclaw", {}).get("extensions")+ if not isinstance(extensions, list) or not extensions:+ results.append(CheckResult(+ "openclaw_package_json_extensions",+ False,+ "package.json missing or empty openclaw.extensions array",+ ))+ return results++ results.append(CheckResult(+ "openclaw_package_json_extensions",+ True,+ f"package.json declares {len(extensions)} extension(s)",+ ))++ # Check each extension entry file exists+ for entry in extensions:+ if not isinstance(entry, str):+ results.append(CheckResult(+ f"openclaw_entry_invalid_{type(entry).__name__}",+ False,+ f"extension entry must be a string, got: {type(entry).__name__}",+ ))+ continue+ entry_path = repo_root / entry+ if entry_path.is_file():+ results.append(CheckResult(+ f"openclaw_entry_{entry}",+ True,+ f"extension entry exists: {entry}",+ ))+ else:+ results.append(CheckResult(+ f"openclaw_entry_{entry}",+ False,+ f"missing extension entry: {entry}",+ ))++ return results++def doctor(*,vault: Path,@@ -181,5 +239,6 @@ def doctor(results.append(check_codex_manifest(repo_root / ".codex-plugin" / "plugin.json"))results.append(check_hermes_manifest(repo_root / "plugins" / "hermes" / "plugin.yaml"))results.append(check_openclaw_manifest(repo_root / "openclaw.plugin.json"))+ results.extend(check_openclaw_installability(repo_root))return resultsdiff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.pyindex 9e206d00..f1a7d6a8 100644--- a/src/open_second_brain/mcp.py+++ b/src/open_second_brain/mcp.py@@ -29,7 +29,7 @@ from open_second_brain.vault import list_vault_pages, parse_frontmatter, write_fPROTOCOL_VERSION = "2025-06-18"SERVER_NAME = "open-second-brain"-SERVER_VERSION = "0.5.0"+SERVER_VERSION = "0.5.1"JSONRPC_VERSION = "2.0"# JSON-RPC 2.0 error codes used by the MCP server.diff --git a/tests/fixtures.py b/tests/fixtures.pyindex bc5492a4..1a3ffb04 100644--- a/tests/fixtures.py+++ b/tests/fixtures.py@@ -72,6 +72,14 @@ def create_plugin_repo(root: Path, *, valid: bool = True) -> Path:""",encoding="utf-8",)+ # Native OpenClaw plugin packaging: package.json + extension entry+ entry_js = repo / "openclaw" / "index.js"+ entry_js.parent.mkdir(parents=True, exist_ok=True)+ entry_js.write_text("// plugin entry\n", encoding="utf-8")+ (repo / "package.json").write_text(+ """{"name": "test-plugin", "openclaw": {"extensions": ["./openclaw/index.js"]}}""",+ encoding="utf-8",+ )else:(repo / ".claude-plugin" / "plugin.json").write_text("{\"name\": \"test\"}", encoding="utf-8")(repo / ".codex-plugin" / "plugin.json").write_text("{\"name\": \"test\"}", encoding="utf-8")diff --git a/tests/test_doctor.py b/tests/test_doctor.pyindex 7a51fa6b..cf051bfa 100644--- a/tests/test_doctor.py+++ b/tests/test_doctor.py@@ -9,6 +9,7 @@ from open_second_brain.doctor import (check_codex_manifest,check_hermes_manifest,check_json_manifest,+ check_openclaw_installability,check_openclaw_manifest,check_vault_writeable,doctor,@@ -100,6 +101,50 @@ class DoctorTests(unittest.TestCase):self.assertIn("missing", hermes.message)self.assertIn("'id'", openclaw.message)+ def test_check_openclaw_installability_on_valid_fixture(self):+ with tempfile.TemporaryDirectory() as tmp:+ repo = create_plugin_repo(Path(tmp), valid=True)+ # Valid fixture now includes package.json and extension entry+ results = check_openclaw_installability(repo)+ self.assertGreater(len(results), 0)+ for r in results:+ self.assertTrue(r.ok, f"{r.name}: {r.message}")++ def test_check_openclaw_installability_with_package_json(self):+ import json+ with tempfile.TemporaryDirectory() as tmp:+ repo = create_plugin_repo(Path(tmp), valid=True)+ # Add a valid package.json with an extension entry+ entry_js = repo / "openclaw" / "index.js"+ entry_js.parent.mkdir(parents=True, exist_ok=True)+ entry_js.write_text("// entry", encoding="utf-8")+ (repo / "package.json").write_text(+ json.dumps({"openclaw": {"extensions": ["./openclaw/index.js"]}}),+ encoding="utf-8",+ )+ results = check_openclaw_installability(repo)+ self.assertGreater(len(results), 0)+ for r in results:+ self.assertTrue(r.ok, f"{r.name}: {r.message}")++ def test_doctor_includes_installability_checks_with_repo(self):+ with tempfile.TemporaryDirectory() as tmp:+ vault = create_sandbox_vault(Path(tmp))+ repo = create_plugin_repo(Path(tmp), valid=True)+ # Add package.json to fixture so installability passes+ import json+ entry_js = repo / "openclaw" / "index.js"+ entry_js.parent.mkdir(parents=True, exist_ok=True)+ entry_js.write_text("// entry", encoding="utf-8")+ (repo / "package.json").write_text(+ json.dumps({"openclaw": {"extensions": ["./openclaw/index.js"]}}),+ encoding="utf-8",+ )+ results = doctor(vault=vault, repo_root=repo)+ names = [r.name for r in results]+ self.assertIn("openclaw_package_json", names)+ self.assertIn("openclaw_package_json_extensions", names)+if __name__ == "__main__":unittest.main()diff --git a/tests/test_openclaw_plugin.py b/tests/test_openclaw_plugin.pyindex c5dcca4b..afa97cbc 100644--- a/tests/test_openclaw_plugin.py+++ b/tests/test_openclaw_plugin.py@@ -1,4 +1,4 @@-"""Tests for OpenClaw plugin compatibility (openclaw.plugin.json)."""+"""Tests for OpenClaw plugin compatibility (openclaw.plugin.json and package.json)."""import jsonimport tempfile@@ -7,7 +7,7 @@ from pathlib import PathROOT = Path(__file__).resolve().parents[1]-from open_second_brain.doctor import check_openclaw_manifest+from open_second_brain.doctor import check_openclaw_manifest, check_openclaw_installabilityfrom open_second_brain.mcp import MCPServerfrom tests.fixtures import create_plugin_repo@@ -34,7 +34,7 @@ class OpenClawManifestValidityTests(unittest.TestCase):self.assertEqual(schema["type"], "object")def test_manifest_has_version(self):- self.assertEqual(self.manifest["version"], "0.5.0")+ self.assertEqual(self.manifest["version"], "0.5.1")def test_manifest_declares_tools(self):tools = self.manifest["contracts"]["tools"]@@ -60,6 +60,22 @@ class OpenClawManifestValidityTests(unittest.TestCase):f"OpenClaw manifest tools {manifest_tools} do not match MCP tools {mcp_tools}",)+ def test_manifest_has_activation(self):+ self.assertIn("activation", self.manifest)+ self.assertTrue(self.manifest["activation"].get("onStartup"))++ def test_manifest_has_skills(self):+ self.assertIn("skills", self.manifest)+ self.assertIsInstance(self.manifest["skills"], list)++ def test_manifest_has_ui_hints(self):+ self.assertIn("uiHints", self.manifest)+ self.assertIn("vault", self.manifest["uiHints"])++ def test_manifest_mcp_enabled_default_false(self):+ mcp_prop = self.manifest["configSchema"]["properties"]["mcpEnabled"]+ self.assertFalse(mcp_prop.get("default", True))+class OpenClawManifestDoctorTests(unittest.TestCase):"""Test the doctor check for openclaw.plugin.json."""@@ -101,6 +117,88 @@ class OpenClawManifestDoctorTests(unittest.TestCase):self.assertTrue(result.ok, result.message)+class OpenClawPackageJsonTests(unittest.TestCase):+ """Validate the shipped package.json for OpenClaw native plugin compatibility."""++ @classmethod+ def setUpClass(cls):+ cls.pkg_path = ROOT / "package.json"+ with cls.pkg_path.open("r", encoding="utf-8") as f:+ cls.pkg = json.load(f)++ def test_package_json_is_valid_json(self):+ self.assertIsInstance(self.pkg, dict)++ def test_package_json_has_name(self):+ self.assertEqual(self.pkg["name"], "open-second-brain")++ def test_package_json_has_version(self):+ self.assertEqual(self.pkg["version"], "0.5.1")++ def test_package_json_has_type_module(self):+ self.assertEqual(self.pkg["type"], "module")++ def test_package_json_has_openclaw_extensions(self):+ extensions = self.pkg["openclaw"]["extensions"]+ self.assertIsInstance(extensions, list)+ self.assertGreater(len(extensions), 0)++ def test_package_json_extension_entries_exist(self):+ for entry in self.pkg["openclaw"]["extensions"]:+ entry_path = ROOT / entry+ self.assertTrue(entry_path.is_file(), f"Missing extension entry: {entry}")++ def test_package_json_has_no_dependencies(self):+ """The package must not declare dependencies β it imports from the host at runtime."""+ self.assertNotIn("dependencies", self.pkg)+++class OpenClawInstallabilityDoctorTests(unittest.TestCase):+ """Test check_openclaw_installability doctor checks."""++ def test_passes_on_real_repo(self):+ results = check_openclaw_installability(ROOT)+ for r in results:+ self.assertTrue(r.ok, f"{r.name}: {r.message}")++ def test_fails_on_missing_package_json(self):+ with tempfile.TemporaryDirectory() as tmp:+ repo = Path(tmp)+ # No package.json+ results = check_openclaw_installability(repo)+ self.assertFalse(results[0].ok)+ self.assertEqual(results[0].name, "openclaw_package_json")++ def test_fails_on_package_json_without_extensions(self):+ with tempfile.TemporaryDirectory() as tmp:+ repo = Path(tmp)+ (repo / "package.json").write_text(+ json.dumps({"name": "test"}),+ encoding="utf-8",+ )+ results = check_openclaw_installability(repo)+ # First check (package.json exists) passes+ self.assertTrue(results[0].ok)+ # Second check (extensions) fails+ self.assertFalse(results[1].ok)+ self.assertIn("extensions", results[1].message)++ def test_fails_on_missing_extension_file(self):+ with tempfile.TemporaryDirectory() as tmp:+ repo = Path(tmp)+ (repo / "package.json").write_text(+ json.dumps({"openclaw": {"extensions": ["./nonexistent.js"]}}),+ encoding="utf-8",+ )+ results = check_openclaw_installability(repo)+ # First two checks pass+ self.assertTrue(results[0].ok)+ self.assertTrue(results[1].ok)+ # Entry file check fails+ self.assertFalse(results[2].ok)+ self.assertIn("nonexistent.js", results[2].message)++class OpenClawInstallabilityTests(unittest.TestCase):"""Invariants required for `openclaw plugins install` to succeed."""@@ -115,6 +213,9 @@ class OpenClawInstallabilityTests(unittest.TestCase):data = json.loads(self.manifest_path.read_text(encoding="utf-8"))self.assertIn("id", data)+ def test_package_json_exists_at_project_root(self):+ self.assertTrue((ROOT / "package.json").is_file())+def test_bundle_adapter_claude_exists(self):"""OpenClaw Bundle format auto-detects .claude-plugin/."""self.assertTrue((ROOT / ".claude-plugin" / "plugin.json").is_file())@@ -123,11 +224,13 @@ class OpenClawInstallabilityTests(unittest.TestCase):"""OpenClaw Bundle format auto-detects .codex-plugin/."""self.assertTrue((ROOT / ".codex-plugin" / "plugin.json").is_file())- def test_no_package_json(self):- """OpenClaw native plugins need package.json; we deliberately omit it- because we use the Bundle format instead. If package.json is ever added- for tooling (ESLint, etc.), this test should be updated or removed."""- self.assertFalse((ROOT / "package.json").is_file())+ def test_openclaw_entry_js_exists(self):+ """The JS entry declared in package.json must exist."""+ self.assertTrue((ROOT / "openclaw" / "index.js").is_file())++ def test_openclaw_runner_js_exists(self):+ """The subprocess helper must exist."""+ self.assertTrue((ROOT / "openclaw" / "o2b-runner.js").is_file())if __name__ == "__main__":