syntax-map-mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.1.4 - 2026-05-04
+
+- `build_context` 인덱스 검색 metadata에 `summarizedFiles`와 `omittedFiles`를 추가했습니다.
+- `build_context`에 `maxFiles` 옵션을 추가해 인덱스 검색 기반 파일 요약 수를 제한할 수 있게 했습니다.
+- 인덱스 기반 심볼/정의/참조 검색 결과를 소스 위치 기준으로 안정 정렬하도록 했습니다.
+- `build_context`의 인덱스 검색 응답에 `metadata`를 추가해 stale 상태와 refresh 여부를 확인할 수 있게 했습니다.
+- `build_context.indexedSearch`가 symbols 모드와 references 모드를 모두 지원하도록 확장했습니다.
+- README의 도구별 입력/응답 예시를 `docs/tools.md`로 분리했습니다.
+- npm 패키지에 `docs/tools.md`를 포함해 README의 도구 레퍼런스 링크가 패키지 안에서도 유지되도록 했습니다.
+
+## 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로 잘못 반환되지 않도록 했습니다.

package/README.md

@@ -47,10 +47,16 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 
 `index_workspace`는 `workspaceRoot` 아래의 `.syntax-map-mcp/index.sqlite`에 인덱스를 저장합니다. 인덱싱 대상은 `.js`, `.jsx`, `.ts`, `.tsx`, `.py` 파일이며, `.git`, `.syntax-map-mcp`, `dist`, `node_modules` 디렉터리는 제외합니다.
 
-파일 변경 여부는 `mtimeMs`와 `size`로 판단합니다. 다시 `index_workspace`를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. `search_symbols`, `find_indexed_definition`, `find_indexed_references`는 `isStale`, `staleFiles`, `refreshed`를 반환해 검색 결과가 최신 인덱스 기반인지 알려줍니다. 세 도구에 `refreshIfStale: true`를 전달하면 stale 파일이 있을 때 먼저 인덱스를 갱신한 뒤 검색합니다. 인덱스 검색 도구는 인덱스에 저장된 위치를 조회한 뒤 현재 파일에서 해당 줄 snippet을 읽어 반환합니다. `contextBefore`, `contextAfter`를 0-10 사이 정수로 전달하면 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`는 빈 배열입니다.
+
+## 도구 레퍼런스
+
+도구별 입력과 응답 예시는 [docs/tools.md](./docs/tools.md)를 참고하세요.
+
 ## 변경 이력
 
 버전별 변경 내용은 [CHANGELOG.md](./CHANGELOG.md)를 참고하세요.

package/dist/analysis/context.js

@@ -1,5 +1,16 @@
+import { findIndexedReferences, searchSymbols } from './index.js';
 import { summarizeFile } from './summary.js';
 export async function buildContext(workspace, input) {
+    if (input.indexedSearch) {
+        return buildIndexedSearchContext(workspace, {
+            detail: input.detail,
+            maxFiles: input.maxFiles,
+            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 +23,101 @@ 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 { detail, indexedSearch } = input;
+    if (indexedSearch.mode === 'references') {
+        return buildIndexedReferenceContext(workspace, { detail, maxFiles: input.maxFiles, indexedSearch });
+    }
+    const search = await searchSymbols(workspace, {
+        ...indexedSearch,
+        includePreview: true
+    });
+    if (!search.ok)
+        return search;
+    const allPaths = [...new Set(search.symbols.map(symbol => symbol.path))];
+    const paths = limitPaths(allPaths, input.maxFiles);
+    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, detail, renderIndexedSearchResults(search.symbols)),
+        metadata: {
+            indexedSearchMode: 'symbols',
+            indexPath: search.indexPath,
+            isStale: search.isStale,
+            staleFiles: search.staleFiles,
+            refreshed: search.refreshed,
+            total: search.total,
+            summarizedFiles: paths.length,
+            omittedFiles: Math.max(0, allPaths.length - paths.length)
+        }
+    };
+}
+async function buildIndexedReferenceContext(workspace, input) {
+    const search = await findIndexedReferences(workspace, {
+        ...input.indexedSearch,
+        includePreview: true
+    });
+    if (!search.ok)
+        return search;
+    const allPaths = [...new Set(search.references.map(reference => reference.path))];
+    const paths = limitPaths(allPaths, input.maxFiles);
+    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.references)),
+        metadata: {
+            indexedSearchMode: 'references',
+            indexPath: search.indexPath,
+            isStale: search.isStale,
+            staleFiles: search.staleFiles,
+            refreshed: search.refreshed,
+            total: search.total,
+            summarizedFiles: paths.length,
+            omittedFiles: Math.max(0, allPaths.length - paths.length)
+        }
+    };
+}
+function renderMarkdown(summaries, detail, intro) {
+    return ['# Code Context', intro, ...summaries.map(summary => renderFile(summary, detail))]
+        .filter(Boolean)
+        .join('\n\n');
+}
+function limitPaths(paths, maxFiles) {
+    if (maxFiles === undefined)
+        return paths;
+    return paths.slice(0, maxFiles);
+}
+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

@@ -253,23 +253,39 @@ function sqlLikePattern(query) {
 function rowValue(row, key) {
     return row[key];
 }
-function snippetDetails(text, row, options) {
+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;
-    if (beforeCount === 0 && afterCount === 0) {
-        return { snippet };
-    }
-    return {
-        snippet,
-        context: {
+    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);
@@ -397,7 +413,7 @@ export async function findIndexedDefinitions(workspace, input) {
           selection_end_column
         FROM symbols
         WHERE ${where.join(' AND ')}
-        ORDER BY file_path ASC, start_row ASC, name ASC
+        ORDER BY file_path ASC, start_row ASC, start_column ASC, name ASC
         LIMIT ?
       `, params);
         const definitions = [];
