semantic-js-mcp 0.10.2 → 0.10.4

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "author": {
     "name": "Jonathan Muñoz Lucas"

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.4] - 2026-07-20
+
+### Changed
+
+- Make `lsp_diagnostics` state explicitly whether current-document diagnostics are available, whether an unconfirmed provider report exists, and whether the result is usable as current-document diagnostic evidence. Untrusted results now direct agents to repository-native validation without treating missing or stale diagnostics as a clean file.
+- Rework setup into a numbered procedure that establishes command authority before any local tool call, separates the host application from its installation route, recommends the positively identified current application as the generic stdio target for confirmation, makes every generic-host command and configuration action user-run, rejects cross-route and temporary `npx` installation, and hands sandbox-blocked work back to the user without changing permissions or installation paths.
+- Add an explicit verification-only operation, distinguish a host route from its Codex plugin, global-package, or source-checkout server source, require exact host-command help before registration or removal, reject saved commands or connection states that do not match the intended stdio entry, and keep optional functional tests scoped to one confirmed source file.
+- Keep setup responses in the user's language and retain user-run version checks for generic hosts because low-risk commands can still observe a sandbox-specific runtime instead of the user's actual environment.
+
+## [0.10.3] - 2026-07-18
+
+### Changed
+
+- Consolidate installation into `SETUP.md`, the shared setup procedure for people and coding agents. README now provides only a brief entry point. The procedure places guards, prerequisites, installation, and verification before troubleshooting and background; uses direct explanatory language; requires exact host and version checks; rejects partial npm extraction; and does not treat installation as permission to inspect source code.
+
 ## [0.10.2] - 2026-07-17
 
 ### Added

package/README.md

@@ -1,13 +1,25 @@
 # Semantic JS MCP
 
+## Setup
+
+Before running an installation command, follow [SETUP.md](SETUP.md). It is the
+single source of truth for setup by either a person or a coding agent, including
+prerequisites, host selection, installation, verification, updates, rollback,
+and removal.
+
+Semantic JS MCP requires Node.js 22 or newer and `rg` (ripgrep). It can be
+installed through the verified Codex plugin route or registered as a local
+stdio server in another compatible MCP host. Package installation alone does not configure an MCP host.
+
+After setup, see [Getting started](docs/getting-started.md) for practical
+investigation prompts and compact evidence examples.
+
 **Your coding agent is only as good as its understanding of your codebase.**
 
 Coding agents can generate code quickly, but reliable engineering requires more than reading files and matching text. They need to understand which declaration a reference belongs to, how symbols cross workspace boundaries, whether the collected evidence is complete, and whether that evidence is still accurate.
 
 Semantic JS MCP gives coding agents structured, read-only semantic context so they can navigate, review, and change code with explicit uncertainty.
 
-When a user explicitly asks a coding agent to install or configure the package, the agent should follow the [agent setup guide](AGENT_SETUP.md).
-
 Its scope is intentionally narrow: it strengthens an agent's understanding of symbol identity, types, references, diagnostics, and evidence coverage. It does not replace architectural reasoning, source inspection, dependency analysis, tests, or runtime observation.
 
 **Better agents begin with better evidence.**
@@ -18,45 +30,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.10.2` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
-
-## Installation
-
-### Codex plugin
-
-Add the public marketplace, then install the plugin:
-
-```bash
-codex plugin marketplace add elnonathan/semantic-js-mcp
-codex plugin add semantic-js-mcp@elnonathan
-```
-
-Codex CLI 0.144.4 or newer is required for npm-backed marketplace installation. Start a new Codex session after installation. The plugin bundles both the MCP server configuration and the semantic-navigation skill.
-
-### Updating the Codex plugin
-
-Codex installs from a local snapshot of each configured marketplace. Refresh that snapshot before reinstalling so `plugin add` resolves the version currently declared by the marketplace:
-
-```bash
-codex plugin marketplace upgrade elnonathan
-codex plugin add semantic-js-mcp@elnonathan
-codex plugin list
-```
-
-`plugin add` reinstalls the plugin; a separate removal is not required. Start a new Codex session after the command reports the expected version.
-
-### MCP executable
-
-Install the package globally when using an MCP host that accepts a command-based stdio configuration:
-
-```bash
-npm install --global semantic-js-mcp
-semantic-js-mcp doctor
-```
-
-Configure the host to run `semantic-js-mcp serve`.
-
-For practical investigation prompts and compact evidence examples, see [Getting started](docs/getting-started.md).
+Version `0.10.4` is the current release. APIs and result contracts may evolve while the project remains on the `0.x` release line. See the [roadmap](ROADMAP.md) for areas under consideration.
 
 ## Runtime
 
@@ -64,7 +38,7 @@ For practical investigation prompts and compact evidence examples, see [Getting
 - Node.js 24 LTS is recommended for new installations. See the [Node.js release schedule](https://nodejs.org/en/about/previous-releases).
 - `rg` (ripgrep) must be available on `PATH` for repository-wide discovery.
 - The nearest workspace TypeScript SDK is used when available; the bundled TypeScript SDK is the fallback.
-- TypeScript, `typescript-language-server`, and the Vue language server are pinned dependencies. Published packages bundle every production dependency so Codex installations do not require a separate dependency installation step. Source checkouts use `npm ci`; startup verifies provider entry points before accepting MCP requests.
+- TypeScript, `typescript-language-server`, and the Vue language server are pinned dependencies. Published packages bundle every production dependency so Codex installations do not require a separate dependency installation step. Startup verifies provider entry points before accepting MCP requests.
 - Source discovery and language selection include `.ts`, `.tsx`, `.mts`, `.cts`, `.js`, `.jsx`, `.mjs`, `.cjs`, and `.vue` files.
 - Run `npm run check:runtime` to report every required component and its resolved file path.
 
@@ -72,10 +46,10 @@ The package exposes a `semantic-js-mcp` executable. `semantic-js-mcp serve` star
 
 ## Development Setup
 
-From a source checkout:
+Complete the [source-checkout setup](SETUP.md#source-checkout), then run the
+checks applicable to the change:
 
 ```bash
-npm ci
 npm run check
 npm run check:runtime
 npm run doctor
@@ -87,34 +61,6 @@ npm run smoke:lifecycle
 
 Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. Provider disposal changes can also be characterized with `npm run benchmark:lifecycle-memory`; its output declares the garbage-collection and platform measurement method. Normal analysis is local and read-only; it does not require network access after dependencies are installed.
 
-For an MCP host that accepts a direct stdio configuration, point it at the checked-out server using an absolute path:
-
-```json
-{
-  "mcpServers": {
-    "semanticjsmcp": {
-      "command": "node",
-      "args": ["/absolute/path/to/semantic-js-mcp/server.mjs"]
-    }
-  }
-}
-```
-
-The bundled [`.mcp.json`](.mcp.json) provides the relative-path configuration used when the repository is installed as a Codex plugin.
-
-When the package executable is available on the host's `PATH`, the equivalent stdio configuration is:
-
-```json
-{
-  "mcpServers": {
-    "semanticjsmcp": {
-      "command": "semantic-js-mcp",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
 ## Tool Graph
 
 Tools are ordered from smaller responses to deeper evidence: