# vue-ts-lsp-mcp

Self-contained, type-aware code intelligence for **TypeScript / JavaScript / Vue**, exposed to
MCP clients (Claude Code) as tools. A fork of [`cclsp`](https://github.com/ktnyt/cclsp) that
bundles its own language servers so it needs **no global installs**.

## Why this fork

| Addition | What it does |
|----------|--------------|
| **Vendored language servers** | `typescript-language-server`, `@vue/language-server`, and `typescript` live in `vendor/node_modules` and are committed. No `npx`, no global installs, no network at runtime. |
| **Working `.vue` deep TS** | Hover / definition / references / diagnostics inside `<script setup lang="ts">`. `@vue/language-server` 3.x (Volar 2.x) ships no in-process TS service; this fork spawns a side-car `tsserver` with `@vue/typescript-plugin` and bridges it (`src/lsp/adapters/tsserver-bridge.ts`). Upstream cclsp times out on these. |
| **Relative-path output** | Tool results show project-relative paths (node_modules collapsed) instead of absolute paths. Root via `CCLSP_REL_ROOT`, else cwd. |
| **MCP server instructions** | The server advertises when/how to use each tool (prefer it over grep for symbol work), surfaced to the client on connect. |
| **Env-expanded config** | `cclsp.json` command/`rootDir` expand `${VAR}` tokens, so vendored binaries resolve via `${CCLSP_PLUGIN_ROOT}` regardless of install location. |
| **esbuild build** | Node-native bundle (`scripts/build.mjs`) — no `bun` required. |

## Install as a Claude Code plugin

The repo is a Claude plugin (`.claude-plugin/plugin.json` + `.mcp.json`). Point a local
marketplace at it and install, or add it directly. On install it registers an MCP server named
`vue-ts-lsp` (tools appear as `mcp__vue-ts-lsp__*`). Nothing else to set up — the language servers
are vendored. The distinct name avoids any clash with an upstream `cclsp` install. The server
advertises its own usage guidance (when to prefer it over grep) via MCP instructions on connect,
so no companion skill is required.

The MCP server is launched as:

```jsonc
// .mcp.json
{
  "vue-ts-lsp": {
    "command": "node",
    "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
    "env": {
      "CCLSP_CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/cclsp.json",
      "CCLSP_PLUGIN_ROOT": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}
```

`CCLSP_REL_ROOT` is intentionally unset — paths relativize against the server's working directory
(your project root). Set it explicitly if your client launches the server elsewhere.

## Tools

`find_definition` · `find_references` · `find_implementation` · `find_workspace_symbols` ·
`get_hover` · `prepare_call_hierarchy` · `get_incoming_calls` · `get_outgoing_calls` ·
`get_diagnostics` · `rename_symbol` · `rename_symbol_strict` · `restart_server`.

Routing guidance (which tool for which question, addressing, gotchas) is delivered to the client as
MCP server instructions on connect — see `SERVER_INSTRUCTIONS` in `index.ts`.

## Develop

```bash
npm install        # build deps (esbuild, typescript, MCP SDK) — root node_modules, NOT committed
npm run build      # esbuild -> dist/index.js  (commit dist/ so the plugin runs on install)
npm run typecheck  # tsc --noEmit (production sources; bun:test files excluded)
node scripts/smoke.mjs        # MCP handshake: initialize + tools/list + instructions
node scripts/integration.mjs  # live TS + Vue checks against scripts/fixture.vue
npm run dev        # esbuild --watch
```

After editing `src/`, rebuild and commit `dist/` — the committed bundle is what runs on install.

### Updating the vendored language servers

```bash
cd vendor && npm install   # bump versions in vendor/package.json first
```

### Syncing upstream cclsp

`upstream` remote points at `ktnyt/cclsp`; `origin` is this fork. `git fetch upstream` then merge
as needed. Fork-specific changes live in `src/lsp/adapters/` (vue + tsserver-bridge),
`src/utils.ts` (relpath), `src/lsp/config.ts` (env expansion), and `index.ts` (instructions).

## License

MIT — see [LICENSE](LICENSE). Fork of [cclsp](https://github.com/ktnyt/cclsp) by nano.