golutra-mcp 0.1.0 → 0.1.2

package/.env.example

@@ -1,5 +1,6 @@
-# Optional. If unset, mcp-golutra first tries the macOS app-bundled CLI path
-# and then falls back to resolving `golutra-cli` from PATH.
+# Optional. If unset, golutra-mcp first tries platform-specific default
+# install paths for `golutra-cli`, then falls back to the platform command
+# name from PATH (`golutra-cli.exe` on Windows, `golutra-cli` elsewhere).
 GOLUTRA_CLI_PATH=golutra-cli
 GOLUTRA_PROFILE=stable
 GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file.
 
 The format follows Keep a Changelog, and this project uses Semantic Versioning.
 
+## [Unreleased]
+
+## [0.1.2] - 2026-03-22
+
+### Changed
+
+- Clarified the runtime `workspacePath` contract so per-tool `workspacePath` input is treated as a one-time override, while `golutra-set-context` remains the only way to persist a new default workspace
+- Added regression tests to lock the workspace context behavior at both `ContextStore` level and workspace-aware tool level
+- Expanded README and `STARTUP_PROCESS.md` so AI hosts can understand the recommended runtime flow for diagnostics, workspace switching, and normal tool execution
+- Added `docs/WORKSPACE_CONTEXT_EXAMPLES.md` with concrete examples for stored defaults, one-off workspace overrides, recommended tool order, and a real chat flow
+- Updated the diagnostic examples to explain that a `workspacePath` passed to `golutra-diagnose` affects only that call and does not mutate the stored default context
+
+## [0.1.1] - 2026-03-21
+
+### Changed
+
+- Synced `scripts/e2e-smoke.mjs` with the layered `golutra-diagnose` output so self-hosted smoke tests validate the current diagnostic contract
+- Expanded the basic GitHub Actions check workflow to run on Linux, macOS, and Windows so platform-specific regressions surface earlier
+- Included `docs/` in the npm publish file list so packaged users can open the referenced diagnostic example document locally
+- Renamed `startup_processmd.md` to `STARTUP_PROCESS.md` and updated repository links to use a stable public-facing document name
+- Removed stale `mcp-golutra` wording from the bug report template so issue reports match the published package name
+- Stopped hardcoding the MCP server runtime version in source scripts and now read it from `package.json`
+
 ## [0.1.0] - 2026-03-17
 
 ### Added
@@ -14,7 +37,7 @@ The format follows Keep a Changelog, and this project uses Semantic Versioning.
 - `golutra-reset-context` and `golutra-diagnose` for runtime troubleshooting
 - ESLint, TypeScript, and Vitest based quality gates
 - CI workflow, contribution guide, security policy, and code of conduct
-- Dedicated `startup_processmd.md` for setup/start/build/validation flow
+- Dedicated `STARTUP_PROCESS.md` for setup/start/build/validation flow
 
 ### Changed
 
@@ -27,6 +50,6 @@ The format follows Keep a Changelog, and this project uses Semantic Versioning.
 - Started tracking the built `dist/` output so GitHub source archives also include runnable server files instead of documentation only
 - Switched the user-facing default profile examples from `dev` to `stable` so published usage aligns with the release app instead of development builds
 - Reworked `README.md` into a project-introduction document focused on purpose, architecture, tool surface, and design boundaries
-- Moved startup, environment, and local development instructions out of `README.md` into `startup_processmd.md`
+- Moved startup, environment, and local development instructions out of `README.md` into `STARTUP_PROCESS.md`
 - Replaced `README.md` again with a bilingual project-homepage version that explains what the project is, what it is today, and the future direction in English and Chinese
-- Moved the remaining reference and operational material from `README.md` into `startup_processmd.md`
+- Moved the remaining reference and operational material from `README.md` into `STARTUP_PROCESS.md`

package/README.md

