syntax-map-mcp 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.1.9 - 2026-05-07
+
+- 잘못된 인덱스 검색 옵션 오류 메시지에 실제 입력값을 포함하도록 개선했습니다.
+- 인덱스 검색 옵션의 `limit`, `contextBefore`, `contextAfter` 범위를 분석 계층에서도 검증하도록 했습니다.
+- 인덱스 저장 실패 시 tool failure 응답 shape를 검증하는 테스트를 추가했습니다.
+- 주요 인덱스 도구의 `structuredContent` 응답 shape를 검증하는 테스트를 추가했습니다.
+- `get_index_status` 응답에 stale 파일별 이유(`changed`, `missing`)를 반환하는 `staleReasons`를 추가했습니다.
+- SQLite 인덱스 DB에 schema version metadata를 저장하고, 호환되지 않는 기존 인덱스는 자동 재생성하도록 했습니다.
+
+## 0.1.8 - 2026-05-07
+
+- `docs/tools.md`의 도구 목록이 실제 MCP `listTools()` 응답과 일치하는지 검증하도록 했습니다.
+- MCP `listTools()` 응답의 공개 tool 이름과 주요 input schema 필드를 검증하는 테스트를 추가했습니다.
+- `release:check`가 npm 패키지를 tarball로 설치한 뒤 MCP 초기화 응답을 확인하는 smoke test를 실행하도록 했습니다.
+
 ## 0.1.7 - 2026-05-07
 
 - `release:check`가 npm 패키징 dry-run 결과의 필수 파일 포함 여부를 자동 검증하도록 했습니다.

package/dist/analysis/index.js

@@ -7,6 +7,10 @@ import { runTreeSitterQuery } from './query.js';
 import { referenceQueryForLanguage } from './references.js';
 const INDEX_DIRECTORY = '.syntax-map-mcp';
 const INDEX_FILE = 'index.sqlite';
+const INDEX_SCHEMA_VERSION = 1;
+const DEFAULT_SEARCH_LIMIT = 50;
+const MAX_SEARCH_LIMIT = 500;
+const MAX_CONTEXT_LINES = 10;
 function indexPathForWorkspace(workspace) {
     return path.join(workspace.root, INDEX_DIRECTORY, INDEX_FILE);
 }
@@ -19,15 +23,49 @@ function failure(message) {
         }
     };
 }
+async function createDatabase() {
+    const SQL = await initSqlJs();
+    return new SQL.Database();
+}
 async function openDatabase(indexPath) {
     const SQL = await initSqlJs();
     try {
         const data = await readFile(indexPath);
-        return new SQL.Database(data);
+        return { database: new SQL.Database(data), exists: true };
     }
     catch {
-        return new SQL.Database();
+        return { database: new SQL.Database(), exists: false };
+    }
+}
+function tableExists(database, tableName) {
+    const result = database.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [tableName])[0];
+    return result !== undefined && result.values.length > 0;
+}
+function storedSchemaVersion(database) {
+    if (!tableExists(database, 'metadata')) {
+        return undefined;
+    }
+    const result = database.exec('SELECT value FROM metadata WHERE key = ?', ['schema_version'])[0];
+    const value = result?.values[0]?.[0];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const version = Number(value);
+    return Number.isInteger(version) ? version : undefined;
+}
+function hasCurrentSchemaVersion(database) {
+    return storedSchemaVersion(database) === INDEX_SCHEMA_VERSION;
+}
+async function openCompatibleDatabase(indexPath) {
+    let { database, exists } = await openDatabase(indexPath);
+    let reset = false;
+    if (exists && !hasCurrentSchemaVersion(database)) {
+        database.close();
+        await rm(indexPath, { force: true });
+        database = await createDatabase();
+        reset = true;
     }
+    return { database, reset };
 }
 async function saveDatabase(database, indexPath) {
     await mkdir(path.dirname(indexPath), { recursive: true });
@@ -81,7 +119,17 @@ function initSchema(database) {
     CREATE INDEX IF NOT EXISTS symbols_name_idx ON symbols(name);
     CREATE INDEX IF NOT EXISTS symbols_kind_idx ON symbols(kind);
     CREATE INDEX IF NOT EXISTS reference_captures_name_idx ON reference_captures(name);
+
+    CREATE TABLE IF NOT EXISTS metadata (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
   `);
+    database.run(`
+      INSERT INTO metadata (key, value)
+      VALUES ('schema_version', ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value
+    `, [String(INDEX_SCHEMA_VERSION)]);
 }
 function selectStoredFiles(database) {
     const rows = database.exec('SELECT path, size, mtime_ms, parse_status FROM files');
@@ -106,29 +154,38 @@ function isCurrent(stored, current) {
         stored.size === current.size &&
         stored.mtimeMs === current.mtimeMs);
 }
-async function countStaleFiles(workspace, database) {
+async function collectStaleReasons(workspace, database) {
     const storedFiles = selectStoredFiles(database);
     const currentFiles = await workspace.listSourceFiles();
     const currentPaths = new Set(currentFiles.map(file => file.relativePath));
-    let staleFiles = 0;
+    const staleReasons = [];
     for (const file of currentFiles) {
         if (!isCurrent(storedFiles.get(file.relativePath), file)) {
-            staleFiles += 1;
+            staleReasons.push({
+                path: file.relativePath,
+                reason: 'changed'
+            });
         }
     }
     for (const storedPath of storedFiles.keys()) {
         if (!currentPaths.has(storedPath)) {
-            staleFiles += 1;
+            staleReasons.push({
+                path: storedPath,
+                reason: 'missing'
+            });
         }
     }
-    return staleFiles;
+    return staleReasons.sort((left, right) => left.path.localeCompare(right.path));
+}
+async function countStaleFiles(workspace, database) {
+    return (await collectStaleReasons(workspace, database)).length;
 }
 async function openIndexForRead(workspace, input) {
     const indexPath = indexPathForWorkspace(workspace);
-    let database = await openDatabase(indexPath);
+    let { database, reset } = await openCompatibleDatabase(indexPath);
     initSchema(database);
     const initialStaleFiles = await countStaleFiles(workspace, database);
-    if (!input.refreshIfStale || initialStaleFiles === 0) {
+    if (!reset && (!input.refreshIfStale || initialStaleFiles === 0)) {
         return {
             database,
             indexPath,
@@ -142,7 +199,7 @@ async function openIndexForRead(workspace, input) {
     if (!refreshedIndex.ok) {
         throw new Error(refreshedIndex.error.message);
     }
-    database = await openDatabase(indexPath);
+    database = (await openCompatibleDatabase(indexPath)).database;
     initSchema(database);
     const staleFiles = await countStaleFiles(workspace, database);
     return {
@@ -253,6 +310,18 @@ function sqlLikePattern(query) {
 function rowValue(row, key) {
     return row[key];
 }
+function assertIntegerRange(name, value, min, max) {
+    if (value === undefined)
+        return;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`${name} must be an integer between ${min} and ${max} (received ${String(value)})`);
+    }
+}
+function validateSearchOptions(input) {
+    assertIntegerRange('limit', input.limit, 1, MAX_SEARCH_LIMIT);
+    assertIntegerRange('contextBefore', input.contextBefore, 0, MAX_CONTEXT_LINES);
+    assertIntegerRange('contextAfter', input.contextAfter, 0, MAX_CONTEXT_LINES);
+}
 function snippetDetails(path, language, text, row, options) {
     if (text === undefined)
         return { snippet: '' };
@@ -289,7 +358,7 @@ function previewMarkdown(filePath, language, row, snippet, context) {
 }
 export async function indexWorkspace(workspace) {
     const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    const { database } = await openCompatibleDatabase(indexPath);
     try {
         initSchema(database);
         const currentFiles = await workspace.listSourceFiles();
@@ -372,6 +441,7 @@ export async function indexWorkspace(workspace) {
             indexedFiles,
             skippedFiles,
             removedFiles,
+            schemaVersion: INDEX_SCHEMA_VERSION,
             symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
             references: scalarCount(database, 'SELECT COUNT(*) FROM reference_captures')
         };
@@ -386,6 +456,7 @@ export async function indexWorkspace(workspace) {
 export async function findIndexedDefinitions(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
         const where = ['name = ?'];
@@ -394,7 +465,7 @@ export async function findIndexedDefinitions(workspace, input) {
             where.push(`kind IN (${input.kinds.map(() => '?').join(', ')})`);
             params.push(...input.kinds);
         }
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         params.push(limit);
         const statement = database.prepare(`
         SELECT
@@ -485,9 +556,10 @@ export async function findIndexedDefinitions(workspace, input) {
 export async function findIndexedReferences(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         const statement = database.prepare(`
         SELECT
           file_path,
@@ -552,6 +624,7 @@ export async function findIndexedReferences(workspace, input) {
 export async function searchSymbols(workspace, input) {
     let readState;
     try {
+        validateSearchOptions(input);
         readState = await openIndexForRead(workspace, input);
         const { database } = readState;
         const where = ['name LIKE ? ESCAPE "\\"'];
@@ -560,7 +633,7 @@ export async function searchSymbols(workspace, input) {
             where.push(`kind IN (${input.kinds.map(() => '?').join(', ')})`);
             params.push(...input.kinds);
         }
-        const limit = input.limit ?? 50;
+        const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         params.push(limit);
         const statement = database.prepare(`
         SELECT
@@ -650,17 +723,19 @@ export async function searchSymbols(workspace, input) {
 }
 export async function getIndexStatus(workspace) {
     const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    const { database } = await openCompatibleDatabase(indexPath);
     try {
         initSchema(database);
-        const staleFiles = await countStaleFiles(workspace, database);
+        const staleReasons = await collectStaleReasons(workspace, database);
         return {
             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
+            staleFiles: staleReasons.length,
+            staleReasons
         };
     }
     catch (error) {

package/docs/tools.md

@@ -2,7 +2,7 @@
 
 syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예시는 핵심 필드만 보여줍니다.
 
-## summarize_file
+## list_symbols
 
 입력:
 
@@ -19,28 +19,26 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
   "ok": true,
   "path": "src/index.ts",
   "language": "typescript",
-  "imports": ["import { createServer } from './server.js';"],
-  "exports": ["export async function main() {"],
-  "sources": {
-    "symbols": "ast",
-    "imports": "ast",
-    "exports": "ast"
-  }
+  "symbols": [
+    {
+      "name": "main",
+      "kind": "function",
+      "line": 3,
+      "column": 1
+    }
+  ]
 }
 ```
 
-## search_symbols
+## find_definition
 
 입력:
 
 ```json
 {
-  "query": "UserService",
-  "kinds": ["class"],
-  "refreshIfStale": true,
-  "contextBefore": 2,
-  "contextAfter": 2,
-  "includePreview": true
+  "name": "UserService",
+  "paths": ["src/users.ts", "src/index.ts"],
+  "kinds": ["class"]
 }
 ```
 
@@ -49,34 +47,24 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
-  "isStale": false,
-  "refreshed": true,
-  "symbols": [
+  "definitions": [
     {
       "path": "src/users.ts",
       "name": "UserService",
-      "kind": "class",
-      "snippet": "export class UserService {",
-      "context": {
-        "before": ["export type UserId = User['id'];", ""],
-        "after": ["  constructor(private readonly users: User[]) {}", ""]
-      },
-      "previewMarkdown": "src/users.ts:8\n\n```typescript\nexport type UserId = User['id'];\n\nexport class UserService {\n  constructor(private readonly users: User[]) {}\n\n```"
+      "kind": "class"
     }
   ]
 }
 ```
 
-## find_indexed_definition
+## find_references
 
 입력:
 
 ```json
 {
-  "name": "UserService",
-  "refreshIfStale": true,
-  "contextBefore": 1,
-  "contextAfter": 1
+  "name": "formatUser",
+  "paths": ["src/users.ts", "src/index.ts"]
 }
 ```
 
@@ -85,27 +73,23 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
-  "total": 1,
-  "definitions": [
+  "references": [
     {
-      "path": "src/users.ts",
-      "name": "UserService",
-      "kind": "class",
-      "snippet": "export class UserService {"
+      "path": "src/index.ts",
+      "name": "formatUser",
+      "nodeType": "identifier"
     }
   ]
 }
 ```
 
-## find_indexed_references
+## summarize_file
 
 입력:
 
 ```json
 {
-  "name": "formatUser",
-  "limit": 20,
-  "refreshIfStale": true
+  "path": "src/index.ts"
 }
 ```
 
@@ -114,12 +98,43 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
-  "references": [
+  "path": "src/index.ts",
+  "language": "typescript",
+  "imports": ["import { createServer } from './server.js';"],
+  "exports": ["export async function main() {"],
+  "sources": {
+    "symbols": "ast",
+    "imports": "ast",
+    "exports": "ast"
+  }
+}
+```
+
+## run_query
+
+입력:
+
+```json
+{
+  "path": "src/users.ts",
+  "query": "(class_declaration name: (type_identifier) @class.name)"
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "matches": [
     {
-      "path": "src/users.ts",
-      "name": "formatUser",
-      "nodeType": "identifier",
-      "snippet": "formatUser(defaultUser);"
+      "pattern": 0,
+      "captures": [
+        {
+          "name": "class.name",
+          "text": "UserService"
+        }
+      ]
     }
   ]
 }
@@ -187,6 +202,123 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 }
 ```
 
+## index_workspace
+
+입력:
+
+```json
+{}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "schemaVersion": 1,
+  "indexedFiles": 12,
+  "symbols": 84,
+  "references": 231,
+  "indexPath": "/workspace/.syntax-map-mcp/index.sqlite"
+}
+```
+
+## search_symbols
+
+입력:
+
+```json
+{
+  "query": "UserService",
+  "kinds": ["class"],
+  "refreshIfStale": true,
+  "contextBefore": 2,
+  "contextAfter": 2,
+  "includePreview": true
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "isStale": false,
+  "refreshed": true,
+  "symbols": [
+    {
+      "path": "src/users.ts",
+      "name": "UserService",
+      "kind": "class",
+      "snippet": "export class UserService {",
+      "context": {
+        "before": ["export type UserId = User['id'];", ""],
+        "after": ["  constructor(private readonly users: User[]) {}", ""]
+      },
+      "previewMarkdown": "src/users.ts:8\n\n```typescript\nexport type UserId = User['id'];\n\nexport class UserService {\n  constructor(private readonly users: User[]) {}\n\n```"
+    }
+  ]
+}
+```
+
+## find_indexed_definition
+
+입력:
+
+```json
+{
+  "name": "UserService",
+  "refreshIfStale": true,
+  "contextBefore": 1,
+  "contextAfter": 1
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "total": 1,
+  "definitions": [
+    {
+      "path": "src/users.ts",
+      "name": "UserService",
+      "kind": "class",
+      "snippet": "export class UserService {"
+    }
+  ]
+}
+```
+
+## find_indexed_references
+
+입력:
+
+```json
+{
+  "name": "formatUser",
+  "limit": 20,
+  "refreshIfStale": true
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "references": [
+    {
+      "path": "src/users.ts",
+      "name": "formatUser",
+      "nodeType": "identifier",
+      "snippet": "formatUser(defaultUser);"
+    }
+  ]
+}
+```
+
 ## get_index_status
 
 입력:
@@ -200,9 +332,38 @@ syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예
 ```json
 {
   "ok": true,
+  "schemaVersion": 1,
   "indexedFiles": 12,
   "symbols": 84,
   "references": 231,
-  "staleFiles": 0
+  "staleFiles": 2,
+  "staleReasons": [
+    {
+      "path": "src/users.ts",
+      "reason": "changed"
+    },
+    {
+      "path": "src/old.ts",
+      "reason": "missing"
+    }
+  ]
+}
+```
+
+## clear_index
+
+입력:
+
+```json
+{}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "indexPath": "/workspace/.syntax-map-mcp/index.sqlite",
+  "deleted": true
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "release:check": "npm run typecheck && npm test && npm run build && node scripts/check-package-files.mjs"
+    "release:check": "npm run typecheck && npm test && npm run build && node scripts/check-package-files.mjs && node scripts/smoke-package-install.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",