syntax-map-mcp 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 1.2.1 - 2026-05-07
+
+- 큰 TypeScript 파일이 workspace 기본 `paths` 조회에 포함될 때 LSP definition, references, hover, workspace symbols, completion, signature help가 `Invalid argument`로 실패하던 문제를 수정했습니다.
+- `lsp_signature_help`가 TypeScript 제네릭 함수의 파라미터를 추출하지 못하던 문제를 수정했습니다.
+- `get_index_status`가 기본 응답에서 `staleReasons` 전체 배열을 생략하고, `includeStaleReasons: true`일 때만 상세 사유를 반환하도록 변경했습니다.
+
+## 1.2.0 - 2026-05-07
+
+- MCP 서버 실행 중 지원 소스 파일 변경을 감지해 SQLite 인덱스를 자동 갱신하는 watcher를 추가했습니다.
+- `lsp_diagnostics` 도구를 추가해 tree-sitter parse error 기반의 가벼운 문법 진단을 LSP Diagnostic 형태로 반환하도록 했습니다.
+- diagnostics 분석 계층에 provider 인터페이스를 추가해 이후 언어별 LSP 서버 진단 결과를 결합할 수 있게 했습니다.
+
 ## 1.1.0 - 2026-05-07
 
 - Rust `.rs` 파일 파싱을 지원하고, `get_ast_tree`와 LSP document symbols, definition, references, hover, workspace symbols, completion, signature help에서 Rust 심볼을 처리하도록 했습니다.

package/README.md

@@ -37,6 +37,7 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 - `run_query`: 파일 하나에 tree-sitter query 실행
 - `get_ast_tree`: 파일 하나의 tree-sitter AST를 depth 제한 JSON 트리로 반환
 - `lsp_document_symbols`: 파일 하나의 심볼을 LSP DocumentSymbol 형태로 반환
+- `lsp_diagnostics`: 파일 하나의 tree-sitter parse error를 LSP Diagnostic 형태로 반환
 - `lsp_definition`: 파일의 LSP 위치에 있는 식별자의 정의 위치를 반환
 - `lsp_references`: 파일의 LSP 위치에 있는 식별자의 참조 위치를 반환
 - `lsp_hover`: 파일의 LSP 위치에 있는 식별자의 hover markdown을 반환
@@ -51,11 +52,13 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 - `get_index_status`: 인덱스 경로, 인덱싱된 파일 수, 심볼 수, 참조 수, stale 파일 수 반환
 - `clear_index`: SQLite 인덱스 파일 삭제
 
+`lsp_definition`, `lsp_references`, `lsp_hover`, `lsp_workspace_symbols`, `lsp_completion`, `lsp_signature_help`의 `paths` 입력은 선택 사항입니다. 생략하면 `workspaceRoot` 아래의 지원 소스 파일 전체를 대상으로 조회합니다.
+
 ## SQLite 인덱스
 
 `index_workspace`는 `workspaceRoot` 아래의 `.syntax-map-mcp/index.sqlite`에 인덱스를 저장합니다. 인덱싱 대상은 `.js`, `.jsx`, `.ts`, `.tsx`, `.py`, `.rs` 파일이며, `.git`, `.syntax-map-mcp`, `dist`, `node_modules` 디렉터리와 `workspaceRoot` 아래의 `.gitignore` 패턴에 매칭되는 파일은 제외합니다. 하위 디렉터리의 `.gitignore`는 해당 디렉터리 기준으로 적용합니다.
 
