syntax-map-mcp 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.1.5 - 2026-05-06
+
+- `express-rate-limit` transitive 의존성을 override해 npm audit 취약점 경고를 제거했습니다.
+- `index_workspace`가 `workspaceRoot`의 `.gitignore` 패턴에 매칭되는 소스 파일을 인덱싱 대상에서 제외하도록 했습니다.
+
+## 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

@@ -45,7 +45,7 @@ npx -y syntax-map-mcp --workspace-root /path/to/workspace
 
 ## SQLite 인덱스
 
-`index_workspace`는 `workspaceRoot` 아래의 `.syntax-map-mcp/index.sqlite`에 인덱스를 저장합니다. 인덱싱 대상은 `.js`, `.jsx`, `.ts`, `.tsx`, `.py` 파일이며, `.git`, `.syntax-map-mcp`, `dist`, `node_modules` 디렉터리는 제외합니다.
+`index_workspace`는 `workspaceRoot` 아래의 `.syntax-map-mcp/index.sqlite`에 인덱스를 저장합니다. 인덱싱 대상은 `.js`, `.jsx`, `.ts`, `.tsx`, `.py` 파일이며, `.git`, `.syntax-map-mcp`, `dist`, `node_modules` 디렉터리와 `workspaceRoot`의 `.gitignore`에 매칭되는 파일은 제외합니다.
 
 파일 변경 여부는 `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 모드는 아직 포함하지 않았습니다.
 
@@ -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/dist/workspace.js

@@ -1,5 +1,6 @@
 import { readdir, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
+import ignore from 'ignore';
 const SUPPORTED_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.py']);
 const EXCLUDED_DIRECTORIES = new Set(['.git', '.syntax-map-mcp', 'dist', 'node_modules']);
 function isInsideRoot(root, candidate) {
@@ -9,8 +10,22 @@ function isInsideRoot(root, candidate) {
 function failure(code, message) {
     return { ok: false, error: { code, message } };
 }
+async function loadGitignore(root) {
+    const matcher = ignore();
+    try {
+        matcher.add(await readFile(path.join(root, '.gitignore'), 'utf8'));
+    }
+    catch {
+        // A workspace without .gitignore indexes all supported source files.
+    }
+    return matcher;
+}
+function toGitignorePath(relativePath) {
+    return relativePath.split(path.sep).join('/');
+}
 export async function createWorkspace(workspaceRoot) {
     const root = await realpath(path.resolve(workspaceRoot));
+    const gitignore = await loadGitignore(root);
     async function readSourceFile(inputPath) {
         const resolved = path.resolve(root, inputPath);
         if (!isInsideRoot(root, resolved)) {
@@ -58,7 +73,10 @@ export async function createWorkspace(workspaceRoot) {
                 }
                 continue;
             }
-            if (!entry.isFile() || !SUPPORTED_EXTENSIONS.has(path.extname(entry.name))) {
+            const relativeEntryPath = path.relative(root, absolutePath);
+            if (!entry.isFile() ||
+                !SUPPORTED_EXTENSIONS.has(path.extname(entry.name)) ||
+                gitignore.ignores(toGitignorePath(relativeEntryPath))) {
                 continue;
             }
             let actualPath;

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.5",
   "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"
@@ -35,6 +36,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/sql.js": "^1.4.11",
+    "ignore": "^7.0.5",
     "sql.js": "^1.14.1",
     "tree-sitter": "^0.21.1",
     "tree-sitter-javascript": "^0.21.4",
@@ -47,5 +49,8 @@
     "tsx": "^4.0.0",
     "typescript": "^5.8.0",
     "vitest": "^3.0.0"
+  },
+  "overrides": {
+    "express-rate-limit": "7.5.1"
   }
 }