remnote-mcp-server 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-05-08
+
+### Added
+
+- Added a `remnote-local` MCPB package for Claude Desktop that proxies stdio MCP calls to a locally running
+  `remnote-mcp-server` Streamable HTTP endpoint without public HTTPS, including setup docs, screenshots, and official
+  MCPB references.
+- Added `remnote-mcp-server mcpb-path` to print the bundled Claude Desktop extension path after npm installation.
+- Added the `remnote-mcp-stdio` executable for local MCP clients that consume stdio servers, including help/version
+  output and smoke-test commands in the configuration guide.
+- Added Codex TUI and Codex.app configuration documentation covering Streamable HTTP MCP, `remnote-mcp-stdio`, and
+  `remnote-cli` skill setup.
+- Added MCP protocol compatibility guidance clarifying that `2025-11-25` initialize requests are supported and separate
+  from bridge/server package versions.
+- Added clearer stdio proxy prerequisites and cross-links between the generic stdio MCP client section and the Codex
+  stdio setup example.
+
+### Changed
+
+- Reordered the README AI client setup list to include Codex and prioritize the local Claude Desktop MCPB path before
+  remote connector setup.
+- Updated documentation and agent repo maps to reflect that the old standalone `remnote-cli` repository is
+  discontinued and the maintained CLI lives in this package.
+
 ## [0.14.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -15,9 +15,9 @@ plugin](https://github.com/robert7/remnote-mcp-bridge).
 
 The RemNote MCP Server enables AI assistants like Claude Code to interact directly with your RemNote knowledge base
 through the Model Context Protocol (MCP). The same npm package also provides `remnote-cli`, a command-line MCP client
-for local scripts and coding harnesses. Create notes, hierarchical markdown trees, and RemNote-native flashcards;
-search and read your knowledge base; update existing notes; and maintain your daily journal through MCP tools or shell
-commands.
+for local scripts and coding harnesses, and `remnote-mcp-stdio`, a stdio MCP proxy for clients that cannot consume
+Streamable HTTP directly. Create notes, hierarchical markdown trees, and RemNote-native flashcards; search and read
+your knowledge base; update existing notes; and maintain your daily journal through MCP tools or shell commands.
 
 ## Demo
 
@@ -29,10 +29,11 @@ This system consists of **two separate runtime components** that work together:
 
 1. **[RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-bridge)** - A RemNote plugin that runs in your
    browser or RemNote desktop app and exposes RemNote API functionality via WebSocket
-2. **RemNote MCP Server** (this project) - A standalone server package that provides the `remnote-mcp-server`
-   executable for MCP clients and the `remnote-cli` executable for command-line workflows
+2. **RemNote MCP Server** (this project) - A standalone server package that provides `remnote-mcp-server` for MCP
+   HTTP clients, `remnote-mcp-stdio` for stdio MCP clients, and `remnote-cli` for command-line workflows
 
-The `remnote-cli` command is not a second server. It calls the MCP endpoint exposed by `remnote-mcp-server`.
+The `remnote-cli` and `remnote-mcp-stdio` commands are not second RemNote-facing servers. They call the MCP endpoint
+exposed by `remnote-mcp-server`.
 
 For the detailed bridge connection lifecycle, retry phases, and wake-up triggers, use the bridge repo as the source of
 truth: [Connection Lifecycle Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md).
