syntax-map-mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.3 - 2026-05-04
+
+- README에 `summarize_file`, 인덱스 검색 도구, `get_index_status`의 입력/응답 예시를 추가했습니다.
+- Python 파일의 `summarize_file.exports`가 top-level `__all__`을 기준으로 반환되는 동작을 문서화했습니다.
+- 배포 전 `typecheck`, 테스트, 빌드, 패키징 dry-run을 한 번에 실행하는 `release:check` 스크립트를 추가했습니다.
+- Python 파일의 top-level `__all__` 문자열 이름을 `summarize_file.exports`로 반환하도록 했습니다.
+- 인덱스 검색 도구에 `includePreview` 옵션을 추가해 `previewMarkdown`을 반환할 수 있게 했습니다.
+- `build_context`가 `indexedSearch` 입력으로 인덱스 검색 결과 기반 markdown 컨텍스트를 만들 수 있게 했습니다.
+- 패키지 버전을 `0.1.3`으로 올렸습니다.
+
+## 0.1.2 - 2026-05-04
+
+- `summarize_file`의 `exports` 추출을 AST 기반으로 변경해 문자열 내부 텍스트가 export로 잘못 반환되지 않도록 했습니다.
+- `summarize_file` 응답에 `sources`를 추가해 `symbols`, `imports`, `exports` 추출 방식이 AST 기반임을 확인할 수 있게 했습니다.
+- 인덱스 검색 도구에 `contextBefore`, `contextAfter` 옵션을 추가해 snippet 주변 라인을 함께 조회할 수 있게 했습니다.
+- 패키지 버전을 `0.1.2`로 올렸습니다.
+- `search_symbols` 결과에 현재 파일의 해당 줄 `snippet`을 추가했습니다.
+- `find_indexed_references`를 추가해 SQLite 인덱스에서 식별자 참조를 검색할 수 있게 했습니다.
+- `search_symbols`, `find_indexed_definition`, `find_indexed_references`가 `isStale`, `staleFiles`, `refreshed`를 반환하도록 했습니다.
+- 인덱스 검색 도구에 `refreshIfStale` 옵션을 추가했습니다.
+- `index_workspace`와 `get_index_status` 응답에 참조 인덱스 개수 `references`를 추가했습니다.
+
+## 0.1.1 - 2026-05-04
+
+- `find_indexed_definition`을 추가해 SQLite 인덱스에서 정확한 심볼 정의와 `snippet`을 조회할 수 있게 했습니다.
+- README의 실행 예시와 MCP 설정 예시를 `npx -y syntax-map-mcp` 기반으로 변경했습니다.
+- npm 페이지에서 GitHub 저장소가 노출되도록 `repository`, `homepage`, `bugs`, `license` 메타데이터를 추가했습니다.
+- npm publish 경고를 피하도록 `bin` 경로를 `dist/cli.js` 형식으로 정규화했습니다.
+
+## 0.1.0 - 2026-05-04
+
+- Tree-sitter 기반 MCP 서버 초기 버전을 배포했습니다.
+- JavaScript, TypeScript, TSX, Python 파일의 심볼, 정의, 참조, 요약, tree-sitter query, 컨텍스트 생성을 지원했습니다.
+- SQLite 기반 workspace 심볼 인덱스를 추가했습니다.

package/README.md

@@ -33,20 +33,209 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 - `list_symbols`: 파일 하나의 top-level 심볼 목록 반환
 - `find_definition`: 여러 파일에서 이름과 선택적 kind로 정의 검색
 - `find_references`: 여러 파일에서 식별자 참조 검색
-- `summarize_file`: 파일 언어, 라인 수, imports, exports, symbols 요약
+- `summarize_file`: 파일 언어, 라인 수, AST 기반 imports, exports, symbols 요약
 - `run_query`: 파일 하나에 tree-sitter query 실행
 - `build_context`: 여러 파일 요약을 markdown 컨텍스트로 구성
-- `index_workspace`: 지원 소스 파일을 파싱해 SQLite 심볼 인덱스 생성 또는 갱신
-- `search_symbols`: SQLite 인덱스에서 심볼 이름 검색
+- `index_workspace`: 지원 소스 파일을 파싱해 SQLite 심볼/참조 인덱스 생성 또는 갱신
+- `search_symbols`: SQLite 인덱스에서 심볼 이름 검색 및 snippet 반환
 - `find_indexed_definition`: SQLite 인덱스에서 정확한 심볼 정의 검색 및 snippet 반환
-- `get_index_status`: 인덱스 경로, 인덱싱된 파일 수, 심볼 수, stale 파일 수 반환
+- `find_indexed_references`: SQLite 인덱스에서 식별자 참조 검색 및 snippet 반환
+- `get_index_status`: 인덱스 경로, 인덱싱된 파일 수, 심볼 수, 참조 수, stale 파일 수 반환
 - `clear_index`: SQLite 인덱스 파일 삭제
 
 ## SQLite 인덱스
 
 `index_workspace`는 `workspaceRoot` 아래의 `.syntax-map-mcp/index.sqlite`에 인덱스를 저장합니다. 인덱싱 대상은 `.js`, `.jsx`, `.ts`, `.tsx`, `.py` 파일이며, `.git`, `.syntax-map-mcp`, `dist`, `node_modules` 디렉터리는 제외합니다.
 
-파일 변경 여부는 `mtimeMs`와 `size`로 판단합니다. 다시 `index_workspace`를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. `find_indexed_definition`은 인덱스에 저장된 정의 위치를 조회한 뒤 현재 파일에서 해당 줄 snippet을 읽어 반환합니다. 자동 watch 모드는 아직 포함하지 않았습니다.
+파일 변경 여부는 `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 모드는 아직 포함하지 않았습니다.
+
+`summarize_file`은 `sources` 필드로 `symbols`, `imports`, `exports`가 어떤 방식으로 추출되었는지 반환합니다.
+
+Python은 JavaScript/TypeScript처럼 명시적인 `export` 문법이 없으므로, top-level `__all__`에 선언된 문자열 이름을 `exports`로 반환합니다. `__all__`이 없으면 `exports`는 빈 배열입니다.
+
+## 도구 사용 예시
+
+### summarize_file
+
+입력:
+
+```json
+{
+  "path": "src/index.ts"
+}
+```
+
+응답 일부:
+
+```json
+{
+  "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"
+  }
+}
+```
+
+### 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);"
+    }
+  ]
+}
+```
+
+### build_context
+
+파일 경로 기반 입력:
+
+```json
+{
+  "paths": ["src/users.ts", "src/index.ts"],
+  "detail": "compact"
+}
+```
+
+인덱스 검색 기반 입력:
+
+```json
+{
+  "detail": "compact",
+  "indexedSearch": {
+    "query": "UserService",
+    "kinds": ["class"],
+    "refreshIfStale": true,
+    "contextBefore": 1,
+    "contextAfter": 1
+  }
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "markdown": "# Code Context\n\n## Indexed Search Results\n\n### UserService\n\nsrc/users.ts:8\n\n```typescript\nexport class UserService {\n```"
+}
+```
+
+### get_index_status
+
+입력:
+
+```json
+{}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "indexedFiles": 12,
+  "symbols": 84,
+  "references": 231,
+  "staleFiles": 0
+}
+```
+
+## 변경 이력
+
+버전별 변경 내용은 [CHANGELOG.md](./CHANGELOG.md)를 참고하세요.
 
 ## MCP 설정 예시
 

package/dist/analysis/context.js

@@ -1,5 +1,15 @@
+import { searchSymbols } from './index.js';
 import { summarizeFile } from './summary.js';
 export async function buildContext(workspace, input) {
+    if (input.indexedSearch) {
+        return buildIndexedSearchContext(workspace, {
+            detail: input.detail,
+            indexedSearch: input.indexedSearch
+        });
+    }
+    if (!input.paths) {
+        return failure('Either paths or indexedSearch must be provided');
+    }
     const summaries = [];
     for (const filePath of input.paths) {
         const summary = await summarizeFile(workspace, filePath);
@@ -12,8 +22,50 @@ export async function buildContext(workspace, input) {
         markdown: renderMarkdown(summaries, input.detail)
     };
 }
-function renderMarkdown(summaries, detail) {
-    return ['# Code Context', ...summaries.map(summary => renderFile(summary, detail))].join('\n\n');
+async function buildIndexedSearchContext(workspace, input) {
+    const search = await searchSymbols(workspace, {
+        ...input.indexedSearch,
+        includePreview: true
+    });
+    if (!search.ok)
+        return search;
+    const paths = [...new Set(search.symbols.map(symbol => symbol.path))];
+    const summaries = [];
+    for (const filePath of paths) {
+        const summary = await summarizeFile(workspace, filePath);
+        if (!summary.ok)
+            return summary;
+        summaries.push(summary);
+    }
+    return {
+        ok: true,
+        markdown: renderMarkdown(summaries, input.detail, renderIndexedSearchResults(search.symbols))
+    };
+}
+function renderMarkdown(summaries, detail, intro) {
+    return ['# Code Context', intro, ...summaries.map(summary => renderFile(summary, detail))]
+        .filter(Boolean)
+        .join('\n\n');
+}
+function renderIndexedSearchResults(symbols) {
+    const lines = ['## Indexed Search Results'];
+    if (symbols.length === 0) {
+        lines.push('', '- None');
+        return lines.join('\n');
+    }
+    for (const symbol of symbols) {
+        lines.push('', `### ${symbol.name}`, '', symbol.previewMarkdown ?? symbol.path);
+    }
+    return lines.join('\n');
+}
+function failure(message) {
+    return {
+        ok: false,
+        error: {
+            code: 'INDEX_ERROR',
+            message
+        }
+    };
 }
 function renderFile(summary, detail) {
     const lines = [

package/dist/analysis/index.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import initSqlJs from 'sql.js';
 import { listSymbols } from './symbols.js';
 import { parseSourceFile } from '../parser.js';
+import { runTreeSitterQuery } from './query.js';
+import { referenceQueryForLanguage } from './references.js';
 const INDEX_DIRECTORY = '.syntax-map-mcp';
 const INDEX_FILE = 'index.sqlite';
 function indexPathForWorkspace(workspace) {
@@ -63,8 +65,22 @@ function initSchema(database) {
       FOREIGN KEY(file_path) REFERENCES files(path) ON DELETE CASCADE
     );
 
+    CREATE TABLE IF NOT EXISTS reference_captures (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      language TEXT NOT NULL,
+      name TEXT NOT NULL,
+      node_type TEXT NOT NULL,
+      start_row INTEGER NOT NULL,
+      start_column INTEGER NOT NULL,
+      end_row INTEGER NOT NULL,
+      end_column INTEGER NOT NULL,
+      FOREIGN KEY(file_path) REFERENCES files(path) ON DELETE CASCADE
+    );
+
     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);
   `);
 }
 function selectStoredFiles(database) {
@@ -90,6 +106,53 @@ function isCurrent(stored, current) {
         stored.size === current.size &&
         stored.mtimeMs === current.mtimeMs);
 }
+async function countStaleFiles(workspace, database) {
+    const storedFiles = selectStoredFiles(database);
+    const currentFiles = await workspace.listSourceFiles();
+    const currentPaths = new Set(currentFiles.map(file => file.relativePath));
+    let staleFiles = 0;
+    for (const file of currentFiles) {
+        if (!isCurrent(storedFiles.get(file.relativePath), file)) {
+            staleFiles += 1;
+        }
+    }
+    for (const storedPath of storedFiles.keys()) {
+        if (!currentPaths.has(storedPath)) {
+            staleFiles += 1;
+        }
+    }
+    return staleFiles;
+}
+async function openIndexForRead(workspace, input) {
+    const indexPath = indexPathForWorkspace(workspace);
+    let database = await openDatabase(indexPath);
+    initSchema(database);
+    const initialStaleFiles = await countStaleFiles(workspace, database);
+    if (!input.refreshIfStale || initialStaleFiles === 0) {
+        return {
+            database,
+            indexPath,
+            isStale: initialStaleFiles > 0,
+            staleFiles: initialStaleFiles,
+            refreshed: false
+        };
+    }
+    database.close();
+    const refreshedIndex = await indexWorkspace(workspace);
+    if (!refreshedIndex.ok) {
+        throw new Error(refreshedIndex.error.message);
+    }
+    database = await openDatabase(indexPath);
+    initSchema(database);
+    const staleFiles = await countStaleFiles(workspace, database);
+    return {
+        database,
+        indexPath,
+        isStale: staleFiles > 0,
+        staleFiles,
+        refreshed: true
+    };
+}
 function upsertFile(database, input) {
     database.run(`
       INSERT INTO files (path, language, size, mtime_ms, parse_status, error_message, indexed_at)
@@ -145,12 +208,39 @@ function insertSymbol(database, input) {
         input.symbol.selectionRange?.end.column ?? null
     ]);
 }
+function insertReference(database, input) {
+    database.run(`
+      INSERT INTO reference_captures (
+        file_path,
+        language,
+        name,
+        node_type,
+        start_row,
+        start_column,
+        end_row,
+        end_column
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `, [
+        input.filePath,
+        input.language,
+        input.name,
+        input.nodeType,
+        input.range.start.row,
+        input.range.start.column,
+        input.range.end.row,
+        input.range.end.column
+    ]);
+}
 function deleteFile(database, filePath) {
     database.run('DELETE FROM files WHERE path = ?', [filePath]);
 }
 function deleteSymbolsForFile(database, filePath) {
     database.run('DELETE FROM symbols WHERE file_path = ?', [filePath]);
 }
+function deleteReferencesForFile(database, filePath) {
+    database.run('DELETE FROM reference_captures WHERE file_path = ?', [filePath]);
+}
 function scalarCount(database, sql) {
     const result = database.exec(sql)[0];
     if (!result)
@@ -163,8 +253,39 @@ function sqlLikePattern(query) {
 function rowValue(row, key) {
     return row[key];
 }
-function lineAt(text, row) {
-    return text.split(/\r?\n/)[row] ?? '';
+function snippetDetails(path, language, text, row, options) {
+    if (text === undefined)
+        return { snippet: '' };
+    const lines = text.split(/\r?\n/);
+    const snippet = lines[row] ?? '';
+    const beforeCount = options.contextBefore ?? 0;
+    const afterCount = options.contextAfter ?? 0;
+    const context = beforeCount === 0 && afterCount === 0
+        ? undefined
+        : {
+            before: lines.slice(Math.max(0, row - beforeCount), row),
+            after: lines.slice(row + 1, row + 1 + afterCount)
+        };
+    const details = {
+        snippet,
+    };
+    if (context)
+        details.context = context;
+    if (options.includePreview) {
+        details.previewMarkdown = previewMarkdown(path, language, row, snippet, context);
+    }
+    return details;
+}
+function previewMarkdown(filePath, language, row, snippet, context) {
+    return [
+        `${filePath}:${row + 1}`,
+        '',
+        `\`\`\`${language}`,
+        ...(context?.before ?? []),
+        snippet,
+        ...(context?.after ?? []),
+        '```'
+    ].join('\n');
 }
 export async function indexWorkspace(workspace) {
     const indexPath = indexPathForWorkspace(workspace);
@@ -197,6 +318,7 @@ export async function indexWorkspace(workspace) {
                     errorMessage: file.error.message
                 });
                 deleteSymbolsForFile(database, fileInfo.relativePath);
+                deleteReferencesForFile(database, fileInfo.relativePath);
                 indexedFiles += 1;
                 continue;
             }
@@ -209,6 +331,7 @@ export async function indexWorkspace(workspace) {
                     errorMessage: parsed.error.message
                 });
                 deleteSymbolsForFile(database, fileInfo.relativePath);
+                deleteReferencesForFile(database, fileInfo.relativePath);
                 indexedFiles += 1;
                 continue;
             }
@@ -219,6 +342,7 @@ export async function indexWorkspace(workspace) {
                 errorMessage: null
             });
             deleteSymbolsForFile(database, fileInfo.relativePath);
+            deleteReferencesForFile(database, fileInfo.relativePath);
             for (const symbol of listSymbols(parsed)) {
                 insertSymbol(database, {
                     filePath: fileInfo.relativePath,
@@ -226,6 +350,19 @@ export async function indexWorkspace(workspace) {
                     symbol
                 });
             }
+            const references = runTreeSitterQuery(parsed, referenceQueryForLanguage(parsed.language));
+            if (!references.ok) {
+                throw new Error(references.error.message);
+            }
+            for (const reference of references.captures) {
+                insertReference(database, {
+                    filePath: fileInfo.relativePath,
+                    language: parsed.language,
+                    name: reference.text,
+                    nodeType: reference.nodeType,
+                    range: reference.range
+                });
+            }
             indexedFiles += 1;
         }
         await saveDatabase(database, indexPath);
@@ -235,7 +372,8 @@ export async function indexWorkspace(workspace) {
             indexedFiles,
             skippedFiles,
             removedFiles,
-            symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols')
+            symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
+            references: scalarCount(database, 'SELECT COUNT(*) FROM reference_captures')
         };
     }
     catch (error) {
@@ -246,10 +384,10 @@ export async function indexWorkspace(workspace) {
     }
 }
 export async function findIndexedDefinitions(workspace, input) {
-    const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    let readState;
     try {
-        initSchema(database);
+        readState = await openIndexForRead(workspace, input);
+        const { database } = readState;
         const where = ['name = ?'];
         const params = [input.name];
         if (input.kinds && input.kinds.length > 0) {
@@ -320,7 +458,7 @@ export async function findIndexedDefinitions(workspace, input) {
                                 column: Number(selectionEndColumn)
                             }
                         },
-                    snippet: file.ok ? lineAt(file.text, startRow) : ''
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
                 });
             }
         }
@@ -329,7 +467,10 @@ export async function findIndexedDefinitions(workspace, input) {
         }
         return {
             ok: true,
-            indexPath,
+            indexPath: readState.indexPath,
+            isStale: readState.isStale,
+            staleFiles: readState.staleFiles,
+            refreshed: readState.refreshed,
             total: definitions.length,
             definitions
         };
@@ -338,14 +479,81 @@ export async function findIndexedDefinitions(workspace, input) {
         return failure(error instanceof Error ? error.message : String(error));
     }
     finally {
-        database.close();
+        readState?.database.close();
+    }
+}
+export async function findIndexedReferences(workspace, input) {
+    let readState;
+    try {
+        readState = await openIndexForRead(workspace, input);
+        const { database } = readState;
+        const limit = input.limit ?? 50;
+        const statement = database.prepare(`
+        SELECT
+          file_path,
+          language,
+          name,
+          node_type,
+          start_row,
+          start_column,
+          end_row,
+          end_column
+        FROM reference_captures
+        WHERE name = ?
+        ORDER BY file_path ASC, start_row ASC
+        LIMIT ?
+      `, [input.name, limit]);
+        const references = [];
+        try {
+            while (statement.step()) {
+                const row = statement.getAsObject();
+                const filePath = String(rowValue(row, 'file_path'));
+                const startRow = Number(rowValue(row, 'start_row'));
+                const file = await workspace.readSourceFile(filePath);
+                references.push({
+                    path: filePath,
+                    language: rowValue(row, 'language'),
+                    name: String(rowValue(row, 'name')),
+                    nodeType: String(rowValue(row, 'node_type')),
+                    range: {
+                        start: {
+                            row: startRow,
+                            column: Number(rowValue(row, 'start_column'))
+                        },
+                        end: {
+                            row: Number(rowValue(row, 'end_row')),
+                            column: Number(rowValue(row, 'end_column'))
+                        }
+                    },
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
+                });
+            }
+        }
+        finally {
+            statement.free();
+        }
+        return {
+            ok: true,
+            indexPath: readState.indexPath,
+            isStale: readState.isStale,
+            staleFiles: readState.staleFiles,
+            refreshed: readState.refreshed,
+            total: references.length,
+            references
+        };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        readState?.database.close();
     }
 }
 export async function searchSymbols(workspace, input) {
-    const indexPath = indexPathForWorkspace(workspace);
-    const database = await openDatabase(indexPath);
+    let readState;
     try {
-        initSchema(database);
+        readState = await openIndexForRead(workspace, input);
+        const { database } = readState;
         const where = ['name LIKE ? ESCAPE "\\"'];
         const params = [sqlLikePattern(input.query)];
         if (input.kinds && input.kinds.length > 0) {
@@ -382,15 +590,18 @@ export async function searchSymbols(workspace, input) {
                 const selectionStartColumn = rowValue(row, 'selection_start_column');
                 const selectionEndRow = rowValue(row, 'selection_end_row');
                 const selectionEndColumn = rowValue(row, 'selection_end_column');
+                const filePath = String(rowValue(row, 'file_path'));
+                const startRow = Number(rowValue(row, 'start_row'));
+                const file = await workspace.readSourceFile(filePath);
                 symbols.push({
-                    path: String(rowValue(row, 'file_path')),
+                    path: filePath,
                     language: rowValue(row, 'language'),
                     name: String(rowValue(row, 'name')),
                     kind: rowValue(row, 'kind'),
                     parentName: rowValue(row, 'parent_name') === null ? undefined : String(rowValue(row, 'parent_name')),
                     range: {
                         start: {
-                            row: Number(rowValue(row, 'start_row')),
+                            row: startRow,
                             column: Number(rowValue(row, 'start_column'))
                         },
                         end: {
@@ -412,7 +623,8 @@ export async function searchSymbols(workspace, input) {
                                 row: Number(selectionEndRow),
                                 column: Number(selectionEndColumn)
                             }
-                        }
+                        },
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
                 });
             }
         }
@@ -421,7 +633,10 @@ export async function searchSymbols(workspace, input) {
         }
         return {
             ok: true,
-            indexPath,
+            indexPath: readState.indexPath,
+            isStale: readState.isStale,
+            staleFiles: readState.staleFiles,
+            refreshed: readState.refreshed,
             total: symbols.length,
             symbols
         };
@@ -430,7 +645,7 @@ export async function searchSymbols(workspace, input) {
         return failure(error instanceof Error ? error.message : String(error));
     }
     finally {
-        database.close();
+        readState?.database.close();
     }
 }
 export async function getIndexStatus(workspace) {
@@ -438,24 +653,13 @@ export async function getIndexStatus(workspace) {
     const database = await openDatabase(indexPath);
     try {
         initSchema(database);
-        const storedFiles = selectStoredFiles(database);
-        const currentFiles = await workspace.listSourceFiles();
-        let staleFiles = 0;
-        for (const file of currentFiles) {
-            if (!isCurrent(storedFiles.get(file.relativePath), file)) {
-                staleFiles += 1;
-            }
-        }
-        for (const storedPath of storedFiles.keys()) {
-            if (!currentFiles.some(file => file.relativePath === storedPath)) {
-                staleFiles += 1;
-            }
-        }
+        const staleFiles = await countStaleFiles(workspace, database);
         return {
             ok: true,
             indexPath,
             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
         };
     }

package/dist/analysis/references.js

@@ -24,7 +24,7 @@ export async function findReferences(workspace, input) {
     }
     return { ok: true, references };
 }
-function referenceQueryForLanguage(language) {
+export function referenceQueryForLanguage(language) {
     switch (language) {
         case 'typescript':
         case 'tsx':

package/dist/analysis/summary.js

@@ -13,8 +13,13 @@ export async function summarizeFile(workspace, filePath) {
         language: parsed.language,
         lineCount: countLines(file.text),
         symbols: listSymbols(parsed),
-        imports: findImports(file.text),
-        exports: findExports(file.text)
+        imports: findImports(parsed),
+        exports: findExports(parsed),
+        sources: {
+            symbols: 'ast',
+            imports: 'ast',
+            exports: 'ast'
+        }
     };
 }
 function countLines(text) {
@@ -22,15 +27,58 @@ function countLines(text) {
         return 0;
     return text.replace(/\r\n|\r|\n$/, '').split(/\r\n|\r|\n/).length;
 }
-function findImports(text) {
-    return trimmedLines(text).filter(line => line.startsWith('import ') || line.startsWith('from '));
+function findImports(parsed) {
+    return parsed.tree.rootNode.namedChildren
+        .filter(node => isImportNode(parsed.language, node.type))
+        .map(node => firstLine(node.text));
 }
-function findExports(text) {
-    return trimmedLines(text).filter(line => line.startsWith('export '));
+function isImportNode(language, nodeType) {
+    switch (language) {
+        case 'python':
+            return nodeType === 'import_statement' || nodeType === 'import_from_statement';
+        case 'javascript':
+        case 'typescript':
+        case 'tsx':
+            return nodeType === 'import_statement';
+    }
 }
-function trimmedLines(text) {
-    return text
-        .split(/\r\n|\r|\n/)
-        .map(line => line.trim())
+function findExports(parsed) {
+    if (parsed.language === 'python') {
+        return findPythonAllExports(parsed);
+    }
+    return parsed.tree.rootNode.namedChildren
+        .filter(node => isExportNode(parsed.language, node.type))
+        .map(node => firstLine(node.text));
+}
+function isExportNode(language, nodeType) {
+    switch (language) {
+        case 'javascript':
+        case 'typescript':
+        case 'tsx':
+            return nodeType === 'export_statement';
+        case 'python':
+            return false;
+    }
+}
+function findPythonAllExports(parsed) {
+    return parsed.tree.rootNode.namedChildren.flatMap(node => pythonAllExportNames(node));
+}
+function pythonAllExportNames(node) {
+    if (node.type !== 'expression_statement')
+        return [];
+    const assignment = node.namedChildren[0];
+    if (!assignment || assignment.type !== 'assignment')
+        return [];
+    const [target, value] = assignment.namedChildren;
+    if (!target || !value || target.type !== 'identifier' || target.text !== '__all__')
+        return [];
+    if (value.type !== 'list' && value.type !== 'tuple')
+        return [];
+    return value.namedChildren
+        .filter(child => child.type === 'string')
+        .map(child => child.namedChildren.find(part => part.type === 'string_content')?.text ?? '')
         .filter(Boolean);
 }
+function firstLine(text) {
+    return text.split(/\r\n|\r|\n/, 1)[0].trim();
+}

package/dist/tools.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { buildContext as buildContextAnalysis } from './analysis/context.js';
 import { findDefinitions } from './analysis/definitions.js';
-import { clearIndex as clearWorkspaceIndex, findIndexedDefinitions, getIndexStatus as getWorkspaceIndexStatus, indexWorkspace as indexWorkspaceAnalysis, searchSymbols as searchIndexedSymbols } from './analysis/index.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';
 import { summarizeFile as summarizeFileAnalysis } from './analysis/summary.js';
@@ -10,6 +10,7 @@ import { parseSourceFile } from './parser.js';
 import { jsonResult, toolFailure } from './result.js';
 const symbolKindSchema = z.enum(['function', 'method', 'class', 'variable', 'interface', 'type']);
 const detailSchema = z.enum(['compact', 'full']);
+const contextLineCountSchema = z.number().int().min(0).max(10);
 export function createToolHandlers(workspace) {
     return {
         async listSymbols(input) {
@@ -80,6 +81,12 @@ export function createToolHandlers(workspace) {
                 return toolFailure(result.error.code, result.error.message);
             return jsonResult(result);
         },
+        async findIndexedReferences(input) {
+            const result = await findIndexedReferences(workspace, input);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
         async getIndexStatus(_input) {
             const result = await getWorkspaceIndexStatus(workspace);
             if (!result.ok)
@@ -139,8 +146,18 @@ export function registerTools(server, workspace) {
         title: 'Build context',
         description: 'Build markdown context for supported source files.',
         inputSchema: {
-            paths: z.array(z.string()),
-            detail: detailSchema
+            paths: z.array(z.string()).optional(),
+            detail: detailSchema,
+            indexedSearch: z
+                .object({
+                query: z.string(),
+                kinds: z.array(symbolKindSchema).optional(),
+                limit: z.number().int().positive().max(500).optional(),
+                refreshIfStale: z.boolean().optional(),
+                contextBefore: contextLineCountSchema.optional(),
+                contextAfter: contextLineCountSchema.optional()
+            })
+                .optional()
         }
     }, handlers.buildContext);
     server.registerTool('index_workspace', {
@@ -154,7 +171,11 @@ export function registerTools(server, workspace) {
         inputSchema: {
             query: z.string(),
             kinds: z.array(symbolKindSchema).optional(),
-            limit: z.number().int().positive().max(500).optional()
+            limit: z.number().int().positive().max(500).optional(),
+            refreshIfStale: z.boolean().optional(),
+            contextBefore: contextLineCountSchema.optional(),
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
         }
     }, handlers.searchSymbols);
     server.registerTool('find_indexed_definition', {
@@ -163,9 +184,25 @@ export function registerTools(server, workspace) {
         inputSchema: {
             name: z.string(),
             kinds: z.array(symbolKindSchema).optional(),
-            limit: z.number().int().positive().max(500).optional()
+            limit: z.number().int().positive().max(500).optional(),
+            refreshIfStale: z.boolean().optional(),
+            contextBefore: contextLineCountSchema.optional(),
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
         }
     }, handlers.findIndexedDefinition);
+    server.registerTool('find_indexed_references', {
+        title: 'Find indexed references',
+        description: 'Find identifier references from the SQLite workspace index with snippets.',
+        inputSchema: {
+            name: z.string(),
+            limit: z.number().int().positive().max(500).optional(),
+            refreshIfStale: z.boolean().optional(),
+            contextBefore: contextLineCountSchema.optional(),
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
+        }
+    }, handlers.findIndexedReferences);
     server.registerTool('get_index_status', {
         title: 'Get index status',
         description: 'Return SQLite index path, indexed file count, symbol count, and stale file count.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -28,7 +29,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "release:check": "npm run typecheck && npm test && npm run build && npm pack --dry-run"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",