syntax-map-mcp 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## 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`의 입력/응답 예시를 추가했습니다.

package/README.md

@@ -53,185 +53,9 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 
 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
-}
-```
+도구별 입력과 응답 예시는 [docs/tools.md](./docs/tools.md)를 참고하세요.
 
 ## 변경 이력
 

package/dist/analysis/context.js

@@ -1,9 +1,10 @@
-import { searchSymbols } from './index.js';
+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
         });
     }
@@ -23,13 +24,49 @@ export async function buildContext(workspace, input) {
     };
 }
 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 paths = [...new Set(search.symbols.map(symbol => symbol.path))];
+    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);
@@ -39,7 +76,17 @@ async function buildIndexedSearchContext(workspace, input) {
     }
     return {
         ok: true,
-        markdown: renderMarkdown(summaries, input.detail, renderIndexedSearchResults(search.symbols))
+        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) {
@@ -47,6 +94,11 @@ function renderMarkdown(summaries, detail, intro) {
         .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) {

package/dist/analysis/index.js

@@ -413,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 = [];
@@ -500,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 = [];
@@ -579,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 = [];

package/dist/tools.js

@@ -148,15 +148,27 @@ export function registerTools(server, workspace) {
         inputSchema: {
             paths: z.array(z.string()).optional(),
             detail: detailSchema,
+            maxFiles: z.number().int().positive().max(100).optional(),
             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()
-            })
+                .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);

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.3",
+  "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"