@@ -41,12 +42,14 @@ truth: [Connection Lifecycle Guide](https://github.com/robert7/remnote-mcp-bridg
 
 ```text
 AI agents (HTTP) -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
+AI agents (stdio) -> remnote-mcp-stdio -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
 CLI commands -> remnote-cli -> MCP HTTP Server :3001 -> WebSocket Server :3002 -> RemNote Plugin -> RemNote
 ```
 
 The server acts as a bridge:
 
 - Communicates with AI agents via Streamable HTTP transport (MCP protocol) - supports both local and remote access
+- Provides `remnote-mcp-stdio` as a local stdio MCP proxy for clients that need stdio transport
 - Provides `remnote-cli` as a bundled command-line MCP client for local automation
 - HTTP server (port 3001) manages MCP sessions for multiple concurrent agents
 - WebSocket server (port 3002) connects to the RemNote browser plugin
@@ -79,11 +82,12 @@ connection always stays local for security. See [Remote Access Guide](docs/guide
 npm install -g remnote-mcp-server
 ```
 
-The package installs both commands:
+The package installs these commands:
 
 ```bash
 remnote-mcp-server --version
 remnote-cli --version
+remnote-mcp-stdio --version
 ```
 
 ### 2. Install the RemNote Plugin
@@ -101,7 +105,7 @@ remnote-mcp-server
 Expected output:
 
 ```text
-RemNote MCP Server v0.14.0 listening { wsPort: 3002, httpPort: 3001 }
+RemNote MCP Server v0.14.1 listening { wsPort: 3002, httpPort: 3001 }
 ```
 
 Keep this terminal running.
@@ -109,10 +113,13 @@ Keep this terminal running.
 ### 4. Configure Your AI Client
 
 - [Configuration Guide](docs/guides/configuration.md) - Overview and generic setup
+  - [Codex TUI / Codex.app](docs/guides/configuration-codex.md) - HTTP MCP, stdio proxy, and `remnote-cli` skill setup
+  - [Claude Desktop Local MCPB](docs/guides/configuration-claude-desktop-local-mcpb.md) - Preferred local Claude Desktop setup, no public HTTPS required
+  - [Claude Desktop / Cowork](docs/guides/configuration-claude-desktop-cowork.md) - Remote connector setup when local MCPB is not applicable
+  - [Claude Code CLI](docs/guides/configuration-claude-code-CLI.md) - Claude Code local MCP setup
   - [ChatGPT](docs/guides/configuration-chatgpt.md) - ChatGPT Apps configuration
-  - [Claude Desktop / Cowork](docs/guides/configuration-claude-desktop-cowork.md) - Remote connector setup (requires remote access setup)
-  - [Claude Code CLI](docs/guides/configuration-claude-code-CLI.md) - Detailed Claude Code CLI configuration
   - [Accomplish](docs/guides/configuration-accomplish.md) - Accomplish (Openwork) configuration
+  - [Generic stdio MCP clients](docs/guides/configuration.md#stdio-mcp-clients) - Use `remnote-mcp-stdio`
 
 ## Documentation
 
@@ -124,6 +131,7 @@ Keep this terminal running.
   \- Match server version to installed bridge plugin version (`0.x` semver)
 - **[Bridge Connection Lifecycle](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/connection-lifecycle.md)** - Canonical bridge connect/retry behavior
 - **[Configuration Guide](docs/guides/configuration.md)** - Configure Claude Code CLI, Accomplish, and other clients
+- **[Codex Configuration Guide](docs/guides/configuration-codex.md)** - Set up Codex TUI and Codex.app with RemNote
 - **[ChatGPT Configuration Guide](docs/guides/configuration-chatgpt.md)** - Set up ChatGPT Apps with your MCP server
 - **[Demo & Screenshots](docs/demo.md)** - See the server in action with different AI clients
 
@@ -163,14 +171,20 @@ Tools that declare an `outputSchema` return MCP `structuredContent` plus a JSON
 See the [MCP tools specification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) for the
 protocol contract.
 
+The server uses `@modelcontextprotocol/sdk` and supports current MCP protocol negotiation, including `2025-11-25`.
+Do not confuse MCP protocol versions with `remnote-mcp-server` or bridge plugin package versions; package versions use
+`0.x` semver and should usually match by minor line.
+
 See the [Tools Reference](docs/guides/tools-reference.md) for detailed usage and examples.
 
 ## Supported AI Clients
 
 - **[Claude Code CLI](https://claude.com/claude-code)** - Local terminal-based agent
+- **Codex TUI / Codex.app** - Local OpenAI coding agent clients
 - **Claude Desktop / Cowork** - Remote connector clients (require [remote access](docs/guides/remote-access.md))
 - **[Accomplish](https://github.com/accomplish-ai/accomplish)** - Task-based MCP client (formerly Openwork)
 - **Any MCP client** supporting Streamable HTTP transport
+- **Any local MCP client** supporting stdio transport through `remnote-mcp-stdio`
 - **Any local command runner** that can call `remnote-cli`
 
 ## Example Usage
@@ -253,7 +267,7 @@ See the [Troubleshooting Guide](docs/guides/troubleshooting.md) for detailed sol
 git clone https://github.com/robert7/remnote-mcp-server.git
 cd remnote-mcp-server
 ./link-cli.sh
-# Later, remove the local links for both remnote-mcp-server and remnote-cli:
+# Later, remove the local links for package executables:
 ./unlink-cli.sh
 ```
 
@@ -274,8 +288,6 @@ For the canonical workflow for updating and running shared live integration cove
 ## Related Projects
 
 - [RemNote Automation Bridge](https://github.com/robert7/remnote-mcp-bridge) - Browser plugin for RemNote integration
-- [Legacy remnote-cli repository](https://github.com/robert7/remnote-cli) - Historical source; the maintained CLI now
-  ships from this package
 - [Model Context Protocol](https://modelcontextprotocol.io/) - Open protocol for AI-application integration
 
 ## License

package/dist/cli.d.ts

@@ -9,6 +9,11 @@ export interface CliOptions {
     requestLog?: string;
     responseLog?: string;
 }
+export declare function getBundledMcpbPath(): string;
+/**
+ * Handle utility commands that do not start the MCP server.
+ */
+export declare function handleUtilityCommand(argv?: string[]): boolean;
 /**
  * Parse CLI arguments and return typed options
  */

package/dist/cli.js

@@ -1,8 +1,23 @@
 import { Command } from 'commander';
 import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 const validLogLevels = ['debug', 'info', 'warn', 'error'];
+const MCPB_PATH_COMMAND = 'mcpb-path';
+export function getBundledMcpbPath() {
+    return fileURLToPath(new URL('../mcpb/remnote-local/remnote-local.mcpb', import.meta.url));
+}
+/**
+ * Handle utility commands that do not start the MCP server.
+ */
+export function handleUtilityCommand(argv = process.argv) {
+    if (argv[2] !== MCPB_PATH_COMMAND) {
+        return false;
+    }
+    console.log(getBundledMcpbPath());
+    return true;
+}
 /**
  * Parse CLI arguments and return typed options
  */
@@ -12,6 +27,7 @@ export function parseCliArgs() {
         .name('remnote-mcp-server')
         .description('MCP server bridge for RemNote knowledge base')
         .version(packageJson.version)
+        .addHelpText('after', '\nCommands:\n  mcpb-path                 Print the bundled Claude Desktop MCPB extension path')
         .option('--ws-port <number>', 'WebSocket port (default: 3002, env: REMNOTE_WS_PORT)', parsePort)
         .option('--http-port <number>', 'HTTP MCP port (default: 3001, env: REMNOTE_HTTP_PORT)', parsePort)
         .option('--http-host <host>', 'HTTP server bind address (default: 127.0.0.1, env: REMNOTE_HTTP_HOST). Use 0.0.0.0 for Docker/VPS deployments', validateHost)

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2,7 +2,7 @@
 import { createRequire } from 'module';
 import { WebSocketServer } from './websocket-server.js';
 import { HttpMcpServer } from './http-server.js';
-import { parseCliArgs } from './cli.js';
+import { handleUtilityCommand, parseCliArgs } from './cli.js';
 import { getConfig } from './config.js';
 import { createLogger, ensureLogDirectory, createRequestResponseLogger } from './logger.js';
 const require = createRequire(import.meta.url);
@@ -69,6 +69,9 @@ async function main() {
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
 }
+if (handleUtilityCommand()) {
+    process.exit(0);
+}
 main().catch((error) => {
     // Pre-logger error handling
     console.error('[MCP Server] Fatal error:', error);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/remnote-cli/client/mcp-server-client.js

@@ -19,7 +19,7 @@ export class McpServerClient {
     clientInfo;
     client = null;
     transport = null;
-    constructor(mcpUrl, clientInfo = { name: 'remnote-cli', version: '0.14.0' }) {
+    constructor(mcpUrl, clientInfo = { name: 'remnote-cli', version: '0.14.1' }) {
         this.mcpUrl = normalizeMcpUrl(mcpUrl);
         this.clientInfo = clientInfo;
     }

package/mcpb/remnote-local/.mcpbignore

@@ -0,0 +1,5 @@
+node_modules/.cache/
+*.log
+coverage/
+dist/
+test/

package/mcpb/remnote-local/README.md

@@ -0,0 +1,25 @@
+# RemNote Local MCPB
+
+Claude Desktop extension that exposes a local `remnote-mcp-server` to Claude Desktop without a public HTTPS tunnel.
+
+## Usage
+
+1. Install and start `remnote-mcp-server`.
+2. Open RemNote with the Automation Bridge plugin enabled and connected.
+3. Install this extension's `.mcpb` file in Claude Desktop.
+4. Keep the default MCP URL unless your server uses a custom port:
+
+```text
+http://127.0.0.1:3001/mcp
+```
+
+This extension does not start or supervise `remnote-mcp-server`. It is a stdio proxy that forwards Claude Desktop tool
+calls to the local Streamable HTTP endpoint.
+
+## Installed Package Path
+
+When installed from npm, print the bundled `.mcpb` path with:
+
+```bash
+remnote-mcp-server mcpb-path
+```

package/mcpb/remnote-local/manifest.json

@@ -0,0 +1,87 @@
+{
+  "manifest_version": "0.3",
+  "name": "remnote-local",
+  "display_name": "RemNote Local",
+  "version": "0.14.1",
+  "description": "Use a locally running RemNote MCP Server from Claude Desktop without a public HTTPS tunnel.",
+  "long_description": "RemNote Local is a Claude Desktop extension that exposes RemNote MCP tools over stdio and forwards calls to a local remnote-mcp-server Streamable HTTP endpoint. Start remnote-mcp-server and keep the RemNote Automation Bridge plugin connected before using the tools.",
+  "author": {
+    "name": "Robert Spiegel",
+    "email": "nightingale7@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robert7/remnote-mcp-server.git"
+  },
+  "homepage": "https://github.com/robert7/remnote-mcp-server",
+  "documentation": "https://github.com/robert7/remnote-mcp-server/tree/main/docs/guides",
+  "support": "https://github.com/robert7/remnote-mcp-server/issues",
+  "server": {
+    "type": "node",
+    "entry_point": "server/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/server/index.js"],
+      "env": {
+        "REMNOTE_MCP_URL": "${user_config.mcp_url}"
+      }
+    }
+  },
+  "tools": [
+    {
+      "name": "remnote_create_note",
+      "description": "Create a new note in RemNote."
+    },
+    {
+      "name": "remnote_search",
+      "description": "Search the RemNote knowledge base."
+    },
+    {
+      "name": "remnote_search_by_tag",
+      "description": "Find notes by tag."
+    },
+    {
+      "name": "remnote_read_note",
+      "description": "Read a specific note from RemNote by Rem ID."
+    },
+    {
+      "name": "remnote_update_note",
+      "description": "Update an existing note in RemNote."
+    },
+    {
+      "name": "remnote_append_journal",
+      "description": "Append content to today's daily document in RemNote."
+    },
+    {
+      "name": "remnote_read_table",
+      "description": "Read an Advanced Table from RemNote."
+    },
+    {
+      "name": "remnote_get_playbook",
+      "description": "Get an operations playbook for MCP agents."
+    },
+    {
+      "name": "remnote_status",
+      "description": "Check bridge connection health and write-policy capabilities."
+    }
+  ],
+  "tools_generated": true,
+  "keywords": ["remnote", "mcp", "notes", "knowledge-base", "local"],
+  "license": "MIT",
+  "compatibility": {
+    "claude_desktop": ">=1.0.0",
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "node": ">=20.0.0"
+    }
+  },
+  "user_config": {
+    "mcp_url": {
+      "type": "string",
+      "title": "Local MCP URL",
+      "description": "Local remnote-mcp-server Streamable HTTP endpoint.",
+      "default": "http://127.0.0.1:3001/mcp",
+      "required": true
+    }
+  }
+}

package/mcpb/remnote-local/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "remnote-local-mcpb",
+  "version": "0.14.1",
+  "description": "Claude Desktop MCPB stdio proxy for a local RemNote MCP Server",
+  "type": "module",
+  "private": true,
+  "main": "server/index.js",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/mcpb/remnote-local/server/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath, URL, pathToFileURL } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+export const DEFAULT_MCP_URL = 'http://127.0.0.1:3001/mcp';
+export const SERVER_INFO = { name: 'remnote-mcp-stdio', version: '0.14.1' };
+
+export const FALLBACK_TOOLS = [
+  {
+    name: 'remnote_create_note',
+    description:
+      'Create a new note in RemNote with optional content, parent, and tags. Supports hierarchical markdown in content and flashcard syntax.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'The title of the note' },
+        content: { type: 'string', description: 'Content as plain text or hierarchical markdown' },
+        parentId: { type: 'string', description: 'Parent Rem ID' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Tags to apply' },
+      },
+    },
+  },
+  {
+    name: 'remnote_search',
+    description: 'Search the RemNote knowledge base.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query text' },
+        limit: { type: 'number', description: 'Maximum results' },
+        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
+        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
+        childLimit: { type: 'number', description: 'Maximum children per level' },
+        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'remnote_search_by_tag',
+    description: 'Find notes by tag.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tag: { type: 'string', description: 'Tag name to search' },
+        limit: { type: 'number', description: 'Maximum results' },
+        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
+        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
+        childLimit: { type: 'number', description: 'Maximum children per level' },
+        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
+      },
+      required: ['tag'],
+    },
+  },
+  {
+    name: 'remnote_read_note',
+    description: 'Read a specific note from RemNote by its Rem ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: { type: 'string', description: 'The Rem ID to read' },
+        depth: { type: 'number', description: 'Depth of child hierarchy to render' },
+        includeContent: { type: 'string', enum: ['none', 'markdown', 'structured'] },
+        childLimit: { type: 'number', description: 'Maximum children per level' },
+        maxContentLength: { type: 'number', description: 'Maximum rendered content length' },
+      },
+      required: ['remId'],
+    },
+  },
+  {
+    name: 'remnote_update_note',
+    description: 'Update an existing note in RemNote.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        remId: { type: 'string', description: 'The Rem ID to update' },
+        title: { type: 'string', description: 'New title' },
+        appendContent: { type: 'string', description: 'Content to append as children' },
+        replaceContent: { type: 'string', description: 'Content to replace direct children' },
+        addTags: { type: 'array', items: { type: 'string' }, description: 'Tags to add' },
+        removeTags: { type: 'array', items: { type: 'string' }, description: 'Tags to remove' },
+      },
+      required: ['remId'],
+    },
+  },
+  {
+    name: 'remnote_append_journal',
+    description: "Append content to today's daily document in RemNote.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        content: { type: 'string', description: "Content to append to today's daily document" },
+        timestamp: { type: 'boolean', description: 'Include timestamp' },
+      },
+      required: ['content'],
+    },
+  },
+  {
+    name: 'remnote_read_table',
+    description: 'Read an Advanced Table from RemNote by exact title or Rem ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tableRemId: { type: 'string', description: 'Table Rem ID' },
+        tableTitle: { type: 'string', description: 'Exact Advanced Table title' },
+        limit: { type: 'number', description: 'Maximum rows to return' },
+        offset: { type: 'number', description: '0-based row offset for pagination' },
+        propertyFilter: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Only return these property/column names',
+        },
+      },
+    },
+  },
+  {
+    name: 'remnote_get_playbook',
+    description: 'Get an operations playbook for MCP agents.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'remnote_status',
+    description:
+      'Check bridge connection health, compatibility warnings, and write-policy capabilities.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export function normalizeMcpUrl(value) {
+  const trimmed = String(value || DEFAULT_MCP_URL).trim();
+  if (trimmed.endsWith('/mcp')) {
+    return trimmed;
+  }
+  return `${trimmed.replace(/\/+$/, '')}/mcp`;
+}
+
+export function createSdkHttpClient(mcpUrl, clientInfo = SERVER_INFO) {
+  const transport = new StreamableHTTPClientTransport(new URL(mcpUrl));
+  const client = new Client(clientInfo);
+  return { client, transport };
+}
+
+export class RemNoteLocalProxy {
+  constructor(options = {}) {
+    this.mcpUrl = normalizeMcpUrl(options.mcpUrl ?? process.env.REMNOTE_MCP_URL);
+    this.createClient = options.createClient ?? createSdkHttpClient;
+  }
+
+  async listTools() {
+    try {
+      return await this.withClient((client) => client.listTools());
+    } catch {
+      return { tools: FALLBACK_TOOLS };
+    }
+  }
+
+  async callTool(params) {
+    try {
+      return await this.withClient((client) => client.callTool(params));
+    } catch (error) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: this.formatConnectionError(error) }],
+      };
+    }
+  }
+
+  registerHandlers(server) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => this.listTools());
+    server.setRequestHandler(CallToolRequestSchema, async (request) =>
+      this.callTool({
+        name: request.params.name,
+        arguments: request.params.arguments ?? {},
+      })
+    );
+  }
+
+  async withClient(operation) {
+    const { client, transport } = this.createClient(this.mcpUrl, SERVER_INFO);
+
+    try {
+      await client.connect(transport);
+      return await operation(client);
+    } finally {
+      await closeBestEffort(transport, client);
+    }
+  }
+
+  formatConnectionError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return [
+      `Cannot connect to local RemNote MCP Server at ${this.mcpUrl}.`,
+      'Start remnote-mcp-server, open RemNote, and ensure the Automation Bridge plugin is connected.',
+      `Details: ${detail}`,
+    ].join(' ');
+  }
+}
+
+export function createStdioServer(options = {}) {
+  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+  const proxy = new RemNoteLocalProxy(options);
+  proxy.registerHandlers(server);
+  return server;
+}
+
+export async function run() {
+  const server = createStdioServer();
+  await server.connect(new StdioServerTransport());
+}
+
+export function formatUsage() {
+  return [
+    'remnote-mcp-stdio - stdio MCP proxy for a local RemNote MCP Server',
+    '',
+    'Usage:',
+    '  remnote-mcp-stdio              Run stdio MCP transport for an MCP client',
+    '  remnote-mcp-stdio --help, -h   Print this help',
+    '  remnote-mcp-stdio --version, -V  Print version',
+    '',
+    'This command is normally launched by a stdio MCP client.',
+    'Start remnote-mcp-server separately first, then let the RemNote Automation Bridge connect to it.',
+    `Default target: ${DEFAULT_MCP_URL}`,
+    '',
+    'Environment:',
+    '  REMNOTE_MCP_URL  Override the local MCP endpoint',
+  ].join('\n');
+}
+
+export function handleUtilityCommand(argv = process.argv) {
+  if (argv.includes('--version') || argv.includes('-V') || argv.includes('-v')) {
+    process.stdout.write(`${SERVER_INFO.version}\n`);
+    return true;
+  }
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    process.stdout.write(`${formatUsage()}\n`);
+    return true;
+  }
+
+  return false;
+}
+
+export function isInteractiveTerminalInvocation(
+  argv = process.argv,
+  stdin = process.stdin,
+  stdout = process.stdout
+) {
+  return argv.length <= 2 && Boolean(stdin.isTTY) && Boolean(stdout.isTTY);
+}
+
+export function isMainModule(argv = process.argv, moduleUrl = import.meta.url) {
+  if (!argv[1]) {
+    return false;
+  }
+
+  try {
+    return realpathSync(argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return pathToFileURL(argv[1]).href === moduleUrl;
+  }
+}
+
+async function closeBestEffort(transport, client) {
+  try {
+    if (typeof transport.terminateSession === 'function') {
+      await transport.terminateSession();
+    }
+  } catch {
+    // Best-effort cleanup: the proxy process can continue serving future calls.
+  }
+
+  try {
+    await client.close();
+  } catch {
+    // Best-effort cleanup: failed closes should not mask the original operation result.
+  }
+}
+
+if (isMainModule()) {
+  if (handleUtilityCommand()) {
+    process.exit(0);
+  }
+
+  if (isInteractiveTerminalInvocation()) {
+    process.stderr.write(`${formatUsage()}\n`);
+    process.exit(1);
+  }
+
+  run().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "remnote-mcp-server",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "MCP server bridge for RemNote knowledge base",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "remnote-mcp-server": "dist/index.js",
-    "remnote-cli": "dist/remnote-cli/index.js"
+    "remnote-cli": "dist/remnote-cli/index.js",
+    "remnote-mcp-stdio": "mcpb/remnote-local/server/index.js"
   },
   "scripts": {
-    "build": "tsc && node scripts/chmod-bins.mjs",
+    "build": "tsc && node scripts/chmod-bins.mjs && node scripts/build-mcpb.mjs",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit",
@@ -19,12 +21,13 @@
     "test:coverage": "vitest run --coverage",
     "test:integration": "./run-integration-test.sh",
     "test:integration:mcp": "tsx test/integration/run-integration.ts",
+    "test:integration:mcpb": "tsx test/integration/run-integration.ts --transport mcpb",
     "test:integration:cli": "tsx test/integration/cli/run-integration.ts",
     "test:ui": "vitest --ui",
-    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
-    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" --fix",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"mcpb/**/*.js\" \"scripts/**/*.mjs\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"mcpb/**/*.js\" \"scripts/**/*.mjs\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\" \"mcpb/**/*.js\" \"mcpb/**/*.json\" \"mcpb/**/*.md\" \"scripts/**/*.mjs\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" \"mcpb/**/*.js\" \"mcpb/**/*.json\" \"mcpb/**/*.md\" \"scripts/**/*.mjs\"",
     "quality": "./code-quality.sh",
     "precommit": "./code-quality.sh"
   },
@@ -39,10 +42,11 @@
     "websocket",
     "bridge"
   ],
-  "author": "nightingale7 <nightingale7@gmail.com>",
+  "author": "Robert Spiegel <nightingale7@gmail.com>",
   "license": "MIT",
   "files": [
     "dist/",
+    "mcpb/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"