@@ -1,10 +1,85 @@
-# golutra-mcp
+<p align="center">
+  <a href="https://www.golutra.com/" target="_blank" rel="noopener noreferrer">
+    <img
+      width="96"
+      src="./assets/readme/golutra-logo.png"
+      alt="golutra logo"
+    />
+  </a>
+</p>
+
+<h1 align="center">golutra-mcp</h1>
+
+<p align="center">
+  MCP bridge for Golutra via golutra-cli. <br />
+  通过 golutra-cli 暴露 Golutra 能力的 MCP 桥接层。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/npm/v/golutra-mcp?label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/npm/dm/golutra-mcp?label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/golutra/golutra-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/golutra/golutra-mcp/ci.yml?branch=main&label=ci" alt="ci"></a>
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/badge/node-%3E%3D20.11-2f7af8" alt="node version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-ff9f1a" alt="license"></a>
+</p>
+
+<p align="center">
+  <a href="#english">English</a> ·
+  <a href="#中文">中文</a> ·
+  <a href="https://www.npmjs.com/package/golutra-mcp">npm</a> ·
+  <a href="https://github.com/golutra/golutra-mcp">GitHub</a> ·
+  <a href="./STARTUP_PROCESS.md">Startup Process</a> ·
+  <a href="./docs/WORKSPACE_CONTEXT_EXAMPLES.md">Workspace Examples</a> ·
+  <a href="./docs/GOLUTRA_DIAGNOSE_EXAMPLES.md">Diagnose Examples</a>
+</p>
+
+<p align="center">
+  Keep Golutra as the app runtime. Use golutra-cli as the stable boundary. Expose the workflow through MCP. <br />
+  保留 Golutra 作为桌面运行时，以 golutra-cli 作为稳定边界，再通过 MCP 暴露给外部 AI 宿主。
+</p>
+
+---
 
-`golutra-mcp` is an MCP bridge project for Golutra.
+## English
 
-`golutra-mcp` 是一个面向 Golutra 的 MCP 桥接项目。
+### Install
 
-## English
+`golutra-mcp` is now published on npm as `golutra-mcp`.
+
+Install it as a normal MCP server package:
+
+```bash
+npm install -g golutra-mcp
+```
+
+Run it with a published Golutra desktop installation.
+
+macOS:
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
 
 ### What This Project Is
 
@@ -14,7 +89,7 @@ It is not a replacement for Golutra itself, and it does not re-implement Golutra
 
 ### What It Is Today
 
-The current project is a usable engineering preview, not yet a fully mature public integration product.
+The current project is an installable public MCP server release with its first npm distribution already published.
 
 Today it already provides:
 
@@ -24,7 +99,7 @@ Today it already provides:
 - skill validation and direct project `SKILL.md` reading for local Golutra skill workflows
 - an open-source project skeleton with contribution, security, CI, and release-facing metadata
 
-At the current stage, the project should be understood as a focused integration layer that can already be downloaded and evaluated, but still needs broader real-world validation before it should be treated as a fully mature public MCP distribution.
+At the current stage, it should be understood as a real downloadable integration package that is ready for evaluation, pilot usage, and downstream MCP wiring, but still needs broader real-world validation before it should be treated as a fully hardened long-term public integration product.
 
 ### Why It Exists
 
@@ -37,6 +112,49 @@ That means this repository is mainly responsible for:
 - safe command wrapping
 - diagnostics and integration ergonomics
 
