syntax-map-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kht6163
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# syntax-map-mcp
+
+Tree-sitter 기반 코드 분석 MCP 서버입니다. 지정한 `workspaceRoot` 아래의 JavaScript, TypeScript, TSX, Python 소스 파일을 읽고 심볼, 정의, 참조, 요약, tree-sitter query, 컨텍스트 markdown을 제공합니다.
+
+## 설치와 빌드
+
+```bash
+npm install
+npm run build
+```
+
+개발 중 검증:
+
+```bash
+npm test
+npm run typecheck
+```
+
+## 실행
+
+```bash
+node dist/cli.js --workspace-root /path/to/workspace
+```
+
+`workspaceRoot` 결정 순서:
+
+1. `--workspace-root` 인자
+2. `WORKSPACE_ROOT` 환경 변수
+3. 현재 작업 디렉터리
+
+## 제공 도구
+
+- `list_symbols`: 파일 하나의 top-level 심볼 목록 반환
+- `find_definition`: 여러 파일에서 이름과 선택적 kind로 정의 검색
+- `find_references`: 여러 파일에서 식별자 참조 검색
+- `summarize_file`: 파일 언어, 라인 수, imports, exports, symbols 요약
+- `run_query`: 파일 하나에 tree-sitter query 실행
+- `build_context`: 여러 파일 요약을 markdown 컨텍스트로 구성
+- `index_workspace`: 지원 소스 파일을 파싱해 SQLite 심볼 인덱스 생성 또는 갱신
+- `search_symbols`: SQLite 인덱스에서 심볼 이름 검색
+- `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`를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. 자동 watch 모드는 아직 포함하지 않았습니다.
+
+## MCP 설정 예시
+
+```json
+{
+  "mcpServers": {
+    "syntax-map-mcp": {
+      "command": "node",
+      "args": [
+        "/Users/hantaekim/my-project/tree-sitter/dist/cli.js",
+        "--workspace-root",
+        "/path/to/workspace"
+      ]
+    }
+  }
+}
+```
+
+## 보안 경계
+
+서버는 `workspaceRoot` 내부 파일만 읽습니다. 지원 확장자는 `.js`, `.jsx`, `.ts`, `.tsx`, `.py`뿐이며, workspace 밖으로 나가는 경로나 지원하지 않는 확장자는 오류로 처리합니다.

package/dist/analysis/context.js

@@ -0,0 +1,47 @@
+import { summarizeFile } from './summary.js';
+export async function buildContext(workspace, input) {
+    const summaries = [];
+    for (const filePath of input.paths) {
+        const summary = await summarizeFile(workspace, filePath);
+        if (!summary.ok)
+            return summary;
+        summaries.push(summary);
+    }
+    return {
+        ok: true,
+        markdown: renderMarkdown(summaries, input.detail)
+    };
+}
+function renderMarkdown(summaries, detail) {
+    return ['# Code Context', ...summaries.map(summary => renderFile(summary, detail))].join('\n\n');
+}
+function renderFile(summary, detail) {
+    const lines = [
+        `## ${summary.path}`,
+        '',
+        `- Language: ${summary.language}`,
+        `- Lines: ${summary.lineCount}`,
+        '',
+        '### Symbols',
+        ...renderSymbols(summary)
+    ];
+    if (detail === 'full') {
+        if (summary.imports.length > 0) {
+            lines.push('', '### Imports', ...summary.imports.map(line => `- ${line}`));
+        }
+        if (summary.exports.length > 0) {
+            lines.push('', '### Exports', ...summary.exports.map(line => `- ${line}`));
+        }
+    }
+    return lines.join('\n');
+}
+function renderSymbols(summary) {
+    if (summary.symbols.length === 0)
+        return ['- None'];
+    return summary.symbols.map(symbol => {
+        const row = symbol.range.start.row + 1;
+        const column = symbol.range.start.column + 1;
+        const name = symbol.kind === 'method' && symbol.parentName ? `${symbol.parentName}.${symbol.name}` : symbol.name;
+        return `- ${symbol.kind} ${name} (${row}:${column})`;
+    });
+}

package/dist/analysis/definitions.js