-파일 변경 여부는 `mtimeMs`와 `size`로 판단합니다. 다시 `index_workspace`를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. `search_symbols`, `find_indexed_definition`, `find_indexed_references`는 `isStale`, `staleFiles`, `refreshed`를 반환해 검색 결과가 최신 인덱스 기반인지 알려줍니다. 세 도구에 `refreshIfStale: true`를 전달하면 stale 파일이 있을 때 먼저 인덱스를 갱신한 뒤 검색합니다. 인덱스 검색 도구는 인덱스에 저장된 위치를 조회한 뒤 현재 파일에서 해당 줄 snippet을 읽어 반환합니다. `contextBefore`, `contextAfter`를 0-10 사이 정수로 전달하면 snippet 주변 라인도 함께 반환합니다. `includePreview: true`를 전달하면 `path:line` 헤더와 코드블록으로 구성된 `previewMarkdown`도 함께 반환합니다. 자동 watch 모드는 아직 포함하지 않았습니다.
+파일 변경 여부는 `mtimeMs`와 `size`로 판단합니다. 다시 `index_workspace`를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. MCP 서버를 실행하면 지원 소스 파일 변경을 감지하는 watcher가 함께 시작되어 SQLite 인덱스를 자동 갱신합니다. `.syntax-map-mcp`, `.git`, `dist`, `node_modules`와 지원하지 않는 확장자 변경은 watcher refresh 대상에서 제외합니다. `get_index_status`는 기본적으로 stale 파일 개수만 반환하고, 상세 목록이 필요하면 `includeStaleReasons: true`를 전달합니다. `search_symbols`, `find_indexed_definition`, `find_indexed_references`는 `isStale`, `staleFiles`, `refreshed`를 반환해 검색 결과가 최신 인덱스 기반인지 알려줍니다. 세 도구에 `refreshIfStale: true`를 전달하면 stale 파일이 있을 때 먼저 인덱스를 갱신한 뒤 검색합니다. 인덱스 검색 도구는 인덱스에 저장된 위치를 조회한 뒤 현재 파일에서 해당 줄 snippet을 읽어 반환합니다. `contextBefore`, `contextAfter`를 0-10 사이 정수로 전달하면 snippet 주변 라인도 함께 반환합니다. `includePreview: true`를 전달하면 `path:line` 헤더와 코드블록으로 구성된 `previewMarkdown`도 함께 반환합니다.
 
 `summarize_file`은 `sources` 필드로 `symbols`, `imports`, `exports`가 어떤 방식으로 추출되었는지 반환합니다.
 

package/dist/analysis/diagnostics.js

@@ -0,0 +1,73 @@
+import { parseSourceFile } from '../parser.js';
+export const treeSitterDiagnosticProvider = {
+    name: 'tree-sitter',
+    getDiagnostics(context) {
+        return collectTreeSitterDiagnostics(context.tree.rootNode);
+    }
+};
+const defaultDiagnosticProviders = [treeSitterDiagnosticProvider];
+export async function getDiagnostics(workspace, input, providers = defaultDiagnosticProviders) {
+    const file = await workspace.readSourceFile(input.path);
+    if (!file.ok)
+        return file;
+    const parsed = parseSourceFile(file);
+    /* v8 ignore next -- parser failures are covered by parser tests. */
+    if (!parsed.ok)
+        return parsed;
+    const context = diagnosticContext(parsed);
+    const diagnostics = (await Promise.all(providers.map(provider => Promise.resolve(provider.getDiagnostics(context))))).flat();
+    return {
+        ok: true,
+        path: file.relativePath,
+        language: parsed.language,
+        diagnostics
+    };
+}
+function diagnosticContext(parsed) {
+    return {
+        path: parsed.file.relativePath,
+        language: parsed.language,
+        text: parsed.file.text,
+        tree: parsed.tree
+    };
+}
+function collectTreeSitterDiagnostics(root) {
+    if (!root.hasError)
+        return [];
+    const diagnostics = [];
+    collectErrorNodes(root, diagnostics);
+    return diagnostics;
+}
+function collectErrorNodes(node, diagnostics) {
+    if (node.isError || node.isMissing) {
+        diagnostics.push({
+            range: lspRange(rangeForNode(node)),
+            severity: 1,
+            source: 'tree-sitter',
+            message: node.isMissing ? `Syntax error: missing ${node.type}` : 'Syntax error'
+        });
+    }
+    if (!node.hasError)
+        return;
+    for (const child of node.children) {
+        collectErrorNodes(child, diagnostics);
+    }
+}
+function lspRange(range) {
+    return {
+        start: {
+            line: range.start.row,
+            character: range.start.column
+        },
+        end: {
+            line: range.end.row,
+            character: range.end.column
+        }
+    };
+}
+function rangeForNode(node) {
+    return {
+        start: node.startPosition,
+        end: node.endPosition
+    };
+}

