semantic-js-mcp 0.8.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "semantic-js-mcp",
+  "version": "0.8.0",
+  "description": "Semantic understanding of JavaScript codebases for AI agents",
+  "author": {
+    "name": "Jonathan Muñoz Lucas"
+  },
+  "license": "MIT",
+  "keywords": ["lsp", "mcp", "javascript", "typescript", "vue", "semantic-analysis", "code-navigation"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Semantic JS MCP",
+    "shortDescription": "Semantic understanding of JavaScript codebases for AI agents",
+    "longDescription": "Adds read-only, workspace-aware TypeScript, JavaScript, Node module, JSX, TSX, and Vue evidence using language servers, complete reference accounting, reusable paged collections, actionable unresolved candidates, and versioned diagnostics.",
+    "developerName": "Jonathan Muñoz Lucas",
+    "category": "Developer Tools",
+    "capabilities": ["Read"],
+    "defaultPrompt": [
+      "Trace this TypeScript symbol and its callers.",
+      "Review this change using semantic references.",
+      "Check focused diagnostics for the edited files."
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "semantic-js-mcp": {
+      "command": "node",
+      "args": ["./server.mjs"],
+      "cwd": ".",
+      "startup_timeout_sec": 30,
+      "tool_timeout_sec": 300,
+      "default_tools_approval_mode": "auto"
+    }
+  }
+}

package/.prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "bracketSpacing": false,
+  "printWidth": 140,
+  "proseWrap": "preserve",
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.8.0] - 2026-07-15
+
+### Added
+
+- Initial pre-release of the read-only semantic evidence server for TypeScript, JavaScript, TSX, JSX, Node module variants, and Vue.
+- Definition, hover, diagnostics, document-symbol, workspace-symbol, named-symbol audit, position audit, and verified-reference tools.
+- Repository-wide text-match accounting that separates requested-symbol matches, different symbols, and unresolved candidates.
+- Explicit collection, presentation, completeness, and diagnostic-trust states.
+- Paged reference collections with content and repository-inventory freshness validation.
+- Workspace-aware TypeScript and Vue language-server selection with cross-workspace reference verification.
+- Vue template fallback for locally imported component bindings and signature recovery from resolved declarations.
+- Visible server and result-schema identity in canonical responses.
+- Runtime checks, generic TypeScript and Vue smoke fixtures, canonical-input CI policy evaluation, and reproducible benchmarks.
+- Literal `not-reported` diagnostic severity when a language server omits severity instead of silently assigning another severity.
+- Codex plugin metadata, semantic-navigation skill, architecture decisions, contribution guide, security policy, and public roadmap.
+- `semantic-js-mcp` executable with `serve`, `doctor`, version, help, JSON, and YAML output paths.
+- Deterministic installation doctor for runtime requirements, provider resolution, MCP startup, tool discovery, TypeScript evidence, diagnostic freshness, and Vue navigation.
+- Explicit npm package allowlist and an isolated tarball installation smoke that prevents runtime reuse of the source checkout.
+- Reproducible Prettier formatting with a repository-wide public-source check in the validation gate.
+
+### Changed
+
+- Runtime provider entry points resolve through Node's package resolution algorithm so npm dependency hoisting is supported.