@@ -0,0 +1,26 @@
+import { parseSourceFile } from '../parser.js';
+import { listSymbols } from './symbols.js';
+export async function findDefinitions(workspace, input) {
+    const definitions = [];
+    const kinds = input.kinds ? new Set(input.kinds) : undefined;
+    for (const inputPath of input.paths) {
+        const file = await workspace.readSourceFile(inputPath);
+        if (!file.ok)
+            return file;
+        const parsed = parseSourceFile(file);
+        if (!parsed.ok)
+            return parsed;
+        definitions.push(...listSymbols(parsed)
+            .filter(symbol => symbol.name === input.name)
+            .filter(symbol => !kinds || kinds.has(symbol.kind))
+            .map(symbol => ({
+            ...symbol,
+            path: file.relativePath,
+            snippet: lineAt(file.text, symbol.range.start.row)
+        })));
+    }
+    return { ok: true, definitions };
+}
+function lineAt(text, row) {
+    return text.split(/\r?\n/)[row] ?? '';
+}

package/dist/analysis/index.js

@@ -0,0 +1,383 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import initSqlJs from 'sql.js';
+import { listSymbols } from './symbols.js';
+import { parseSourceFile } from '../parser.js';
+const INDEX_DIRECTORY = '.syntax-map-mcp';
+const INDEX_FILE = 'index.sqlite';
+function indexPathForWorkspace(workspace) {
+    return path.join(workspace.root, INDEX_DIRECTORY, INDEX_FILE);
+}
+function failure(message) {
+    return {
+        ok: false,
+        error: {
+            code: 'INDEX_ERROR',
+            message
+        }
+    };
+}
+async function openDatabase(indexPath) {
+    const SQL = await initSqlJs();
+    try {
+        const data = await readFile(indexPath);
+        return new SQL.Database(data);
+    }
+    catch {
+        return new SQL.Database();
+    }
+}
+async function saveDatabase(database, indexPath) {
+    await mkdir(path.dirname(indexPath), { recursive: true });
+    await writeFile(indexPath, Buffer.from(database.export()));
+}
+function initSchema(database) {
+    database.exec(`
+    PRAGMA foreign_keys = ON;
+
+    CREATE TABLE IF NOT EXISTS files (
+      path TEXT PRIMARY KEY,
+      language TEXT,
+      size INTEGER NOT NULL,
+      mtime_ms REAL NOT NULL,
+      parse_status TEXT NOT NULL,
+      error_message TEXT,
+      indexed_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS symbols (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL,
+      language TEXT NOT NULL,
+      name TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      parent_name TEXT,
+      start_row INTEGER NOT NULL,
+      start_column INTEGER NOT NULL,
+      end_row INTEGER NOT NULL,
+      end_column INTEGER NOT NULL,
+      selection_start_row INTEGER,
+      selection_start_column INTEGER,
+      selection_end_row INTEGER,
+      selection_end_column INTEGER,
+      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);
+  `);
+}
+function selectStoredFiles(database) {
+    const rows = database.exec('SELECT path, size, mtime_ms, parse_status FROM files');
+    const files = new Map();
+    const result = rows[0];
+    if (!result)
+        return files;
+    for (const row of result.values) {
+        const [filePath, size, mtimeMs, parseStatus] = row;
+        files.set(String(filePath), {
+            path: String(filePath),
+            size: Number(size),
+            mtimeMs: Number(mtimeMs),
+            parseStatus: String(parseStatus)
+        });
+    }
+    return files;
+}
+function isCurrent(stored, current) {
+    return (stored !== undefined &&
+        stored.parseStatus === 'ok' &&
+        stored.size === current.size &&
+        stored.mtimeMs === current.mtimeMs);
+}
+function upsertFile(database, input) {
+    database.run(`
+      INSERT INTO files (path, language, size, mtime_ms, parse_status, error_message, indexed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET
+        language = excluded.language,
+        size = excluded.size,
+        mtime_ms = excluded.mtime_ms,
+        parse_status = excluded.parse_status,
+        error_message = excluded.error_message,
+        indexed_at = excluded.indexed_at
+    `, [
+        input.file.relativePath,
+        input.language,
+        input.file.size,
+        input.file.mtimeMs,
+        input.parseStatus,
+        input.errorMessage,
+        new Date().toISOString()
+    ]);
+}
+function insertSymbol(database, input) {
+    database.run(`
+      INSERT INTO symbols (
+        file_path,
+        language,
+        name,
+        kind,
+        parent_name,
+        start_row,
+        start_column,
+        end_row,
+        end_column,
+        selection_start_row,
+        selection_start_column,
+        selection_end_row,
+        selection_end_column
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `, [
+        input.filePath,
+        input.language,
+        input.symbol.name,
+        input.symbol.kind,
+        input.symbol.parentName ?? null,
+        input.symbol.range.start.row,
+        input.symbol.range.start.column,
+        input.symbol.range.end.row,
+        input.symbol.range.end.column,
+        input.symbol.selectionRange?.start.row ?? null,
+        input.symbol.selectionRange?.start.column ?? null,
+        input.symbol.selectionRange?.end.row ?? null,
+        input.symbol.selectionRange?.end.column ?? null
+    ]);
+}
+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 scalarCount(database, sql) {
+    const result = database.exec(sql)[0];
+    if (!result)
+        return 0;
+    return Number(result.values[0]?.[0] ?? 0);
+}
+function sqlLikePattern(query) {
+    return `%${query.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_')}%`;
+}
+function rowValue(row, key) {
+    return row[key];
+}
+export async function indexWorkspace(workspace) {
+    const indexPath = indexPathForWorkspace(workspace);
+    const database = await openDatabase(indexPath);
+    try {
+        initSchema(database);
+        const currentFiles = await workspace.listSourceFiles();
+        const currentPaths = new Set(currentFiles.map(file => file.relativePath));
+        const storedFiles = selectStoredFiles(database);
+        let removedFiles = 0;
+        let indexedFiles = 0;
+        let skippedFiles = 0;
+        for (const storedPath of storedFiles.keys()) {
+            if (!currentPaths.has(storedPath)) {
+                deleteFile(database, storedPath);
+                removedFiles += 1;
+            }
+        }
+        for (const fileInfo of currentFiles) {
+            if (isCurrent(storedFiles.get(fileInfo.relativePath), fileInfo)) {
+                skippedFiles += 1;
+                continue;
+            }
+            const file = await workspace.readSourceFile(fileInfo.relativePath);
+            if (!file.ok) {
+                upsertFile(database, {
+                    file: fileInfo,
+                    language: null,
+                    parseStatus: 'error',
+                    errorMessage: file.error.message
+                });
+                deleteSymbolsForFile(database, fileInfo.relativePath);
+                indexedFiles += 1;
+                continue;
+            }
+            const parsed = parseSourceFile(file);
+            if (!parsed.ok) {
+                upsertFile(database, {
+                    file: fileInfo,
+                    language: null,
+                    parseStatus: 'error',
+                    errorMessage: parsed.error.message
+                });
+                deleteSymbolsForFile(database, fileInfo.relativePath);
+                indexedFiles += 1;
+                continue;
+            }
+            upsertFile(database, {
+                file: fileInfo,
+                language: parsed.language,
+                parseStatus: 'ok',
+                errorMessage: null
+            });
+            deleteSymbolsForFile(database, fileInfo.relativePath);
+            for (const symbol of listSymbols(parsed)) {
+                insertSymbol(database, {
+                    filePath: fileInfo.relativePath,
+                    language: parsed.language,
+                    symbol
+                });
+            }
+            indexedFiles += 1;
+        }
+        await saveDatabase(database, indexPath);
+        return {
+            ok: true,
+            indexPath,
+            indexedFiles,
+            skippedFiles,
+            removedFiles,
+            symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols')
+        };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        database.close();
+    }
+}
+export async function searchSymbols(workspace, input) {
+    const indexPath = indexPathForWorkspace(workspace);
+    const database = await openDatabase(indexPath);
+    try {
+        initSchema(database);
+        const where = ['name LIKE ? ESCAPE "\\"'];
+        const params = [sqlLikePattern(input.query)];
+        if (input.kinds && input.kinds.length > 0) {
+            where.push(`kind IN (${input.kinds.map(() => '?').join(', ')})`);
+            params.push(...input.kinds);
+        }
+        const limit = input.limit ?? 50;
+        params.push(limit);
+        const statement = database.prepare(`
+        SELECT
+          file_path,
+          language,
+          name,
+          kind,
+          parent_name,
+          start_row,
+          start_column,
+          end_row,
+          end_column,
+          selection_start_row,
+          selection_start_column,
+          selection_end_row,
+          selection_end_column
+        FROM symbols
+        WHERE ${where.join(' AND ')}
+        ORDER BY name ASC, file_path ASC, start_row ASC
+        LIMIT ?
+      `, params);
+        const symbols = [];
+        try {
+            while (statement.step()) {
+                const row = statement.getAsObject();
+                const selectionStartRow = rowValue(row, 'selection_start_row');
+                const selectionStartColumn = rowValue(row, 'selection_start_column');
+                const selectionEndRow = rowValue(row, 'selection_end_row');
+                const selectionEndColumn = rowValue(row, 'selection_end_column');
+                symbols.push({
+                    path: String(rowValue(row, 'file_path')),
+                    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')),
+                            column: Number(rowValue(row, 'start_column'))
+                        },
+                        end: {
+                            row: Number(rowValue(row, 'end_row')),
+                            column: Number(rowValue(row, 'end_column'))
+                        }
+                    },
+                    selectionRange: selectionStartRow === null ||
+                        selectionStartColumn === null ||
+                        selectionEndRow === null ||
+                        selectionEndColumn === null
+                        ? undefined
+                        : {
+                            start: {
+                                row: Number(selectionStartRow),
+                                column: Number(selectionStartColumn)
+                            },
+                            end: {
+                                row: Number(selectionEndRow),
+                                column: Number(selectionEndColumn)
+                            }
+                        }
+                });
+            }
+        }
+        finally {
+            statement.free();
+        }
+        return {
+            ok: true,
+            indexPath,
+            total: symbols.length,
+            symbols
+        };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        database.close();
+    }
+}
+export async function getIndexStatus(workspace) {
+    const indexPath = indexPathForWorkspace(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;
+            }
+        }
+        return {
+            ok: true,
+            indexPath,
+            indexedFiles: scalarCount(database, 'SELECT COUNT(*) FROM files WHERE parse_status = "ok"'),
+            symbols: scalarCount(database, 'SELECT COUNT(*) FROM symbols'),
+            staleFiles
+        };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        database.close();
+    }
+}
+export async function clearIndex(workspace) {
+    const indexPath = indexPathForWorkspace(workspace);
+    try {
+        await rm(indexPath, { force: true });
+        return {
+            ok: true,
+            indexPath,
+            cleared: true
+        };
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/analysis/query.js

@@ -0,0 +1,32 @@
+import Parser from 'tree-sitter';
+import { languageForName } from '../languages.js';
+export function runTreeSitterQuery(parsed, queryText) {
+    try {
+        const query = new Parser.Query(languageForName(parsed.language), queryText);
+        const captures = query.captures(parsed.tree.rootNode).map(capture => ({
+            name: capture.name,
+            nodeType: capture.node.type,
+            range: {
+                start: capture.node.startPosition,
+                end: capture.node.endPosition
+            },
+            text: capture.node.text
+        }));
+        return {
+            ok: true,
+            language: parsed.language,
+            path: parsed.file.relativePath,
+            captures
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: {
+                code: 'QUERY_ERROR',
+                message
+            }
+        };
+    }
+}

package/dist/analysis/references.js

@@ -0,0 +1,41 @@
+import { parseSourceFile } from '../parser.js';
+import { runTreeSitterQuery } from './query.js';
+export async function findReferences(workspace, input) {
+    const references = [];
+    for (const inputPath of input.paths) {
+        const file = await workspace.readSourceFile(inputPath);
+        if (!file.ok)
+            return file;
+        const parsed = parseSourceFile(file);
+        if (!parsed.ok)
+            return parsed;
+        const query = runTreeSitterQuery(parsed, referenceQueryForLanguage(parsed.language));
+        if (!query.ok)
+            return query;
+        references.push(...query.captures
+            .filter(capture => capture.text === input.name)
+            .map(capture => ({
+            path: file.relativePath,
+            name: capture.text,
+            nodeType: capture.nodeType,
+            range: capture.range,
+            snippet: lineAt(file.text, capture.range.start.row)
+        })));
+    }
+    return { ok: true, references };
+}
+function referenceQueryForLanguage(language) {
+    switch (language) {
+        case 'typescript':
+        case 'tsx':
+            return '[(identifier) (type_identifier) (property_identifier)] @reference';
+        case 'javascript':
+            return '[(identifier) (property_identifier)] @reference';
+        case 'python':
+        default:
+            return '(identifier) @reference';
+    }
+}
+function lineAt(text, row) {
+    return text.split(/\r?\n/)[row] ?? '';
+}

package/dist/analysis/summary.js

@@ -0,0 +1,36 @@
+import { parseSourceFile } from '../parser.js';
+import { listSymbols } from './symbols.js';
+export async function summarizeFile(workspace, filePath) {
+    const file = await workspace.readSourceFile(filePath);
+    if (!file.ok)
+        return file;
+    const parsed = parseSourceFile(file);
+    if (!parsed.ok)
+        return parsed;
+    return {
+        ok: true,
+        path: file.relativePath,
+        language: parsed.language,
+        lineCount: countLines(file.text),
+        symbols: listSymbols(parsed),
+        imports: findImports(file.text),
+        exports: findExports(file.text)
+    };
+}
+function countLines(text) {
+    if (text.length === 0)
+        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 findExports(text) {
+    return trimmedLines(text).filter(line => line.startsWith('export '));
+}
+function trimmedLines(text) {
+    return text
+        .split(/\r\n|\r|\n/)
+        .map(line => line.trim())
+        .filter(Boolean);
+}

package/dist/analysis/symbols.js

@@ -0,0 +1,119 @@
+import Parser from 'tree-sitter';
+import { languageForName } from '../languages.js';
+const javaScriptSymbolPatterns = [
+    { kind: 'class', query: '(class_declaration name: (identifier) @name) @definition' },
+    { kind: 'method', query: '(method_definition name: (property_identifier) @name) @definition' },
+    { kind: 'function', query: '(function_declaration name: (identifier) @name) @definition' },
+    { kind: 'variable', query: '(variable_declarator name: (identifier) @name) @definition' }
+];
+const typeScriptSymbolPatterns = [
+    { kind: 'interface', query: '(interface_declaration name: (type_identifier) @name) @definition' },
+    { kind: 'type', query: '(type_alias_declaration name: (type_identifier) @name) @definition' },
+    { kind: 'class', query: '(class_declaration name: (type_identifier) @name) @definition' },
+    { kind: 'class', query: '(abstract_class_declaration name: (type_identifier) @name) @definition' },
+    { kind: 'method', query: '(method_definition name: (property_identifier) @name) @definition' },
+    { kind: 'method', query: '(abstract_method_signature name: (property_identifier) @name) @definition' },
+    { kind: 'function', query: '(function_declaration name: (identifier) @name) @definition' },
+    { kind: 'variable', query: '(variable_declarator name: (identifier) @name) @definition' }
+];
+const pythonSymbolPatterns = [
+    { kind: 'class', query: '(class_definition name: (identifier) @name) @definition' },
+    { kind: 'function', query: '(function_definition name: (identifier) @name) @definition' },
+    { kind: 'variable', query: '(module (expression_statement (assignment left: (identifier) @name) @definition))' }
+];
+export function listSymbols(parsed) {
+    return patternsForLanguage(parsed).flatMap(pattern => querySymbols(parsed, pattern));
+}
+function patternsForLanguage(parsed) {
+    switch (parsed.language) {
+        case 'javascript':
+            return javaScriptSymbolPatterns;
+        case 'typescript':
+        case 'tsx':
+            return typeScriptSymbolPatterns;
+        case 'python':
+            return pythonSymbolPatterns;
+    }
+}
+function querySymbols(parsed, pattern) {
+    const query = new Parser.Query(languageForName(parsed.language), pattern.query);
+    return query.matches(parsed.tree.rootNode).flatMap(match => {
+        const name = match.captures.find(capture => capture.name === 'name')?.node;
+        const definition = match.captures.find(capture => capture.name === 'definition')?.node ?? name;
+        if (!name || !definition)
+            return [];
+        if (pattern.kind === 'variable' && !isTopLevelVariableDefinition(definition))
+            return [];
+        if (pattern.kind === 'method' &&
+            isJavaScriptLikeLanguage(parsed) &&
+            !directJavaScriptLikeMethodClass(definition)) {
+            return [];
+        }
+        if (pattern.kind === 'method' && name.text === 'constructor')
+            return [];
+        const kind = symbolKind(parsed, pattern.kind, definition);
+        return [
+            {
+                name: name.text,
+                kind,
+                range: rangeForNode(definition),
+                selectionRange: rangeForNode(name),
+                parentName: parentNameForSymbol(parsed, kind, definition)
+            }
+        ];
+    });
+}
+function symbolKind(parsed, kind, definition) {
+    if (parsed.language === 'python' && kind === 'function' && isDirectPythonMethod(definition)) {
+        return 'method';
+    }
+    return kind;
+}
+function parentNameForSymbol(parsed, kind, definition) {
+    if (kind !== 'method')
+        return undefined;
+    const classNode = parsed.language === 'python'
+        ? directPythonMethodClass(definition)
+        : directJavaScriptLikeMethodClass(definition);
+    return classNode?.childForFieldName('name')?.text;
+}
+function isJavaScriptLikeLanguage(parsed) {
+    return (parsed.language === 'javascript' ||
+        parsed.language === 'typescript' ||
+        parsed.language === 'tsx');
+}
+function isTopLevelVariableDefinition(definition) {
+    const statement = definition.parent;
+    if (!statement)
+        return false;
+    if (statement.parent?.type === 'program' || statement.parent?.type === 'module')
+        return true;
+    return (statement.parent?.type === 'export_statement' &&
+        (statement.parent.parent?.type === 'program' || statement.parent.parent?.type === 'module'));
+}
+function isDirectPythonMethod(definition) {
+    return directPythonMethodClass(definition) !== undefined;
+}
+function directPythonMethodClass(definition) {
+    const methodNode = definition.parent?.type === 'decorated_definition' ? definition.parent : definition;
+    const block = methodNode.parent;
+    const classNode = block?.parent;
+    if (block?.type !== 'block' || classNode?.type !== 'class_definition')
+        return undefined;
+    return classNode;
+}
+function directJavaScriptLikeMethodClass(definition) {
+    const classBody = definition.parent;
+    const classNode = classBody?.parent;
+    if (classBody?.type !== 'class_body' ||
+        (classNode?.type !== 'class_declaration' && classNode?.type !== 'abstract_class_declaration')) {
+        return undefined;
+    }
+    return classNode;
+}
+function rangeForNode(node) {
+    return {
+        start: node.startPosition,
+        end: node.endPosition
+    };
+}

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { runServer } from './server.js';
+function readWorkspaceRoot(argv, env) {
+    const flagIndex = argv.indexOf('--workspace-root');
+    if (flagIndex >= 0 && argv[flagIndex + 1]) {
+        return argv[flagIndex + 1];
+    }
+    return env.WORKSPACE_ROOT ?? process.cwd();
+}
+await runServer({
+    workspaceRoot: readWorkspaceRoot(process.argv.slice(2), process.env)
+});

package/dist/languages.js

@@ -0,0 +1,14 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const javascript = require('tree-sitter-javascript');
+const python = require('tree-sitter-python');
+const typescript = require('tree-sitter-typescript');
+const languages = {
+    javascript,
+    typescript: typescript.typescript,
+    tsx: typescript.tsx,
+    python
+};
+export function languageForName(language) {
+    return languages[language];
+}

package/dist/parser.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import Parser from 'tree-sitter';
+import { languageForName } from './languages.js';
+export function detectLanguage(filePath) {
+    const extension = path.extname(filePath);
+    switch (extension) {
+        case '.js':
+        case '.jsx':
+            return { ok: true, language: 'javascript' };
+        case '.ts':
+            return { ok: true, language: 'typescript' };
+        case '.tsx':
+            return { ok: true, language: 'tsx' };
+        case '.py':
+            return { ok: true, language: 'python' };
+        default:
+            return {
+                ok: false,
+                error: {
+                    code: 'UNSUPPORTED_EXTENSION',
+                    message: `Unsupported extension: ${extension}`
+                }
+            };
+    }
+}
+export function parseSourceFile(file) {
+    const detected = detectLanguage(file.absolutePath);
+    if (!detected.ok)
+        return detected;
+    try {
+        const parser = new Parser();
+        parser.setLanguage(languageForName(detected.language));
+        const tree = parser.parse(file.text);
+        return {
+            ok: true,
+            file,
+            language: detected.language,
+            tree
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            error: {
+                code: 'PARSE_ERROR',
+                message
+            }
+        };
+    }
+}

package/dist/result.js

@@ -0,0 +1,15 @@
+export function jsonResult(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        structuredContent: value
+    };
+}
+export function toolFailure(code, message) {
+    return {
+        ...jsonResult({
+            ok: false,
+            error: { code, message }
+        }),
+        isError: true
+    };
+}

package/dist/server.js

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+import { createWorkspace } from './workspace.js';
+export async function createServer(options) {
+    const workspace = await createWorkspace(options.workspaceRoot);
+    const server = new McpServer({ name: 'syntax-map-mcp', version: '0.1.0' }, {
+        instructions: 'Analyze JavaScript, TypeScript, and Python source files under the configured workspaceRoot only.'
+    });
+    registerTools(server, workspace);
+    return server;
+}
+export async function runServer(options) {
+    const server = await createServer(options);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { buildContext as buildContextAnalysis } from './analysis/context.js';
+import { findDefinitions } from './analysis/definitions.js';
+import { clearIndex as clearWorkspaceIndex, 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';
+import { listSymbols as listParsedSymbols } from './analysis/symbols.js';
+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']);
+export function createToolHandlers(workspace) {
+    return {
+        async listSymbols(input) {
+            const file = await workspace.readSourceFile(input.path);
+            if (!file.ok)
+                return toolFailure(file.error.code, file.error.message);
+            const parsed = parseSourceFile(file);
+            if (!parsed.ok)
+                return toolFailure(parsed.error.code, parsed.error.message);
+            return jsonResult({
+                ok: true,
+                path: file.relativePath,
+                language: parsed.language,
+                symbols: listParsedSymbols(parsed)
+            });
+        },
+        async findDefinition(input) {
+            const result = await findDefinitions(workspace, input);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async findReferences(input) {
+            const result = await findReferencesAnalysis(workspace, input);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async summarizeFile(input) {
+            const result = await summarizeFileAnalysis(workspace, input.path);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async runQuery(input) {
+            const file = await workspace.readSourceFile(input.path);
+            if (!file.ok)
+                return toolFailure(file.error.code, file.error.message);
+            const parsed = parseSourceFile(file);
+            if (!parsed.ok)
+                return toolFailure(parsed.error.code, parsed.error.message);
+            const result = runTreeSitterQuery(parsed, input.query);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async buildContext(input) {
+            const result = await buildContextAnalysis(workspace, input);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async indexWorkspace(_input) {
+            const result = await indexWorkspaceAnalysis(workspace);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async searchSymbols(input) {
+            const result = await searchIndexedSymbols(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)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        },
+        async clearIndex(_input) {
+            const result = await clearWorkspaceIndex(workspace);
+            if (!result.ok)
+                return toolFailure(result.error.code, result.error.message);
+            return jsonResult(result);
+        }
+    };
+}
+export function registerTools(server, workspace) {
+    const handlers = createToolHandlers(workspace);
+    server.registerTool('list_symbols', {
+        title: 'List symbols',
+        description: 'List top-level symbols in one supported source file.',
+        inputSchema: {
+            path: z.string()
+        }
+    }, handlers.listSymbols);
+    server.registerTool('find_definition', {
+        title: 'Find definition',
+        description: 'Find symbol definitions by name across supported source files.',
+        inputSchema: {
+            name: z.string(),
+            paths: z.array(z.string()),
+            kinds: z.array(symbolKindSchema).optional()
+        }
+    }, handlers.findDefinition);
+    server.registerTool('find_references', {
+        title: 'Find references',
+        description: 'Find identifier references by name across supported source files.',
+        inputSchema: {
+            name: z.string(),
+            paths: z.array(z.string())
+        }
+    }, handlers.findReferences);
+    server.registerTool('summarize_file', {
+        title: 'Summarize file',
+        description: 'Summarize language, line count, imports, exports, and symbols for one file.',
+        inputSchema: {
+            path: z.string()
+        }
+    }, handlers.summarizeFile);
+    server.registerTool('run_query', {
+        title: 'Run tree-sitter query',
+        description: 'Run a tree-sitter query against one supported source file.',
+        inputSchema: {
+            path: z.string(),
+            query: z.string()
+        }
+    }, handlers.runQuery);
+    server.registerTool('build_context', {
+        title: 'Build context',
+        description: 'Build markdown context for supported source files.',
+        inputSchema: {
+            paths: z.array(z.string()),
+            detail: detailSchema
+        }
+    }, handlers.buildContext);
+    server.registerTool('index_workspace', {
+        title: 'Index workspace',
+        description: 'Build or refresh the SQLite symbol index for all supported source files.',
+        inputSchema: {}
+    }, handlers.indexWorkspace);
+    server.registerTool('search_symbols', {
+        title: 'Search indexed symbols',
+        description: 'Search symbols from the SQLite workspace index.',
+        inputSchema: {
+            query: z.string(),
+            kinds: z.array(symbolKindSchema).optional(),
+            limit: z.number().int().positive().max(500).optional()
+        }
+    }, handlers.searchSymbols);
+    server.registerTool('get_index_status', {
+        title: 'Get index status',
+        description: 'Return SQLite index path, indexed file count, symbol count, and stale file count.',
+        inputSchema: {}
+    }, handlers.getIndexStatus);
+    server.registerTool('clear_index', {
+        title: 'Clear index',
+        description: 'Delete the SQLite workspace index file.',
+        inputSchema: {}
+    }, handlers.clearIndex);
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/workspace.js

@@ -0,0 +1,97 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+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) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message } };
+}
+export async function createWorkspace(workspaceRoot) {
+    const root = await realpath(path.resolve(workspaceRoot));
+    async function readSourceFile(inputPath) {
+        const resolved = path.resolve(root, inputPath);
+        if (!isInsideRoot(root, resolved)) {
+            return failure('WORKSPACE_OUTSIDE_ROOT', `Path is outside workspaceRoot: ${inputPath}`);
+        }
+        const extension = path.extname(resolved);
+        if (!SUPPORTED_EXTENSIONS.has(extension)) {
+            return failure('UNSUPPORTED_EXTENSION', `Unsupported extension: ${extension}`);
+        }
+        let actualPath;
+        try {
+            actualPath = await realpath(resolved);
+        }
+        catch {
+            return failure('FILE_NOT_FOUND', `File not found: ${inputPath}`);
+        }
+        if (!isInsideRoot(root, actualPath)) {
+            return failure('WORKSPACE_OUTSIDE_ROOT', `Path is outside workspaceRoot: ${inputPath}`);
+        }
+        const actualExtension = path.extname(actualPath);
+        if (!SUPPORTED_EXTENSIONS.has(actualExtension)) {
+            return failure('UNSUPPORTED_EXTENSION', `Unsupported extension: ${actualExtension}`);
+        }
+        const fileStat = await stat(actualPath);
+        if (!fileStat.isFile()) {
+            return failure('FILE_NOT_FOUND', `Not a file: ${inputPath}`);
+        }
+        return {
+            ok: true,
+            absolutePath: actualPath,
+            relativePath: path.relative(root, actualPath),
+            text: await readFile(actualPath, 'utf8'),
+            size: fileStat.size,
+            mtimeMs: fileStat.mtimeMs
+        };
+    }
+    async function listSourceFilesInDirectory(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            const absolutePath = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!EXCLUDED_DIRECTORIES.has(entry.name)) {
+                    files.push(...(await listSourceFilesInDirectory(absolutePath)));
+                }
+                continue;
+            }
+            if (!entry.isFile() || !SUPPORTED_EXTENSIONS.has(path.extname(entry.name))) {
+                continue;
+            }
+            let actualPath;
+            try {
+                actualPath = await realpath(absolutePath);
+            }
+            catch {
+                continue;
+            }
+            if (!isInsideRoot(root, actualPath)) {
+                continue;
+            }
+            const fileStat = await stat(actualPath);
+            if (!fileStat.isFile()) {
+                continue;
+            }
+            files.push({
+                absolutePath: actualPath,
+                relativePath: path.relative(root, actualPath),
+                size: fileStat.size,
+                mtimeMs: fileStat.mtimeMs
+            });
+        }
+        return files.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    }
+    return {
+        root,
+        readSourceFile,
+        readSourceFiles(inputPaths) {
+            return Promise.all(inputPaths.map(readSourceFile));
+        },
+        listSourceFiles() {
+            return listSourceFilesInDirectory(root);
+        }
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "syntax-map-mcp",
+  "version": "0.1.0",
+  "description": "Tree-sitter based code analysis MCP server",
+  "type": "module",
+  "bin": {
+    "syntax-map-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/sql.js": "^1.4.11",
+    "sql.js": "^1.14.1",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-javascript": "^0.21.4",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0"
+  }
+}