Skip to content

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.json
index 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.json
index 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.yml
index b9ba6d81..1e9e8912 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -82,6 +82,16 @@ jobs:
bash -n scripts/vault-log
scripts/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 distributions
run: |
python -m pip install --upgrade pip build
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.1
diff --git a/README.md b/README.md
index 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 run
diff --git a/after-install.md b/after-install.md
index 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.
## OpenClaw
If 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:
```bash
o2b 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.md
index 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 model
diff --git a/install.md b/install.md
index 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-brain
This 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
```bash
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.json
new file mode 100644
index 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.yaml
index 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: standalone
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 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: standalone
diff --git a/pyproject.toml b/pyproject.toml
index 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__.py
index 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.py
index ed6f8b47..dac10b3e 100644
--- a/src/open_second_brain/cli.py
+++ b/src/open_second_brain/cli.py
@@ -6,11 +6,13 @@ import os
import sys
from pathlib import Path
+import json as _json
+
from open_second_brain.config import default_config_path, discover_config, redact_mapping
from open_second_brain.doctor import doctor
from open_second_brain.event_log import append_event
from 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_server
from open_second_brain.uninstall import plan_uninstall, render_plan
from 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 parser
def 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.py
index 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 results
diff --git a/src/open_second_brain/mcp.py b/src/open_second_brain/mcp.py
index 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_f
PROTOCOL_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.py
index 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.py
index 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.py
index 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 json
import tempfile
@@ -7,7 +7,7 @@ from pathlib import Path
ROOT = 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_installability
from open_second_brain.mcp import MCPServer
from 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__":