+### Runtime Requirements
+
+To work correctly, the server still depends on the existing Golutra desktop runtime:
+
+- a locally installed Golutra desktop application
+- a reachable `golutra-cli` binary
+- a valid Golutra workspace path
+- the target Golutra desktop app profile running locally, usually `stable`
+
+Default CLI discovery by platform:
+
+- macOS: `/Applications/Golutra.app/Contents/MacOS/golutra-cli`, then `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`, then `golutra-cli` from `PATH`
+- Windows: `%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`, then `%ProgramFiles%\Golutra\golutra-cli.exe`, then `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`, then `golutra-cli.exe` from `PATH`
+- Linux: `~/.local/bin/golutra-cli`, then `~/.cargo/bin/golutra-cli`, then `/usr/local/bin/golutra-cli`, `/usr/bin/golutra-cli`, `/opt/Golutra/golutra-cli`, `/app/bin/golutra-cli`, then `golutra-cli` from `PATH`
+
+### Diagnostics
+
+Use `golutra-diagnose` when you need to separate:
+
+- CLI path problems
+- missing or invalid workspace paths
+- missing user identity for app-backed probes
+- app-not-running or profile-mismatch failures
+- generic app command failures
+
+Detailed diagnostic output fields and common `reasonCode` values are documented in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`.
+
+### What An AI Host Should Do
+
+If an AI system or MCP-compatible host sees this repository, the intended usage is:
+
+1. Launch `golutra-mcp` as a local `stdio` MCP server, not as an HTTP service.
+2. Provide `GOLUTRA_CLI_PATH`, `GOLUTRA_PROFILE`, and usually `GOLUTRA_WORKSPACE_PATH`.
+3. Call `golutra-get-context` or `golutra-diagnose` first to confirm runtime readiness.
+4. Use the structured tool flow instead of inventing a custom transport:
+   `golutra-list-conversations` -> `golutra-list-messages` / `golutra-send-message` / `golutra-read-roadmap` / `golutra-update-roadmap`.
+5. Treat `golutra-cli` as the stable boundary. Do not bypass this project by directly calling Golutra local socket IPC unless you intentionally want to maintain a separate integration layer.
+6. When switching workspaces for a single request, pass `workspacePath` on that tool call. Use `golutra-set-context` only when you want to persist a new default for later calls.
+
+In short: start with diagnostics, keep workspace and profile explicit, and use the provided MCP tools as the integration contract.
+
+For concrete workspace switching and chat flow examples, see `docs/WORKSPACE_CONTEXT_EXAMPLES.md`.
+
 ### Future Direction
 
 The next stages should move the project from "basic bridge" to "usable integration product."
@@ -50,9 +168,9 @@ Likely future work includes:
 - tighter documentation around real Golutra collaboration workflows
 - stronger release hardening across installation paths, packaging validation, and end-to-end compatibility checks
 
-### Getting Started
+### Source Development
 
-Try from source first:
+If you want to run or modify the repository from source instead of installing the npm package:
 
 ```bash
 npm install
@@ -62,19 +180,48 @@ export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 npm run dev
 ```
 
-Use the npm package after you are ready to consume it as a normal MCP server distribution:
+Detailed startup, validation, and client wiring instructions live in `STARTUP_PROCESS.md`.
+
+## 中文
+
+### 安装方式
+
+`golutra-mcp` 现在已经以 `golutra-mcp` 这个包名发布到 npm。
+
+按普通 MCP Server 包安装即可：
 
 ```bash
 npm install -g golutra-mcp
-export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
+```
+
+建议配合已安装的 Golutra 桌面应用直接运行。
+
+macOS：
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
 export GOLUTRA_PROFILE=stable
 export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 golutra-mcp
 ```
 
-Detailed startup, validation, and client wiring instructions live in `startup_processmd.md`.
+Windows PowerShell：
 
-## 中文
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux：
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
 
 ### 这是什么项目
 
@@ -84,7 +231,7 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 
 ### 当前阶段是什么
 
-当前这个项目已经进入“可下载试用的工程化预发布”阶段，但还不能算“完全成熟、长期稳定的公共 MCP 成品”。
+当前这个项目已经进入“可下载安装的公开版本”阶段，并且第一版 npm 包已经发布。
 
 现阶段已经具备：
 
@@ -94,7 +241,7 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 技能校验与项目 `SKILL.md` 直接读取能力，能覆盖本地技能开发链路
 - 基本完整的开源项目骨架，包括贡献规范、安全策略、CI 和发布元数据
 
-但它现在还不是一个“已经经过广泛真实场景验证的完整 Golutra 远程集成产品”，更准确的定位是：一个已经能下载试用、也具备基本发布骨架的 MCP 集成底座。
+但它现在还不是一个“已经经过大规模真实场景验证、长期充分打磨”的成熟公共集成产品。更准确的定位是：一个已经可以下载安装、接入验证、试点使用的 Golutra MCP 集成层。
 
 ### 这个项目解决什么问题
 
@@ -107,6 +254,49 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 对现有 CLI 能力的稳定封装
 - 联通诊断与集成体验
 