package/dist/analysis/index-watcher.js

@@ -0,0 +1,80 @@
+import { watch } from 'node:fs';
+import path from 'node:path';
+import { indexWorkspace } from './index.js';
+const DEFAULT_DEBOUNCE_MS = 250;
+const SUPPORTED_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.py', '.rs']);
+const EXCLUDED_DIRECTORIES = new Set(['.git', '.syntax-map-mcp', 'dist', 'node_modules']);
+/* v8 ignore next -- default fs.watch wiring is exercised by CLI/manual MCP runs. */
+const defaultWatchFactory = (root, options, listener) => watch(root, options, listener);
+export function startIndexWatcher(workspace, options = {}) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const refreshIndex = options.indexWorkspace ?? indexWorkspace;
+    const setTimer = options.setTimer ?? setTimeout;
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    let stopped = false;
+    let timer;
+    let refreshChain = Promise.resolve();
+    function runRefresh() {
+        refreshChain = refreshChain
+            .then(async () => {
+            if (stopped)
+                return;
+            const result = await refreshIndex(workspace);
+            if (!result.ok) {
+                throw new Error(result.error.message);
+            }
+        })
+            .catch(error => {
+            options.onError?.(error instanceof Error ? error : new Error(String(error)));
+        });
+        return refreshChain;
+    }
+    function scheduleRefresh(filename) {
+        if (stopped || !isRelevantWatchPath(filename))
+            return;
+        if (timer) {
+            clearTimer(timer);
+        }
+        timer = setTimer(() => {
+            timer = undefined;
+            void runRefresh();
+        }, debounceMs);
+        timer.unref?.();
+    }
+    /* v8 ignore next -- tests inject watchFactory to avoid platform-specific fs.watch behavior. */
+    const watchFactory = options.watchFactory ??
+        /* v8 ignore next -- default fs.watch wiring is exercised by CLI/manual MCP runs. */
+        defaultWatchFactory;
+    const watcher = watchFactory(workspace.root, { recursive: true }, (_eventType, filename) => {
+        scheduleRefresh(filename);
+    });
+    watcher.unref?.();
+    return {
+        ready: runRefresh(),
+        async flush() {
+            if (timer) {
+                clearTimer(timer);
+                timer = undefined;
+                await runRefresh();
+            }
+            await refreshChain;
+        },
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimer(timer);
+                timer = undefined;
+            }
+            watcher.close();
+        }
+    };
+}
+function isRelevantWatchPath(filename) {
+    if (filename === null)
+        return true;
+    const normalized = filename.toString().split(path.sep).join('/');
+    const parts = normalized.split('/');
+    if (parts.some(part => EXCLUDED_DIRECTORIES.has(part)))
+        return false;
+    return SUPPORTED_EXTENSIONS.has(path.extname(normalized));
+}

package/dist/analysis/index.js

@@ -747,22 +747,25 @@ export async function searchSymbols(workspace, input) {
         readState?.database.close();
     }
 }
