semantic-js-mcp 0.10.1 → 0.10.2

package/.codex-plugin/plugin.json

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

package/AGENT_SETUP.md

@@ -0,0 +1,176 @@
+# Agent Setup
+
+This guide is for a coding agent whose user has explicitly requested that it
+install, configure, update, verify, roll back, or remove Semantic JS MCP. It is
+not an instruction to change an environment merely because this file was read.
+
+## Scope
+
+First identify the application that will run the MCP server. That application
+is the MCP host. Use the verified Codex procedure only for Codex. For every
+other host, use the generic stdio procedure below and translate its fields into
+the host's documented configuration format. Do not guess a configuration file
+or schema.
+
+Semantic JS MCP requires Node.js 22 or newer and `rg` (ripgrep) on `PATH`.
+Before changing host configuration, run:
+
+```bash
+node --version
+rg --version
+```
+
+Stop if Node.js is older than 22 or either command is unavailable. Report the
+missing prerequisite. Do not continue with a partial installation.
+
+## Safety Boundaries
+
+This guide does not override system, developer, organization, repository, or
+host security policy.
+
+- Inspect existing configuration before editing it and change only the entry
+  approved by the user.
+- Request any approval required for package installation, global writes,
+  configuration changes, network access, or process restart.
+- Never request or expose credentials, disable security controls, or execute a
+  remote shell pipeline.
+- Preserve every unrelated MCP server and setting. Never replace an entire
+  configuration file to add one server.
+- Stop and report the blocker when the requested host or prerequisite cannot be
+  verified safely.
+
+## Installation Procedure
+
+### Codex
+
+Use the public marketplace adapter:
+
+```bash
+codex plugin marketplace add elnonathan/semantic-js-mcp
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+Start a new Codex session after installation. The plugin supplies both the MCP
+server and the semantic-navigation skill.
+
+### Generic Stdio Hosts
+
+Use this procedure only when the host supports local MCP servers over stdio. If
+that capability cannot be confirmed from installed help or host documentation,
+stop and report that the host is unsupported or unverified.
+
+After the user approves the package installation and configuration change,
+install the executable:
+
+```bash
+npm install --global semantic-js-mcp
+```
+
+Inspect the existing host configuration. Add exactly one MCP server with these
+values:
+
+- server name: `semanticjsmcp`
+- transport: `stdio`
+- executable or command: `semantic-js-mcp`
+- arguments: one argument, `serve`
+- enabled: `true`, when the host has an enabled field
+
+Do not configure a URL, port, shell command, or credentials. The host must
+start `semantic-js-mcp serve` as a local child process and communicate through
+standard input and standard output. Translate the values above into the host's
+documented schema; do not copy a configuration shape from a different host.
+
+Save the smallest possible change. Restart or reload the host when its
+documentation requires it.
+
+## Verification
+
+For an executable installation, record the installed version and run the
+doctor:
+
+```bash
+semantic-js-mcp --version
+semantic-js-mcp doctor
+```
+
+Read the structured doctor result literally:
+
+- `pass`: continue to host tool verification.
+- `untrusted`: continue to host tool verification and report the stated
+  uncertainty. Do not describe it as `pass`.
+- `blocked` or `fail`: stop, correct the reported problem when authorized, or
+  report the blocker. Do not claim a successful installation.
+
+Then verify the host discovers tools whose base names begin with `lsp_`. A host
+may display the server name before the base name. Execute one read-only call
+such as `lsp_document_symbols` against a user-approved JavaScript, TypeScript,
+or Vue file. Do not claim successful installation from configuration text
+alone.
+
+For a Codex plugin installation without a global executable, verify the version
+with `codex plugin list`, start a new session, and confirm MCP tool discovery
+there.
+
+Installation is successful only when the host discovers the MCP tools and one
+read-only `lsp_*` call returns a result. Package installation or configuration
+text alone is not success.
+
+## Update And Rollback
+
+Update an existing Codex installation by refreshing its marketplace snapshot
+before reinstalling:
+
+```bash
+codex plugin marketplace upgrade elnonathan
+codex plugin add semantic-js-mcp@elnonathan
+codex plugin list
+```
+
+Update a global npm installation with:
+
+```bash
+npm install --global semantic-js-mcp@latest
+```
+
+Before updating, record the working version. To roll back a global installation,
+install that exact known version, for example:
+
+```bash
+npm install --global semantic-js-mcp@0.10.1
+```
+
+For a host adapter, restore the previously recorded package version and host
+configuration together. Do not replace or remove unrelated configuration while
+rolling back.
+
+## Removal
+
+For Codex, remove only this plugin:
+
+```bash
+codex plugin remove semantic-js-mcp@elnonathan
+```
+
+Remove the `elnonathan` marketplace only when the user confirms that no other
+installed plugin uses it:
+
+```bash
+codex plugin marketplace remove elnonathan
+```
+
+For a global executable, remove the package and only its `semanticjsmcp` MCP
+entry:
+
+```bash
+npm uninstall --global semantic-js-mcp
+```
+
+Restart the host and confirm the tools are no longer registered.
+
+## Completion Report
+
+Report the detected host, installed or removed version, exact configuration
+entry changed, doctor status when available, tool-discovery result, required
+restart, and any remaining uncertainty. Do not include credentials or unrelated
+configuration values.

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-07-17
+
+### Added
+
+- Add `AGENT_SETUP.md` with safe installation, verification, update, rollback, and removal steps for Codex and standard stdio MCP hosts.
+- Expand semantic-navigation guidance for values assembled from multiple sources so agents inspect existing merge rules, related helpers, consumers, and boundary cases before changing precedence or fallback behavior.
+
 ## [0.10.1] - 2026-07-17
 
 ### Added

package/README.md

@@ -6,6 +6,8 @@ Coding agents can generate code quickly, but reliable engineering requires more
 
 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.**
@@ -16,7 +18,7 @@ For each file, it identifies the owning workspace and uses the corresponding Typ
 
 ## Project Status
 
-Version `0.10.1` 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.
+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
 
@@ -90,7 +92,7 @@ For an MCP host that accepts a direct stdio configuration, point it at the check
 ```json
 {
   "mcpServers": {
-    "semantic-js-mcp": {
+    "semanticjsmcp": {
       "command": "node",
       "args": ["/absolute/path/to/semantic-js-mcp/server.mjs"]
     }
@@ -105,7 +107,7 @@ When the package executable is available on the host's `PATH`, the equivalent st
 ```json
 {
   "mcpServers": {
-    "semantic-js-mcp": {
+    "semanticjsmcp": {
       "command": "semantic-js-mcp",
       "args": ["serve"]
     }

package/docs/getting-started.md

@@ -10,6 +10,10 @@ Semantic JS MCP adds static semantic evidence to an agent's existing code invest
 
 > Review the authentication changes in this diff. Use semantic evidence to verify every material symbol and cross-workspace reference, corroborate reachability with text search and direct source inspection, and distinguish introduced defects from pre-existing behavior.
 
+## Review Combination Logic
+
+> Review this precedence, fallback, normalization, or merge change. Identify every producer of the combined domain value, recover the invariant encoded by existing helpers and direct consumers, verify the discovered symbols and references with semantic evidence, and test a boundary case that could disprove the proposed rule.
+
 ## Check Current Diagnostics
 
 > Check current diagnostics for `src/handler.ts`. Treat the file as clean only if the language server confirms the current document snapshot; otherwise report the result as untrusted and explain the required follow-up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
   "keywords": [
     "mcp",
@@ -28,6 +28,7 @@
     ".codex-plugin/",
     ".mcp.json",
     ".prettierrc.json",
+    "AGENT_SETUP.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "ROADMAP.md",

package/protocol.mjs

@@ -408,7 +408,7 @@ export const RESULT_SCHEMA = Object.freeze({
   VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.10.1";
+export const SERVER_VERSION = "0.10.2";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",

package/scripts/distribution-policy.mjs

@@ -2,6 +2,7 @@ export const REQUIRED_PACKAGE_FILE = Object.freeze({
   PACKAGE_MANIFEST: "package.json",
   PRETTIER_CONFIGURATION: ".prettierrc.json",
   README: "README.md",
+  AGENT_SETUP: "AGENT_SETUP.md",
   LICENSE: "LICENSE",
   CLI: "cli.mjs",
   SERVER: "server.mjs",

package/scripts/documentation-contract.mjs

@@ -2,12 +2,21 @@ import {DOCTOR_REASON, SEMANTIC_EVIDENCE_FOLLOW_UP_REASON} from "../protocol.mjs
 
 export const DOCUMENTATION_FILE = Object.freeze({
   README: "README.md",
+  AGENT_SETUP: "AGENT_SETUP.md",
   GETTING_STARTED: "docs/getting-started.md",
+  SEMANTIC_NAVIGATION_SKILL: "skills/semantic-navigation/SKILL.md",
   CONTRIBUTING: "CONTRIBUTING.md",
   SECURITY: "SECURITY.md",
 });
 
-export const PUBLIC_ROOT_DOCUMENT = Object.freeze(["CHANGELOG.md", "CONTRIBUTING.md", "README.md", "ROADMAP.md", "SECURITY.md"]);
+export const PUBLIC_ROOT_DOCUMENT = Object.freeze([
+  "AGENT_SETUP.md",
+  "CHANGELOG.md",
+  "CONTRIBUTING.md",
+  "README.md",
+  "ROADMAP.md",
+  "SECURITY.md",
+]);
 
 export const PUBLIC_DOCUMENT_DIRECTORY = Object.freeze(["docs", "skills"]);
 
@@ -24,14 +33,37 @@ export const DOCUMENTATION_REQUIREMENT = Object.freeze({
   GETTING_STARTED_HEADINGS: Object.freeze([
     "Trace A Symbol",
     "Review A Security-Sensitive Change",
+    "Review Combination Logic",
     "Check Current Diagnostics",
     "Complete Evidence",
     "Partial Evidence",
     "Untrusted Diagnostics",
     "Startup Failure",
   ]),
-  README_LINKS: Object.freeze(["docs/getting-started.md", "CONTRIBUTING.md", "SECURITY.md"]),
+  AGENT_SETUP_HEADINGS: Object.freeze([
+    "Scope",
+    "Safety Boundaries",
+    "Installation Procedure",
+    "Verification",
+    "Update And Rollback",
+    "Removal",
+    "Completion Report",
+  ]),
+  SEMANTIC_NAVIGATION_SKILL_HEADINGS: Object.freeze(["Preserve Combination Invariants"]),
+  README_LINKS: Object.freeze(["AGENT_SETUP.md", "docs/getting-started.md", "CONTRIBUTING.md", "SECURITY.md"]),
   GETTING_STARTED_LITERALS: Object.freeze([SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_PARTIAL, DOCTOR_REASON.RUNTIME_COMPONENT_MISSING]),
+  AGENT_SETUP_LITERALS: Object.freeze([
+    "semantic-js-mcp doctor",
+    "semantic-js-mcp serve",
+    "does not override system, developer, organization, repository",
+    "npm uninstall --global semantic-js-mcp",
+    "server name: `semanticjsmcp`",
+  ]),
+  SEMANTIC_NAVIGATION_SKILL_LITERALS: Object.freeze([
+    "Identify every producer of the value",
+    "boundary case that could disprove",
+    "conceptual relationships that an LSP cannot establish",
+  ]),
 });
 
 export const DOCUMENTATION_REASON = Object.freeze({

package/scripts/documentation-gate-smoke.mjs

@@ -7,7 +7,9 @@ import {evaluateDocumentation} from "./documentation-gate.mjs";
 const headingText = (headings) => headings.map((heading) => `## ${heading}`).join("\n");
 const valid = {
   [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.AGENT_SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.GETTING_STARTED]: `${headingText(DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: `${headingText(DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.CONTRIBUTING]: "# Contributing",
   [DOCUMENTATION_FILE.SECURITY]: "# Security",
 };
@@ -59,6 +61,71 @@ strictEqual(
   "Missing marketplace upgrade guidance was accepted",
 );
 
+const missingAgentSetupLink = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(`[doc](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`, ""),
+};
+strictEqual(
+  evaluateDocumentation(missingAgentSetupLink).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
+  ),
+  true,
+  "Missing agent setup README link was accepted",
+);
+
+const missingAgentSetup = {...valid};
+delete missingAgentSetup[DOCUMENTATION_FILE.AGENT_SETUP];
+strictEqual(
+  evaluateDocumentation(missingAgentSetup).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.AGENT_SETUP,
+  ),
+  true,
+  "Missing agent setup guide was accepted",
+);
+
+const missingAgentSafetyBoundary = {
+  ...valid,
+  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingAgentSafetyBoundary).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2],
+  ),
+  true,
+  "Missing agent setup safety boundary was accepted",
+);
+
+const missingGenericServerName = {
+  ...valid,
+  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingGenericServerName).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4],
+  ),
+  true,
+  "Missing generic MCP server name was accepted",
+);
+
+const missingCombinationInvariant = {
+  ...valid,
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
+    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+    "",
+  ),
+};
+strictEqual(
+  evaluateDocumentation(missingCombinationInvariant).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+  ),
+  true,
+  "Missing combination-invariant guidance was accepted",
+);
+
 process.stdout.write(
   `${JSON.stringify(
     {
@@ -66,6 +133,11 @@ process.stdout.write(
       missingHeading: "rejected",
       missingLiteral: "rejected",
       missingMarketplaceUpgrade: "rejected",
+      missingAgentSetupLink: "rejected",
+      missingAgentSetup: "rejected",
+      missingAgentSafetyBoundary: "rejected",
+      missingGenericServerName: "rejected",
+      missingCombinationInvariant: "rejected",
       privateCoordination: "rejected",
     },
     null,

package/scripts/documentation-gate.mjs

@@ -35,7 +35,9 @@ export function evaluateDocumentation(documents) {
 
   const headingRequirements = [
     [DOCUMENTATION_FILE.README, DOCUMENTATION_REQUIREMENT.README_HEADINGS],
+    [DOCUMENTATION_FILE.AGENT_SETUP, DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS],
     [DOCUMENTATION_FILE.GETTING_STARTED, DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS],
+    [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL, DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS],
   ];
   for (const [file, requiredHeadings] of headingRequirements) {
     if (documents[file] === undefined) continue;
@@ -66,6 +68,26 @@ export function evaluateDocumentation(documents) {
     }
   }
 
+  const agentSetup = documents[DOCUMENTATION_FILE.AGENT_SETUP];
+  if (agentSetup !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS) {
+      if (agentSetup.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.AGENT_SETUP, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
+  }
+
+  const semanticNavigationSkill = documents[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL];
+  if (semanticNavigationSkill !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS) {
+      if (semanticNavigationSkill.includes(literal)) continue;
+      findings.push({
+        file: DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL,
+        reason: DOCUMENTATION_REASON.LITERAL_MISSING,
+        literal,
+      });
+    }
+  }
+
   for (const [file, source] of Object.entries(documents)) {
     if (PRIVATE_COORDINATION_PATTERN.test(source)) {
       findings.push({file, reason: DOCUMENTATION_REASON.PRIVATE_COORDINATION});

package/skills/semantic-navigation/SKILL.md

@@ -131,6 +131,24 @@ Omitted collection limits still mean unlimited. The server never inserts a hidde
 4. Inspect focused tests for asserted behavior; run them when permitted.
 5. Re-read cited locations before presenting a finding.
 
+### Preserve Combination Invariants
+
+When a change combines multiple sources into one domain value or introduces
+precedence, fallback, normalization, ordering, or merge logic:
+
+1. Identify every producer of the value, not only the source involved in the
+   reported example.
+2. Find existing comparison, normalization, fallback, and combination helpers
+   and state the invariant they encode.
+3. Inspect direct consumers and focused tests to confirm how the combined value
+   is treated as a contract.
+4. Exercise a boundary case that could disprove the proposed precedence or
+   merge rule.
+
+Semantic tools verify the identities and references discovered during this
+work. Use text search, direct source inspection, tests, and domain reasoning for
+conceptual relationships that an LSP cannot establish.
+
 An actionable finding requires a reachable path, a violated contract, and concrete impact. For commit or pull-request reviews, compare with the exact parent and classify material conclusions as `introduced`, `modified`, or `pre-existing`.
 
 Empty symbol, reference, or diagnostic results are evidence to investigate. Use `collection`, `textSearch`, `rg`, and direct inspection to establish the supported conclusion.

package/skills/semantic-navigation/references/protocol-literals.md

@@ -2,7 +2,7 @@
 
 Generated from `protocol.mjs`. Do not edit this file directly.
 
-Producer: `semantic-js-mcp` version `0.10.1`
+Producer: `semantic-js-mcp` version `0.10.2`
 Display name: `Semantic JS MCP`
 Result schema version: `7`