+### 运行前提
+
+这个 MCP Server 运行时依赖现有的 Golutra 本地运行环境：
+
+- 本机已安装 Golutra 桌面应用
+- 能访问到 `golutra-cli`
+- 已知的有效工作区路径
+- 本地已启动目标 profile 的 Golutra 桌面应用，通常使用 `stable`
+
+按平台的默认 CLI 自动发现顺序：
+
+- macOS：`/Applications/Golutra.app/Contents/MacOS/golutra-cli`，然后 `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`，最后回退到 `PATH` 里的 `golutra-cli`
+- Windows：`%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`，然后 `%ProgramFiles%\Golutra\golutra-cli.exe`，再然后 `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`，最后回退到 `PATH` 里的 `golutra-cli.exe`
+- Linux：`~/.local/bin/golutra-cli`，然后 `~/.cargo/bin/golutra-cli`、`/usr/local/bin/golutra-cli`、`/usr/bin/golutra-cli`、`/opt/Golutra/golutra-cli`、`/app/bin/golutra-cli`，最后回退到 `PATH` 里的 `golutra-cli`
+
+### 诊断能力
+
+需要排查问题时，可以优先用 `golutra-diagnose` 区分：
+
+- CLI 路径问题
+- workspacePath 缺失或非法
+- userId 缺失导致 app 探针跳过
+- 桌面应用未运行或 profile 不匹配
+- 普通 app 命令失败
+
+更完整的诊断输出字段和常见 `reasonCode` 说明见 `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`。
+
+### AI 看到这个项目后应该怎么做
+
+如果一个 AI 系统或支持 MCP 的宿主看到这个仓库，推荐按下面方式接入：
+
+1. 把 `golutra-mcp` 当作本地 `stdio` MCP Server 启动，不要把它当成 HTTP 服务。
+2. 提供 `GOLUTRA_CLI_PATH`、`GOLUTRA_PROFILE`，通常还需要提供 `GOLUTRA_WORKSPACE_PATH`。
+3. 先调用 `golutra-get-context` 或 `golutra-diagnose`，确认运行时上下文和联通状态。
+4. 按现有工具面走标准调用链路，不要自造传输协议：
+   `golutra-list-conversations` -> `golutra-list-messages` / `golutra-send-message` / `golutra-read-roadmap` / `golutra-update-roadmap`。
+5. 把 `golutra-cli` 视为稳定边界。除非你明确准备长期维护另一套集成层，否则不要绕过这个项目去直连 Golutra 本地 socket IPC。
+6. 如果只是某一次调用切换工作区，就在该次 tool 调用里显式传 `workspacePath`。只有在你希望后续调用默认都改到新工作区时，才使用 `golutra-set-context`。
+
+一句话概括：先诊断，再显式设置 workspace/profile，然后把 README 里提供的 MCP tools 当作正式集成契约来用。
+
+如果你想看“工作区切换”和“真实聊天链路”的具体调用示例，直接看 `docs/WORKSPACE_CONTEXT_EXAMPLES.md`。
+
 ### 后续规划
 
 后续项目应该从“能桥接”继续推进到“更好用、可发布、可维护”。
@@ -120,9 +310,9 @@ Detailed startup, validation, and client wiring instructions live in `startup_pr
 - 补齐围绕真实 Golutra 协作场景的文档和示例
 - 继续补强跨平台安装路径、自诊断、端到端兼容性验证
 
-### 开始使用
+### 源码开发
 
-建议先从源码试用：
+如果你要按源码方式运行或参与开发：
 
 ```bash
 npm install
@@ -132,22 +322,16 @@ export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 npm run dev
 ```
 
-确认链路符合预期后，再按普通 MCP 包的方式安装：
-
-```bash
-npm install -g golutra-mcp
-export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
-export GOLUTRA_PROFILE=stable
-export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
-golutra-mcp
-```
-
-更完整的启动、验证与客户端接入说明见 `startup_processmd.md`。
+更完整的启动、验证与客户端接入说明见 `STARTUP_PROCESS.md`。
 
 ## Documentation
 
 - Startup, installation, validation, and MCP client wiring:
-  [startup_processmd.md](./startup_processmd.md)
+  [STARTUP_PROCESS.md](./STARTUP_PROCESS.md)
+- Workspace override and stored default examples:
+  [docs/WORKSPACE_CONTEXT_EXAMPLES.md](./docs/WORKSPACE_CONTEXT_EXAMPLES.md)
+- Diagnostic output examples and reason codes:
+  [docs/GOLUTRA_DIAGNOSE_EXAMPLES.md](./docs/GOLUTRA_DIAGNOSE_EXAMPLES.md)
 - Contribution guide:
   [CONTRIBUTING.md](./CONTRIBUTING.md)
 - Security policy:

package/{startup_processmd.md → STARTUP_PROCESS.md}

@@ -1,4 +1,4 @@
-# startup_processmd
+# STARTUP_PROCESS
 
 This document contains the setup, startup, build, validation, local integration steps, and the detailed operational notes previously kept in `README.md`.
 
@@ -43,6 +43,18 @@ This repository focuses on protocol translation, context management, diagnostics
 - `golutra-set-context` updates defaults for later tool calls
 - `golutra-reset-context` restores defaults from the process environment used at startup
 - `golutra-diagnose` verifies `golutra-cli` reachability and, when both `workspacePath` and `userId` are available, probes app connectivity with `chat.conversations.list`
+- `golutra-diagnose` now returns layered checks for `cliPath`, `cliCommand`, `workspace`, `userId`, and `appConnection`
+- `golutra-diagnose` also returns `summary.status` (`ok`, `partial`, `error`), `reasonCodes`, and `nextSteps`
+- Detailed output examples and common `reasonCode` values live in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`
+
+### Workspace Override Contract
+
+- Passing `workspacePath` in a tool call is a one-time override for that call only
+- `golutra-set-context` is the explicit operation that persists a new default `workspacePath` for later calls
+- If an AI host switches workspaces frequently, prefer passing `workspacePath` per call instead of mutating shared defaults
+- 如果只是某一次调用临时切换工作区，直接在该次 tool 输入里传 `workspacePath`
+- 如果希望后续调用默认都切到新工作区，再使用 `golutra-set-context`
+- Concrete request sequences are documented in `docs/WORKSPACE_CONTEXT_EXAMPLES.md`
 
 ### Current Limitations
 
@@ -76,7 +88,7 @@ It still needs more real-world validation across MCP hosts, operating systems, a
 ## Environment Variables
 
 - `GOLUTRA_CLI_PATH`
-  Default: auto-discover the macOS app-bundled CLI when available, otherwise `golutra-cli`
+  Default: auto-discover a platform-specific `golutra-cli` install when available, otherwise fall back to the platform command name from `PATH`
 - `GOLUTRA_PROFILE`
   Optional Golutra runtime profile: `dev`, `canary`, or `stable`
 - `GOLUTRA_WORKSPACE_PATH`
@@ -86,6 +98,12 @@ It still needs more real-world validation across MCP hosts, operating systems, a
 
 Use [.env.example](./.env.example) as the minimal local template.
 
+Default CLI discovery order:
+
+- macOS: `/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `golutra-cli`
+- Windows: `%LOCALAPPDATA%\Programs\Golutra\golutra-cli.exe`, `%ProgramFiles%\Golutra\golutra-cli.exe`, `%ProgramFiles(x86)%\Golutra\golutra-cli.exe`, `golutra-cli.exe`
+- Linux: `~/.local/bin/golutra-cli`, `~/.cargo/bin/golutra-cli`, `/usr/local/bin/golutra-cli`, `/usr/bin/golutra-cli`, `/opt/Golutra/golutra-cli`, `/app/bin/golutra-cli`, `golutra-cli`
+
 ## Install Dependencies
 
 ```bash
@@ -102,6 +120,75 @@ npm install -g golutra-mcp
 
 Then configure your MCP client to launch `golutra-mcp` directly.
 