@@ -442,7 +458,7 @@ export async function findIndexedDefinitions(workspace, input) {
                                 column: Number(selectionEndColumn)
                             }
                         },
-                    ...snippetDetails(file.ok ? file.text : undefined, startRow, input)
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
                 });
             }
         }
@@ -484,7 +500,7 @@ export async function findIndexedReferences(workspace, input) {
           end_column
         FROM reference_captures
         WHERE name = ?
-        ORDER BY file_path ASC, start_row ASC
+        ORDER BY file_path ASC, start_row ASC, start_column ASC
         LIMIT ?
       `, [input.name, limit]);
         const references = [];
@@ -509,7 +525,7 @@ export async function findIndexedReferences(workspace, input) {
                             column: Number(rowValue(row, 'end_column'))
                         }
                     },
-                    ...snippetDetails(file.ok ? file.text : undefined, startRow, input)
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
                 });
             }
         }
@@ -563,7 +579,7 @@ export async function searchSymbols(workspace, input) {
           selection_end_column
         FROM symbols
         WHERE ${where.join(' AND ')}
-        ORDER BY name ASC, file_path ASC, start_row ASC
+        ORDER BY file_path ASC, start_row ASC, start_column ASC, name ASC
         LIMIT ?
       `, params);
         const symbols = [];
@@ -608,7 +624,7 @@ export async function searchSymbols(workspace, input) {
                                 column: Number(selectionEndColumn)
                             }
                         },
-                    ...snippetDetails(file.ok ? file.text : undefined, startRow, input)
+                    ...snippetDetails(filePath, rowValue(row, 'language'), file.ok ? file.text : undefined, startRow, input)
                 });
             }
         }

package/dist/analysis/summary.js

@@ -43,6 +43,9 @@ function isImportNode(language, nodeType) {
     }
 }
 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));
@@ -57,6 +60,25 @@ function isExportNode(language, nodeType) {
             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

@@ -146,8 +146,30 @@ 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,
+            maxFiles: z.number().int().positive().max(100).optional(),
+            indexedSearch: z
+                .union([
+                z.object({
+                    mode: z.literal('symbols').optional(),
+                    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()
+                }),
+                z.object({
+                    mode: z.literal('references'),
+                    name: z.string(),
+                    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', {
@@ -164,7 +186,8 @@ export function registerTools(server, workspace) {
             limit: z.number().int().positive().max(500).optional(),
             refreshIfStale: z.boolean().optional(),
             contextBefore: contextLineCountSchema.optional(),
-            contextAfter: contextLineCountSchema.optional()
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
         }
     }, handlers.searchSymbols);
     server.registerTool('find_indexed_definition', {
@@ -176,7 +199,8 @@ export function registerTools(server, workspace) {
             limit: z.number().int().positive().max(500).optional(),
             refreshIfStale: z.boolean().optional(),
             contextBefore: contextLineCountSchema.optional(),
-            contextAfter: contextLineCountSchema.optional()
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
         }
     }, handlers.findIndexedDefinition);
     server.registerTool('find_indexed_references', {
@@ -187,7 +211,8 @@ export function registerTools(server, workspace) {
             limit: z.number().int().positive().max(500).optional(),
             refreshIfStale: z.boolean().optional(),
             contextBefore: contextLineCountSchema.optional(),
-            contextAfter: contextLineCountSchema.optional()
+            contextAfter: contextLineCountSchema.optional(),
+            includePreview: z.boolean().optional()
         }
     }, handlers.findIndexedReferences);
     server.registerTool('get_index_status', {

package/docs/tools.md

@@ -0,0 +1,208 @@
+# Tool Reference
+
+syntax-map-mcp의 주요 MCP 도구 입력과 응답 예시입니다. 응답 예시는 핵심 필드만 보여줍니다.
+
+## 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",
+  "maxFiles": 3,
+  "indexedSearch": {
+    "query": "UserService",
+    "kinds": ["class"],
+    "refreshIfStale": true,
+    "contextBefore": 1,
+    "contextAfter": 1
+  }
+}
+```
+
+인덱스 참조 검색 기반 입력:
+
+```json
+{
+  "detail": "compact",
+  "maxFiles": 3,
+  "indexedSearch": {
+    "mode": "references",
+    "name": "formatUser",
+    "refreshIfStale": true,
+    "contextBefore": 1,
+    "contextAfter": 1
+  }
+}
+```
+
+응답 일부:
+
+```json
+{
+  "ok": true,
+  "metadata": {
+    "indexedSearchMode": "symbols",
+    "indexPath": "/workspace/.syntax-map-mcp/index.sqlite",
+    "isStale": false,
+    "staleFiles": 0,
+    "refreshed": true,
+    "total": 1,
+    "summarizedFiles": 1,
+    "omittedFiles": 0
+  },
+  "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
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
   },
   "files": [
     "dist",
+    "docs/tools.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -29,7 +30,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",