syntax-map-mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## 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로 잘못 반환되지 않도록 했습니다.

package/README.md

@@ -47,10 +47,192 @@ 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`는 빈 배열입니다.
+
+## 도구 사용 예시
+
+### 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)를 참고하세요.

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

@@ -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);
@@ -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)
                 });
             }
         }
@@ -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)
                 });
             }
         }
@@ -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,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', {
@@ -164,7 +174,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 +187,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 +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.findIndexedReferences);
     server.registerTool('get_index_status', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntax-map-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Tree-sitter based code analysis MCP server",
   "license": "MIT",
   "type": "module",
@@ -29,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",