+Typical launch examples by platform:
+
+macOS:
+
+```bash
+export GOLUTRA_CLI_PATH=/Applications/Golutra.app/Contents/MacOS/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\Users\<you>\AppData\Local\Programs\Golutra\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/usr/bin/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+## Quick Verification After Install
+
+Use this sequence when you want to confirm that the published package and the local Golutra runtime are wired correctly.
+
+1. Confirm the package is visible from npm:
+
+```bash
+npm view golutra-mcp version
+```
+
+2. Confirm the binary can start with your local Golutra runtime settings:
+
+macOS/Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\absolute\path\to\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+3. If your MCP host can call tools immediately, run `golutra-get-context` or `golutra-diagnose`.
+
+What to expect:
+
+- `golutra-get-context` should return the resolved `cliPath`, `profile`, `workspacePath`, and `timeoutMs`
+- `golutra-diagnose` should report `checks.cliPath.ok = true` and `checks.cliCommand.ok = true`
+- If you also provide a valid workspace `userId`, `golutra-diagnose` should attempt the app-backed `chat.conversations.list` probe
+
+If installation succeeds but runtime access still fails, use `golutra-diagnose` first and then compare the output with `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`.
+
 ## Local Development
 
 Start the MCP server directly from source:
@@ -187,6 +274,43 @@ npm pack --dry-run
 
 `prepack` is configured to build the project before npm packaging.
 
+## Publish To npm
+
+Use this flow for a normal public npm release:
+
+1. Confirm you are in the repository root and that checks pass:
+
+```bash
+cd /path/to/golutra-mcp
+npm run check
+npm pack
+```
+
+2. Confirm your npm CLI session is authenticated:
+
+```bash
+npm whoami
+```
+
+3. Publish the package:
+
+```bash
+npm publish
+```
+
+4. Verify the published result:
+
+```bash
+npm view golutra-mcp version
+npm view golutra-mcp
+```
+
+Release notes:
+
+- If `npm publish` reports that the version already exists, bump `package.json` to the next version and publish again
+- If npm requires browser or OTP confirmation, complete that flow and wait for the CLI to print `+ golutra-mcp@<version>`
+- `npm pack` creates a local `.tgz` artifact in the repository root; this is useful for pre-publish inspection or private file distribution
+
 ## Self-Hosted E2E CI
 
 The repository includes a dedicated GitHub Actions workflow for real MCP smoke tests on a macOS self-hosted runner:
@@ -205,7 +329,7 @@ Recommended runner prerequisites:
 Repository variables:
 
 - `GOLUTRA_E2E_WORKSPACE_PATH`: required unless provided as a workflow input
-- `GOLUTRA_E2E_CLI_PATH`: optional, defaults to `/Applications/Golutra.app/Contents/MacOS/golutra-cli`
+- `GOLUTRA_E2E_CLI_PATH`: optional, defaults to the same platform-specific discovery rules as runtime startup; macOS runners commonly use `/Applications/Golutra.app/Contents/MacOS/golutra-cli`
 - `GOLUTRA_E2E_PROFILE`: optional, defaults to `stable`
 - `GOLUTRA_E2E_USER_ID`: required only when the workflow is run with `app_probe=true`
 

package/dist/index.js

@@ -4,9 +4,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { NodeCliJsonRunner } from "./lib/cli-runner.js";
 import { ContextStore, createInitialContext } from "./lib/context.js";
 import { GolutraCliGateway } from "./lib/golutra-client.js";
+import { readPackageMetadata } from "./lib/package-metadata.js";
 import { registerTools } from "./lib/toolkit.js";
-const SERVER_NAME = "golutra-mcp";
-const SERVER_VERSION = "0.1.0";
+const { name: SERVER_NAME, version: SERVER_VERSION } = readPackageMetadata();
 async function main() {
     const server = new McpServer({
         name: SERVER_NAME,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,GAAG,aAAa,CAAC;AAClC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAC;IAE/D,kDAAkD;IAClD,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,qBAAqB,OAAO,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,mBAAmB,EAAE,CAAC;AAE7E,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,cAAc;KACxB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,IAAI,iBAAiB,EAAE,CAAC,CAAC;IAE/D,kDAAkD;IAClD,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,MAAM,QAAQ,GAAG,KAAK,IAAmB,EAAE;QACzC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,KAAK,QAAQ,EAAE,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACtF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,qBAAqB,OAAO,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/context.d.ts

@@ -11,6 +11,7 @@ export declare class ContextStore {
     constructor(initialContext: RuntimeContextSnapshot);
     getSnapshot(): RuntimeContextSnapshot;
     reset(): RuntimeContextSnapshot;
+    private mergeContext;
     update(nextValues: CommandContextInput): RuntimeContextSnapshot;
     resolveCommandContext(nextValues?: CommandContextInput): RuntimeContextSnapshot;
     requireWorkspacePath(nextValues?: CommandContextInput): string;