package/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Semantic JS MCP is pre-release. Changes should preserve its read-only evidence contract and keep collection scope separate from response presentation.
+
+## Requirements
+
+- Node.js 22 or newer;
+- npm with lockfile support;
+- `rg` available on `PATH`.
+
+## Setup
+
+```bash
+npm ci
+npm run format:check
+npm run check
+npm run check:runtime
+npm run doctor
+npm run smoke:ci
+npm run smoke
+npm run smoke:vue
+```
+
+Run `npm run benchmark` for changes that affect repository scanning, reference verification, caching, lifecycle, or memory.
+
+## Source Of Truth
+
+- `protocol.mjs` owns public literals, server identity, schema identity, runtime components, and defaults.
+- `.prettierrc.json` and the `format` scripts define the public source style.
+- `skills/semantic-navigation/references/protocol-literals.md` is generated; update it with `node scripts/generate-protocol-reference.mjs`.
+- `README.md` documents implemented behavior and known limitations.
+- `ROADMAP.md` summarizes public development direction without defining implemented behavior.
+
+## Change Expectations
+
+- Centralize public literals in `protocol.mjs`.
+- Run `npm run format` after changing public source or documentation.
+- Regenerate protocol documentation instead of editing it directly.
+- Add isolated fixtures for positive, partial, and failed evidence.
+- Preserve explicit unresolved candidates and freshness status.
+- Avoid project-specific assumptions in the public MCP or skill.
+- Do not commit `node_modules`, local caches, credentials, or third-party source.
+
+## Validation Expectations
+
+Run the smallest relevant checks while developing, then run the complete local validation suite before submitting a change:
+
+```bash
+npm run check
+npm run check:runtime
+npm run smoke:ci
+npm run smoke
+npm run smoke:vue
+npm run smoke:distribution
+```
+
+Also run `npm run benchmark` when collection cost or memory could change. Run `npm run doctor` when changing runtime resolution, provider startup, the CLI, or diagnostic trust. New behavior should use generic fixtures and cover complete, partial, limited, failed, stale, or untrusted outcomes as applicable.
+
+## Changelog And Versioning
+
+- Add user-visible behavior under `Unreleased` while developing.
+- Move those entries to a dated version section when the package version is finalized.
+- Increment the result-schema version when consumers must understand a changed canonical response shape or identity.
+- A server-version change does not automatically require a result-schema change when the response contract remains compatible.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Muñoz Lucas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+# Semantic JS MCP
+
+**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.
+
+**Better agents begin with better evidence.**
+
+It supports the JavaScript ecosystem, including TypeScript, JavaScript, TSX, JSX, Node module variants, and Vue projects. Language servers provide the underlying semantic data, which the server turns into structured results designed for coding agents.
+
+For each file, it identifies the owning workspace and uses the corresponding TypeScript or Vue language server. Across the repository, it can distinguish verified references from unrelated or unresolved text matches. These results complement text search, source inspection, and focused tests.
+
+## Project Status
+
+Version `0.8.0` is the first public 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
+```
+
+Start a new Codex session after installation. The plugin bundles both the MCP server configuration and the semantic-navigation skill.
+
+### 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`.
+
+## Runtime
+
+- Node.js 22 or newer is supported.
+- 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. Install with `npm ci`; startup verifies their bundled 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.
+
+The package exposes a `semantic-js-mcp` executable. `semantic-js-mcp serve` starts the stdio MCP server, and `semantic-js-mcp doctor` verifies the installed Node runtime, ripgrep, resolved provider paths, MCP startup, tool discovery, TypeScript reference accounting, diagnostic freshness, and Vue navigation.
+
+## Development Setup
+
+From a source checkout:
+
+```bash
+npm ci
+npm run check
+npm run check:runtime
+npm run doctor
+npm run smoke:ci
+npm run smoke
+npm run smoke:vue
+```
+
+Run `npm run benchmark` after changes to scanning, references, caching, lifecycle, or memory. 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": {
+    "semantic-js-mcp": {
+      "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": {
+    "semantic-js-mcp": {
+      "command": "semantic-js-mcp",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+## Tool Graph
+
+Tools are ordered from smaller responses to deeper evidence:
+
+| Tool                            | Provides                                                  | Typical continuation                               |
+| ------------------------------- | --------------------------------------------------------- | -------------------------------------------------- |
+| `lsp_document_symbols`          | Structure for one file                                    | `lsp_definition`, `lsp_audit_symbol`               |
+| `lsp_workspace_symbols`         | Symbol-name discovery                                     | `lsp_count_named_symbol`, `lsp_audit_named_symbol` |
+| `lsp_definition`                | Definition resolution at a position                       | `lsp_hover`, `lsp_count_references`                |
+| `lsp_hover`                     | Inferred type and documentation                           | `lsp_definition`, `lsp_audit_symbol`               |
+| `lsp_diagnostics`               | Focused diagnostics for one file                          | `lsp_definition`, `lsp_hover`                      |
+| `lsp_count_text_matches`        | Exact identifier text count without semantic verification | `lsp_count_named_symbol`, `lsp_audit_named_symbol` |
+| `lsp_count_named_symbol`        | Definition and reference counts by name                   | `lsp_audit_named_symbol`, `lsp_references`         |
+| `lsp_count_references`          | Reference counts at a position                            | `lsp_audit_symbol`, `lsp_references`               |
+| `lsp_audit_named_symbol`        | Composed summary by symbol name                           | `lsp_references`                                   |
+| `lsp_audit_symbol`              | Composed summary at a position                            | `lsp_references`                                   |
+| `lsp_references`                | First page of verified locations                          | `lsp_reference_page`                               |
+| `lsp_reference_page`            | A later page from the same collection                     | `lsp_definition`                                   |
+| `lsp_unresolved_reference_page` | Unresolved candidates with locations and literal reasons  | `lsp_definition`                                   |
+
+Composite audits reuse the same internal definition, hover, and reference primitives as the narrow tools. Compatible count, audit, and reference calls reuse a short-lived reference set.
+
+## Result Contract
+
+Every successful result contains:
+
+- `server`: the literal semantic-js-mcp server name and version that produced the response.
+- `resultSchema`: the literal canonical result schema name and version.
+- `request`: normalized inputs and explicit limit interpretation.
+- `result`: evidence produced by the tool.
+- `collection`: how evidence collection completed.
+- `presentation`: how much collected evidence appears in this response.
+- `continueWith`: exact MCP tool names that can add the next kind of evidence.
+
+`structuredContent` is the canonical JSON object. The text content is YAML generated from that same object and parses back to the same data.
+
+### Collection status
+
+- `complete`: the requested collection scope completed and every discovered item was classified.
+- `limited`: a supplied `maxCandidates` or `maxDefinitions` value stopped collection.
+- `partial`: collection completed with explicitly reported items whose definition or owning file could not be resolved.
+- `failed`: the tool call failed and the error object explains why.
+
+Collection and presentation are independent. A complete collection may use `presentation.mode: page`, `count-only`, `summary-by-file`, or `subset` without weakening its counts.
+
+For reference results, `includeDeclaration: false` excludes locations that resolve to the requested declaration. It never excludes the source position merely because that position initiated the query. The reported invariant is `verifiedTotal = foundByOwningWorkspaceLanguageServer + verifiedFromOtherWorkspaces` after declaration filtering and deduplication.
+
+### Vue template definitions
+
+Definition lookup uses the Vue language server and TypeScript server first. If both leave a Vue template tag unresolved, the server parses the SFC and follows only a matching local import from `<script>` or `<script setup>`. A successful fallback reports `resolutionMethod: vue-template-import-binding-definition`. This proves an imported component binding; it does not infer global component registration or filename-based identity.
+
+The Vue parser and TypeScript AST dependencies are loaded lazily only when this fallback is needed.
+
+### Signature source
+
+Position audits first request hover information at the query position. If that position has a resolved definition but no hover information, the audit requests hover at the resolved declaration. `signatureSource` reports `query-position-hover`, `resolved-definition-hover`, or `not-reported`; `signatureDefinition` identifies the declaration used by the fallback.
+
+### Limits
+
+Collection limits accept positive integers only:
+
+- omitted: `{mode: unlimited}`
+- supplied: `{mode: maximum, maximum: N}`
+
+Omitting `maxCandidates` or `maxDefinitions` requests unlimited collection. `pageSize` and `maxResults` only control returned items for tools that expose them as presentation parameters.
+
+### Text-match accounting
+
+Repository verification reports:
+
+- `matchesFound`
+- `matchesChecked`
+- `matchesToRequestedSymbol`
+- `matchesToDifferentSymbols`
+- `matchesWhoseDefinitionCouldNotBeResolved`
+- `accountingStatus: complete | incomplete`
+
+`accountingStatus: complete` means every discovered text match appears in exactly one classification. Unresolved matches remain explicit and make semantic collection `partial`.
+
+Count and audit responses expose the `referenceSetId` and unresolved-candidate count. Use `lsp_unresolved_reference_page` to inspect those candidates without inflating every summary. The server also queries tsserver `projectInfo` for unresolved candidates and reports whether the file belongs to a configured or inferred TypeScript project. Reasons describe only observed behavior; they do not speculate that an alias caused a failure.
+
+### Freshness
+
+Reusable reference sets store SHA-256 fingerprints for the source file, native reference files, every cross-workspace candidate file, and the relevant `package.json`, `tsconfig.json`, or `jsconfig.json` files. They also store a repository source-inventory fingerprint built from every relevant path, file size, and high-resolution modification time. Reuse and pagination verify both layers, so new, deleted, renamed, or normally modified source files invalidate repository-wide completeness. Changed evidence produces `REFERENCE_SET_CONTENT_CHANGED` and requires a new `lsp_references` collection. Expired or evicted sets produce `REFERENCE_SET_NOT_FOUND_OR_EXPIRED`.
+
+The inventory is sampled before and after collection. If repository sources change during collection, the server retries once and then returns `REPOSITORY_CHANGED_DURING_COLLECTION` instead of publishing an unstable result.
+
+Diagnostics clear their cache on `didChange` and report the analyzed document version and SHA-256 content fingerprint. Only a language-server report for that exact document version appears under `diagnosticsForCurrentDocument`. Otherwise that field is `null`, `evidence.status` is `untrusted`, and any unconfirmed report is isolated under `unconfirmedDiagnosticReport`. Untrusted diagnostics always produce a partial collection.
+
+Diagnostic severities are preserved literally. If a language server omits severity, the result reports `not-reported`; it is not silently treated as information, warning, or error.
+
+### CI policy adapter
+
+MCP tools report evidence; they do not decide whether a code change passes. `npm run ci:evaluate -- <result.json>` applies a deterministic CI policy to one canonical structured result:
+
+- `pass`, exit `0`: complete evidence and no verified error diagnostic.
+- `fail`, exit `1`: verified diagnostics contain an error.
+- `untrusted`, exit `2`: collection is partial or limited.
+- `blocked`, exit `3`: the tool failed or the input is not a semantic-js-mcp result.
+
+Pass `--yaml` after the input path for a YAML representation. The adapter accepts canonical JSON or YAML, validates the server and result-schema identity plus public tool and presentation literals, and never converts incomplete evidence into a pass.
+
+### Installation doctor
+
+`semantic-js-mcp doctor` returns a structured installation report with the same deterministic status vocabulary and exit codes as the CI adapter:
+
+- `pass`, exit `0`: every installation and semantic fixture check passed;
+- `fail`, exit `1`: the server ran, but a functional check returned the wrong result;
+- `untrusted`, exit `2`: runtime checks passed, but a provider did not confirm current diagnostic evidence;
+- `blocked`, exit `3`: a runtime requirement, provider component, or MCP startup step was unavailable.
+
+Use `semantic-js-mcp doctor --yaml` for a YAML representation. An `untrusted` result is not converted to a package failure by the distribution smoke test, but the reason remains explicit in the report.
+
+### Cost visibility
+
+`lsp_count_text_matches` scans repository text without issuing per-match semantic requests. Use it to measure common identifiers before requesting verified counts or audits. Semantic collections preserve omitted limits as unlimited and report text-search time, semantic-verification time, semantic request count, and maximum concurrency. There is no hidden candidate cap.
+
+The bundled Codex MCP configuration allows up to 300 seconds for one tool call. Reaching a client or language-server timeout returns a failed call; it never changes collection scope or reports a timed-out collection as complete.
+
+## Memory Management
+
+Language-server clients and reusable reference sets are released automatically using idle timeout, TTL, and LRU policies. These policies affect reuse only; they do not cap a collection being computed.
+
+Environment variables:
+
+- `SEMANTIC_JS_MCP_CLIENT_IDLE_TIMEOUT_MS` default `60000`
+- `SEMANTIC_JS_MCP_CLIENT_MINIMUM_EVICTION_AGE_MS` default `15000`
+- `SEMANTIC_JS_MCP_MAXIMUM_ACTIVE_CLIENTS` default `4`
+- `SEMANTIC_JS_MCP_REFERENCE_SET_TTL_MS` default `300000`
+- `SEMANTIC_JS_MCP_MAXIMUM_REFERENCE_SETS` default `12`
+- `SEMANTIC_JS_MCP_MAXIMUM_CHANGED_REFERENCE_SET_MARKERS` default `24`
+- `SEMANTIC_JS_MCP_MAXIMUM_CACHED_REFERENCE_LOCATIONS` default `50000`
+- `SEMANTIC_JS_MCP_DEFAULT_REFERENCE_PAGE_SIZE` default `100`
+- `SEMANTIC_JS_MCP_CROSS_WORKSPACE_CONCURRENCY` default `6`
+
+A single reference collection may exceed the cache-location budget so it can still be paged. Older collections are evicted first.
+
+## Verification
+
+```bash
+npm run check
+npm run check:runtime
+npm run doctor
+npm run smoke
+npm run smoke:ci
+npm run smoke:vue
+npm run smoke:distribution
+```
+
+`npm run benchmark` measures text counting, verified reference collection, memory, and freshness-validation latency at configurable match counts. Set `SEMANTIC_JS_MCP_BENCHMARK_COUNTS=10,100,1000,10000` to include the 10,000-match scale.
+
+`npm run smoke:distribution` packs the explicit npm file allowlist, installs the tarball into a temporary consumer project, runs the installed executable, and verifies that runtime components resolve from the consumer dependency tree rather than the source checkout.
+
+The smoke tests create temporary generic TypeScript and Vue projects. They do not depend on a specific application repository.
+
+## Current Limitations
+
+- The server provides static semantic evidence, not runtime call tracing or behavioral proof.
+- Empty references and clean diagnostics do not establish absence or correctness.
+- Vue named-component discovery remains ambiguous when filenames, component names, import aliases, global registration, and test doubles differ. Prefer a position-based audit when an exact use is available.
+- Diagnostics remain `untrusted` when the owning language server does not correlate a report with the current document version.
+- Dynamic imports, computed property access, generated code, runtime dependency injection, and dynamically constructed class names may require text search and direct source inspection.
+- CSS graph analysis, Tailwind semantics, and other language domains are intentionally outside this project. Provider-native diagnostics embedded in Vue documents may still be preserved.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned areas of development. Roadmap items describe direction, not release commitments.
+
+## Project Documents
+
+- [Architecture decisions](docs/architecture-decisions.md)
+- [Distribution verification](docs/distribution.md)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Maintainer
+
+[Jonathan Muñoz Lucas](https://mx.linkedin.com/in/nonathan)

package/ROADMAP.md

@@ -0,0 +1,37 @@
+# Roadmap
+
+Semantic JS MCP is under active development. This roadmap outlines areas of investigation and intended development. Items are directional and are not release commitments.
+
+## Reliability
+
+- Improve current-document diagnostic confirmation across supported language servers.
+- Keep semantic evidence fresh across edits, file additions, removals, renames, and workspace configuration changes.
+- Expand deterministic fixtures for complete, partial, limited, failed, stale, and untrusted outcomes.
+- Continue measuring collection latency, memory use, and language-server lifecycle behavior at repository scale.
+
+## Vue
+
+- Improve named-component discovery for single-file components.
+- Expand template binding resolution while preserving explicit uncertainty for global or dynamic registration.
+- Improve diagnostics and signature recovery in complex Vue files.
+
+## React And JSX
+
+- Add framework-focused fixtures for components, hooks, props, re-exports, aliases, and higher-order patterns.
+- Document the evidence boundaries for dynamic JSX composition and runtime component selection.
+
+## Agent-Facing Results
+
+- Keep result vocabulary literal, finite, and versioned.
+- Improve compact presentation without hiding collection scope or unresolved evidence.
+- Expand examples for combining count, audit, reference, diagnostic, text-search, source-inspection, and test evidence.
+
+## Distribution
+
+- Expand reproducible package and plugin release checks across supported Node.js LTS releases and hosted CI.
+- Document setup for additional MCP hosts using the same public server contract.
+- Add immutable release-source, upgrade, rollback, and installed-plugin verification.
+
+## Additional Language Domains
+
+CSS, preprocessors, utility-class frameworks, and other language domains may be explored as independent providers. Any expansion must preserve source attribution, explicit uncertainty, and the read-only evidence contract.

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+Semantic JS MCP is a read-only developer tool that starts bundled language servers and reads local source files. It must not apply workspace edits, execute repository-provided commands, require credentials, or use network access during normal local analysis.
+
+## Supported Versions
+
+During pre-release development, security fixes are applied to the latest version only.
+
+## Reporting A Vulnerability
+
+Report vulnerabilities privately using the maintainer address in `package.json` or GitHub private vulnerability reporting when available. Do not open a public issue for an unpatched vulnerability.
+
+Do not include repository credentials, proprietary source, access tokens, or other secrets in a report.
+
+Include:
+
+- semantic-js-mcp version;
+- Node.js version;
+- operating system;
+- affected tool;
+- minimal reproduction using non-sensitive source;
+- observed and expected behavior.

package/cli.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import {stringify as stringifyYaml} from "yaml";
+import {CLI_ARGUMENT, CLI_COMMAND, CLI_MESSAGE, DEFAULT, PROCESS_EXIT_CODE, PRODUCT, SERVER_VERSION} from "./protocol.mjs";
+
+const HELP = `Usage: ${PRODUCT.NAME} [command] [options]
+
+Commands:
+  ${CLI_COMMAND.SERVE}       Start the MCP server over stdio (default)
+  ${CLI_COMMAND.DOCTOR}      Verify the installed runtime and semantic providers
+
+Options:
+  ${CLI_ARGUMENT.YAML}       Render doctor output as YAML instead of JSON
+  ${CLI_ARGUMENT.HELP}, ${CLI_ARGUMENT.HELP_SHORT}   Show this help
+  ${CLI_ARGUMENT.VERSION}, ${CLI_ARGUMENT.VERSION_SHORT}   Show the installed version
+`;
+
+const args = process.argv.slice(DEFAULT.PROCESS_ARGUMENT_OFFSET);
+const commandIndex = args.findIndex((argument) => !argument.startsWith("-"));
+const command = commandIndex >= 0 ? args[commandIndex] : CLI_COMMAND.SERVE;
+const commandArguments = args.filter((_, index) => index !== commandIndex);
+const acceptedArguments = command === CLI_COMMAND.DOCTOR ? new Set([CLI_ARGUMENT.YAML]) : new Set();
+const unknownArguments = commandArguments.filter((argument) => !acceptedArguments.has(argument));
+
+if (args.includes(CLI_ARGUMENT.HELP) || args.includes(CLI_ARGUMENT.HELP_SHORT) || command === CLI_COMMAND.HELP) {
+  process.stdout.write(HELP);
+} else if (args.includes(CLI_ARGUMENT.VERSION) || args.includes(CLI_ARGUMENT.VERSION_SHORT) || command === CLI_COMMAND.VERSION) {
+  process.stdout.write(`${SERVER_VERSION}\n`);
+} else if (args.length > 0 && commandIndex < 0) {
+  process.stderr.write(`${CLI_MESSAGE.UNKNOWN_OPTION}: ${args[0]}\n\n${HELP}`);
+  process.exitCode = PROCESS_EXIT_CODE.FAILURE;
+} else if (unknownArguments.length > 0) {
+  process.stderr.write(`${CLI_MESSAGE.UNKNOWN_ARGUMENT}: ${unknownArguments[0]}\n\n${HELP}`);
+  process.exitCode = PROCESS_EXIT_CODE.FAILURE;
+} else if (command === CLI_COMMAND.SERVE) {
+  await import("./server.mjs");
+} else if (command === CLI_COMMAND.DOCTOR) {
+  const {runDoctor} = await import("./lib/doctor.mjs");
+  const result = await runDoctor();
+  process.stdout.write(args.includes(CLI_ARGUMENT.YAML) ? stringifyYaml(result, {lineWidth: 0}) : `${JSON.stringify(result, null, 2)}\n`);
+  process.exitCode = result.exitCode;
+} else {
+  process.stderr.write(`${CLI_MESSAGE.UNKNOWN_COMMAND}: ${command}\n\n${HELP}`);
+  process.exitCode = PROCESS_EXIT_CODE.FAILURE;
+}

package/docs/architecture-decisions.md

@@ -0,0 +1,72 @@
+# Architecture Decisions
+
+This document records accepted product boundaries. These decisions may be revised through an explicit change that documents the reason and migration impact.
+
+## DEC-001: Independent MCPs By Semantic Domain
+
+Status: accepted
+
+Semantic support for JavaScript, CSS, PHP, and other domains belongs in independent projects with separate dependencies, processes, releases, installation, and lifecycle management.
+
+This project is `semantic-js-mcp`; it does not load or bundle semantic providers for other domains.
+
+## DEC-002: Composition Belongs To The Consumer
+
+Status: accepted
+
+One MCP does not call another MCP. A model, skill, CI adapter, or other consumer decides whether evidence from multiple semantic domains is needed.
+
+This avoids runtime coupling, chained failures, implicit configuration, and assumptions that another product exists.
+
+## DEC-003: Common Representation, Domain-Specific Evidence
+
+Status: accepted
+
+Related semantic MCPs should use a compatible evidence envelope when practical:
+
+- server identity;
+- result-schema identity;
+- tool and normalized request;
+- result;
+- collection status;
+- presentation status;
+- exact continuation tool names.
+
+Each domain owns the vocabulary inside its result. A CSS class relationship is not represented as a JavaScript LSP reference.
+
+## DEC-004: Continuations Stay Inside One MCP
+
+Status: accepted
+
+`continueWith` names tools from the server that produced the response. It does not recommend tools from another MCP. Cross-product guidance belongs in consumer documentation or skills.
+
+## DEC-005: Narrow And Composed Tools Coexist
+
+Status: accepted
+
+Narrow tools provide one focused fact with a small response. Composed audits reuse the same internal primitives to reduce tool calls for consumers that can use a larger evidence summary.
+
+Composed tools do not remove access to narrow tools and do not weaken collection accounting.
+
+## DEC-006: Preserve Provider-Native Embedded Evidence
+
+Status: accepted
+
+The JavaScript ecosystem includes mixed-language documents. When the owning provider reports diagnostics for a Vue template or embedded CSS, SCSS, or Less block, semantic-js-mcp preserves that evidence instead of filtering it according to another provider's domain.
+
+Where it can be determined safely, diagnostic evidence should identify:
+
+- provider;
+- document language;
+- embedded region;
+- embedded language.
+
+Unknown provenance remains explicit. Provider-native style diagnostics do not imply complete CSS graph analysis.
+
+## DEC-007: Extract Shared Code Only After A Second Implementation
+
+Status: accepted
+
+The project may document transferable concepts, but it will not create a shared runtime package or universal provider framework before a second semantic MCP demonstrates concrete duplication.
+
+Compatibility should begin with result concepts and conformance fixtures, not premature runtime coupling.