-export async function getIndexStatus(workspace) {
+export async function getIndexStatus(workspace, input = {}) {
     const indexPath = indexPathForWorkspace(workspace);
     const { database } = await openCompatibleDatabase(indexPath);
     try {
         initSchema(database);
         const staleReasons = await collectStaleReasons(workspace, database);
-        return {
+        const result = {
             ok: true,
             indexPath,
             schemaVersion: INDEX_SCHEMA_VERSION,
             indexedFiles: scalarCount(database, 'SELECT COUNT(*) FROM files WHERE parse_status = "ok"'),
             symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
             references: scalarCount(database, 'SELECT COUNT(*) FROM reference_captures'),
-            staleFiles: staleReasons.length,
-            staleReasons
+            staleFiles: staleReasons.length
         };
+        if (input.includeStaleReasons === true) {
+            result.staleReasons = staleReasons;
+        }
+        return result;
         /* v8 ignore next -- status read failures require a corrupted sqlite runtime path. */
     }
     catch (error) {

package/dist/analysis/lsp.js

@@ -120,8 +120,8 @@ function splitParameters(parameters) {
 }
 function signatureFromSnippet(name, snippet) {
     const firstLine = snippet.split(/\r?\n/)[0].trim();
-    const functionMatch = firstLine.match(/^(?:export\s+)?(?:async\s+)?function\s+[A-Za-z_$][A-Za-z0-9_$]*\s*\(([^)]*)\)\s*([^{:]*(?::\s*[^{]+)?)[{:]?/);
-    const methodMatch = firstLine.match(/^(?:public\s+|private\s+|protected\s+|static\s+|async\s+)*[A-Za-z_$][A-Za-z0-9_$]*\s*\(([^)]*)\)\s*([^{:]*(?::\s*[^{]+)?)[{:]?/);
+    const functionMatch = firstLine.match(/^(?:export\s+)?(?:async\s+)?function\s+[A-Za-z_$][A-Za-z0-9_$]*\s*(?:<[^>]+>)?\s*\(([^)]*)\)\s*([^{:]*(?::\s*[^{]+)?)[{:]?/);
+    const methodMatch = firstLine.match(/^(?:public\s+|private\s+|protected\s+|static\s+|async\s+)*[A-Za-z_$][A-Za-z0-9_$]*\s*(?:<[^>]+>)?\s*\(([^)]*)\)\s*([^{:]*(?::\s*[^{]+)?)[{:]?/);
     const pythonMatch = firstLine.match(/^def\s+[A-Za-z_$][A-Za-z0-9_$]*\s*\(([^)]*)\)\s*([^:]*)/);
     const rustMatch = firstLine.match(/^(?:pub\s+)?(?:async\s+)?fn\s+[A-Za-z_$][A-Za-z0-9_$]*\s*\(([^)]*)\)\s*([^{]*)/);
     const match = functionMatch ?? pythonMatch ?? rustMatch ?? methodMatch;

package/dist/parser.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import Parser from 'tree-sitter';
 import { languageForName } from './languages.js';
+const PARSE_CHUNK_SIZE = 4096;
 export function detectLanguage(filePath) {
     const extension = path.extname(filePath);
     switch (extension) {
@@ -32,7 +33,7 @@ export function parseSourceFile(file, resolveLanguage = languageForName) {
     try {
         const parser = new Parser();
         parser.setLanguage(resolveLanguage(detected.language));
-        const tree = parser.parse(file.text);
+        const tree = parser.parse(offset => file.text.slice(offset, offset + PARSE_CHUNK_SIZE));
         return {
             ok: true,
             file,

package/dist/server.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { startIndexWatcher } from './analysis/index-watcher.js';
 import { registerTools } from './tools.js';
 import { createWorkspace } from './workspace.js';
 function defaultPackageJsonPath() {
@@ -18,17 +19,35 @@ export async function createServerInfo(packageJsonPath = defaultPackageJsonPath(
         version: packageJson.version
     };
 }
-export async function createServer(options) {
+export async function createServer(options, dependencies = {}) {
     const workspace = await createWorkspace(options.workspaceRoot);
     const server = new McpServer(await createServerInfo(), {
         instructions: 'Analyze JavaScript, TypeScript, Python, and Rust source files under the configured workspaceRoot only.'
     });
     registerTools(server, workspace);
+    if (options.autoIndex === true) {
+        attachIndexWatcher(server, (dependencies.startIndexWatcher ?? startIndexWatcher)(workspace, {
+            debounceMs: options.indexDebounceMs
+        }));
+    }
     return server;
 }
 export async function runServer(options, dependencies = {}) {
     /* v8 ignore next 2 -- default CLI wiring is exercised by the package smoke test in a child process. */
-    const server = await (dependencies.createServer ?? createServer)(options);
-    const transport = (dependencies.createTransport ?? (() => new StdioServerTransport()))();
+    const server = await (dependencies.createServer ?? createServer)({
+        ...options,
+        autoIndex: options.autoIndex ?? true
+    });
+    const createTransport = dependencies.createTransport ??
+        /* v8 ignore next -- default stdio transport wiring is exercised by the package smoke test. */
+        (() => new StdioServerTransport());
+    const transport = createTransport();
     await server.connect(transport);
 }
+function attachIndexWatcher(server, watcher) {
+    const closeServer = server.close.bind(server);
+    server.close = async () => {
+        watcher.stop();
+        await closeServer();
+    };
+}

package/dist/tools.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { getAstTree as getAstTreeAnalysis } from './analysis/ast-tree.js';
 import { buildContext as buildContextAnalysis } from './analysis/context.js';
 import { findDefinitions } from './analysis/definitions.js';
+import { getDiagnostics as getLspDiagnostics } from './analysis/diagnostics.js';
 import { clearIndex as clearWorkspaceIndex, findIndexedDefinitions, findIndexedReferences, getIndexStatus as getWorkspaceIndexStatus, indexWorkspace as indexWorkspaceAnalysis, searchSymbols as searchIndexedSymbols } from './analysis/index.js';
 import { runTreeSitterQuery } from './analysis/query.js';
 import { findReferences as findReferencesAnalysis } from './analysis/references.js';
@@ -75,6 +76,12 @@ export function createToolHandlers(workspace) {
                 return toolFailure(result.error.code, result.error.message);
             return jsonResult(result);
         },
+        async lspDiagnostics(input) {
+            const result = await getLspDiagnostics(workspace, input);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
         async lspDefinition(input) {
             const result = await getLspDefinition(workspace, input);
             if (!result.ok)
@@ -141,8 +148,8 @@ export function createToolHandlers(workspace) {
                 return toolFailure(result.error.code, result.error.message);
             return jsonResult(result);
         },
-        async getIndexStatus(_input) {
-            const result = await getWorkspaceIndexStatus(workspace);
+        async getIndexStatus(input) {
+            const result = await getWorkspaceIndexStatus(workspace, input);
             /* v8 ignore next -- getIndexStatus read failures are defensive and covered at index layer. */
             if (!result.ok)
                 return toolFailure(result.error.code, result.error.message);
@@ -214,6 +221,13 @@ export function registerTools(server, workspace) {
             path: z.string()
         }
     }, handlers.lspDocumentSymbols);
+    server.registerTool('lsp_diagnostics', {
+        title: 'LSP diagnostics',
+        description: 'Return lightweight syntax diagnostics from tree-sitter parse errors.',
+        inputSchema: {
+            path: z.string()
+        }
+    }, handlers.lspDiagnostics);
     server.registerTool('lsp_definition', {
         title: 'LSP definition',
         description: 'Return definition locations for the identifier at a zero-based LSP position.',
@@ -351,7 +365,9 @@ export function registerTools(server, workspace) {
     server.registerTool('get_index_status', {
         title: 'Get index status',
         description: 'Return SQLite index path, indexed file count, symbol count, and stale file count.',
-        inputSchema: {}
+        inputSchema: {
+            includeStaleReasons: z.boolean().optional()
+        }
     }, handlers.getIndexStatus);
     server.registerTool('clear_index', {
         title: 'Clear index',

package/docs/tools.md

@@ -215,6 +215,37 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 }
 ```
 
+## lsp_diagnostics
+
+입력:
+
+```json
+{
+  "path": "src/users.ts"
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "path": "src/users.ts",
+  "language": "typescript",
+  "diagnostics": [
+    {
+      "range": {
+        "start": { "line": 10, "character": 4 },
+        "end": { "line": 10, "character": 12 }
+      },
+      "severity": 1,
+      "source": "tree-sitter",
+      "message": "Syntax error"
+    }
+  ]
+}
+```
+
 ## lsp_definition
 
 입력:
@@ -473,7 +504,9 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 입력:
 
 ```json
-{}
+{
+  "includeStaleReasons": true
+}
 ```
 
 응답 일부:
@@ -616,6 +649,8 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 }
 ```
 
+`includeStaleReasons`를 생략하거나 `false`로 전달하면 응답에는 `staleFiles` 개수만 포함됩니다.
+
 ## clear_index
 
 입력:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",