ronds-mcp-tracker 0.1.6 → 0.1.8

package/README.md

@@ -47,18 +47,43 @@ Custom worker id:
 - Kafka config is currently hardcoded (see `src/config.ts`) and can be extended later.
 
 ## Tools
+### `before_edit`
+适用场景：支持在编辑前先调用 MCP 的客户端。服务端会保存编辑前快照，并返回 `snapshot_id` 供后续 `after_edit` 使用。
+
+Input:
+- `file_path`: file path
+
+Output:
+- `status`: `snapshotted`
+- `snapshot_id`: snapshot id
+- `file_path`: normalized file path
+
 ### `after_edit`
+适用场景：基于 `before_edit` 保存的快照，在编辑后计算完整 diff。该模式能区分新增与删除，`file.operation` 为 `edit`。
+
 Input:
 - `file_path`: file path
-- `old_string`: previous content
-- `new_string`: new content
+- `snapshot_id`: snapshot id returned by `before_edit`
 
 Output:
-- `status`: `recorded`
+- `status`: `recorded` or `queued_for_retry`
 - `event_id`: event id
-- `lines_changed`: total lines changed
+- `lines_changed`: total changed lines (`added + removed`)
 - `added_content`: added lines content (may be truncated)
 
+### `direct_add`
+适用场景：客户端无法在编辑前调用 MCP，只能在编辑完成后上报新增内容时使用。该模式不依赖 snapshot，直接记录新增内容，`file.operation` 为 `add`。
+
+Input:
+- `file_path`: file path
+- `added_content`: newly added content supplied by the client
+
+Output:
+- `status`: `recorded` or `queued_for_retry`
+- `event_id`: event id
+- `lines_changed`: non-empty line count in `added_content`
+- `added_content`: original added content
+
 ### `cleanup_failed`
 Input:
 - `max_age_hours` (optional): default 168
@@ -79,6 +104,38 @@ Output:
 ## Failed Queue
 Failed events are stored in `~/.mcp-tracker/failed` as JSON files. Old files are cleaned by age and replayed in FIFO order.
 
+## Usage Flow
+### Snapshot mode (`before_edit` + `after_edit`)
+适用于 Claude Code 这类可以在编辑前后分别调用 MCP 的客户端：
+
+1. 调用 `before_edit` 保存服务端快照
+2. 完成文件编辑
+3. 调用 `after_edit` 并传入 `snapshot_id`
+
+说明：
+- 如果目标文件在 `before_edit` 时还不存在，服务端会保存一个空快照。
+- 随后 `after_edit` 会把该文件视为“从空内容新增”，正常上传新增内容。
+- 这种场景下事件类型仍然是 `file.operation = edit`，用于保持 snapshot 模式的一致性。
+
+### Direct add mode (`direct_add`)
+适用于 Cursor 这类通常只能在编辑完成后调用 MCP 的客户端：
+
+1. 客户端拿到本次新增内容
+2. 调用 `direct_add(file_path, added_content)`
+3. 服务端直接构建 `ChangeEvent` 并发布到 Kafka
+
+适用建议：
+- 能走 `before_edit` / `after_edit` 时，优先使用 snapshot 模式。
+- 客户端只能后调用、拿不到编辑前快照时，再使用 `direct_add` 兜底。
+
+### Direct add mode (`direct_add`)
+适用于 Cursor 这类通常只能在编辑完成后调用 MCP 的客户端：
+
+1. 客户端拿到本次新增内容
+2. 调用 `direct_add(file_path, added_content)`
+3. 服务端直接构建 `ChangeEvent` 并发布到 Kafka
+
 ## Development
 - Build: `npm run build`
 - Test tools list: `echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/server.js`
+- Test direct add locally: call `tools/call` with `direct_add`, `file_path`, and multi-line `added_content`

package/dist/config.js

@@ -9,7 +9,6 @@ export const FAILED_QUEUE_CONFIG = {
 };
 function resolveWorkerId() {
     const localConfigPath = path.resolve(process.cwd(), '.ai_config', 'config.json');
-    console.log('[mcp-tracker] localConfigPath:', localConfigPath);
     try {
         if (fs.existsSync(localConfigPath)) {
             const raw = fs.readFileSync(localConfigPath, 'utf-8');

package/dist/server.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { diffLines } from 'diff';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -40,12 +41,27 @@ function getRepoNameFromGitConfig(cwd) {
         return null;
     }
 }
+function getGitRepoRoot(cwd) {
+    try {
+        const output = execSync('git rev-parse --show-toplevel', {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const repoRoot = output.trim();
+        return repoRoot || null;
+    }
+    catch {
+        return null;
+    }
+}
 async function getGitInfo(cwd) {
-    const repoNameFromGitConfig = getRepoNameFromGitConfig(cwd);
+    const repoRoot = getGitRepoRoot(cwd) ?? cwd;
+    const repoNameFromGitConfig = getRepoNameFromGitConfig(repoRoot);
     if (repoNameFromGitConfig) {
-        return { repo_name: repoNameFromGitConfig };
+        return { repo_name: repoNameFromGitConfig, repo_root: repoRoot };
     }
-    const configPath = path.join(cwd, '.gitlab', 'config.json');
+    const configPath = path.join(repoRoot, '.gitlab', 'config.json');
     if (!fs.existsSync(configPath)) {
         return null;
     }
@@ -56,12 +72,25 @@ async function getGitInfo(cwd) {
         if (!repoName) {
             return null;
         }
-        return { repo_name: repoName };
+        return { repo_name: repoName, repo_root: repoRoot };
     }
     catch {
         return null;
     }
 }
+function toRepoRelativePath(filePath, repoRoot) {
+    if (!repoRoot) {
+        return filePath;
+    }
+    const relativePath = path.relative(repoRoot, filePath);
+    if (!relativePath || relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        return filePath;
+    }
+    return relativePath.replace(/\\/g, '/');
+}
+function getKafkaFilePath(filePath, gitInfo) {
+    return toRepoRelativePath(filePath, gitInfo?.repo_root);
+}
 function getAddedLines(oldStr, newStr) {
     const parts = diffLines(oldStr, newStr);
     let lineCount = 0;
@@ -97,9 +126,75 @@ function countDiff(oldStr, newStr) {
     }
     return { added, removed };
 }
+function countNonEmptyLines(content) {
+    return content.split('\n').filter((line) => line !== '').length;
+}
+async function buildChangeEvent(params) {
+    const gitInfo = await getGitInfo(process.cwd());
+    return {
+        event_id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        worker_id: params.config.worker_id,
+        git: gitInfo ? { repo_name: gitInfo.repo_name } : null,
+        file: { path: getKafkaFilePath(params.filePath, gitInfo), operation: params.operation },
+        changes: {
+            added_content: params.addedContent,
+            added: params.added,
+            removed: params.removed
+        }
+    };
+}
 function getFailedDir() {
     return path.join(os.homedir(), '.mcp-tracker', 'failed');
 }
+function getSnapshotsDir() {
+    return path.join(os.homedir(), '.mcp-tracker', 'snapshots');
+}
+function ensureSnapshotsDirExists() {
+    const dir = getSnapshotsDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+function getSnapshotPath(snapshotId) {
+    return path.join(getSnapshotsDir(), `${snapshotId}.json`);
+}
+function cleanupSnapshotsOnStartup() {
+    const dir = ensureSnapshotsDirExists();
+    const entries = fs.readdirSync(dir);
+    let deleted = 0;
+    for (const name of entries) {
+        const filePath = path.join(dir, name);
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile()) {
+            continue;
+        }
+        fs.unlinkSync(filePath);
+        deleted += 1;
+    }
+    return { status: 'cleaned', deleted_count: deleted };
+}
+function saveSnapshot(snapshot) {
+    const dir = ensureSnapshotsDirExists();
+    const filePath = path.join(dir, `${snapshot.snapshot_id}.json`);
+    fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf8');
+    return filePath;
+}
+function loadSnapshot(snapshotId) {
+    const filePath = getSnapshotPath(snapshotId);
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw);
+}
+function deleteSnapshot(snapshotId) {
+    const filePath = getSnapshotPath(snapshotId);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+}
 function cleanupFailed(maxAgeHours = 168) {
     const dir = getFailedDir();
     if (!fs.existsSync(dir)) {
@@ -167,23 +262,80 @@ async function replayFailed(maxCount, config) {
     }
     return { status: 'completed', replayed, failed };
 }
+function validateFilePath(filePath) {
+    const normalizedPath = filePath.trim();
+    if (!normalizedPath) {
+        throw new Error('file_path is required');
+    }
+    return normalizedPath;
+}
+function readFileContent(filePath) {
+    return fs.readFileSync(filePath, 'utf8');
+}
+function getFailedEventPath(eventId) {
+    return path.join(getFailedDir(), `${eventId}.json`);
+}
+function handleBeforeEdit(input) {
+    const filePath = validateFilePath(input.file_path);
+    const content = fs.existsSync(filePath) ? readFileContent(filePath) : '';
+    const snapshotId = randomUUID();
+    saveSnapshot({
+        snapshot_id: snapshotId,
+        file_path: filePath,
+        created_at: new Date().toISOString(),
+        content
+    });
+    return JSON.stringify({
+        status: 'snapshotted',
+        snapshot_id: snapshotId,
+        file_path: filePath
+    });
+}
 async function handleAfterEdit(input, config) {
-    const addedLines = getAddedLines(input.old_string, input.new_string);
-    const diffStats = countDiff(input.old_string, input.new_string);
-    const gitInfo = await getGitInfo(process.cwd());
-    const event = {
-        event_id: randomUUID(),
-        timestamp: new Date().toISOString(),
-        worker_id: config.worker_id,
-        git: gitInfo,
-        file: { path: input.file_path, operation: 'edit' },
-        changes: {
-            added_content: addedLines,
-            added: diffStats.added,
-            removed: diffStats.removed
-        }
-    };
+    const filePath = validateFilePath(input.file_path);
+    const snapshotId = input.snapshot_id?.trim();
+    if (!snapshotId) {
+        throw new Error('snapshot_id is required');
+    }
+    const snapshot = loadSnapshot(snapshotId);
+    if (!snapshot) {
+        return JSON.stringify({
+            status: 'snapshot_not_found',
+            snapshot_id: snapshotId,
+            file_path: filePath
+        });
+    }
+    if (snapshot.file_path !== filePath) {
+        return JSON.stringify({
+            status: 'snapshot_file_path_mismatch',
+            snapshot_id: snapshotId,
+            file_path: filePath,
+            snapshot_file_path: snapshot.file_path
+        });
+    }
+    const oldStr = snapshot.content;
+    const newStr = readFileContent(filePath);
+    const addedLines = getAddedLines(oldStr, newStr);
+    const diffStats = countDiff(oldStr, newStr);
+    const event = await buildChangeEvent({
+        filePath,
+        operation: 'edit',
+        addedContent: addedLines,
+        added: diffStats.added,
+        removed: diffStats.removed,
+        config
+    });
     await publishToKafka(config, event);
+    if (fs.existsSync(getFailedEventPath(event.event_id))) {
+        return JSON.stringify({
+            status: 'queued_for_retry',
+            event_id: event.event_id,
+            snapshot_id: snapshotId,
+            lines_changed: diffStats.added + diffStats.removed,
+            added_content: addedLines
+        });
+    }
+    deleteSnapshot(snapshotId);
     return JSON.stringify({
         status: 'recorded',
         event_id: event.event_id,
@@ -191,6 +343,30 @@ async function handleAfterEdit(input, config) {
         added_content: addedLines
     });
 }
+async function handleDirectAdd(input, config) {
+    const filePath = validateFilePath(input.file_path);
+    const addedContent = input.added_content;
+    if (typeof addedContent !== 'string' || !addedContent.trim()) {
+        throw new Error('added_content is required');
+    }
+    const added = countNonEmptyLines(addedContent);
+    const event = await buildChangeEvent({
+        filePath,
+        operation: 'add',
+        addedContent,
+        added,
+        removed: 0,
+        config
+    });
+    await publishToKafka(config, event);
+    const status = fs.existsSync(getFailedEventPath(event.event_id)) ? 'queued_for_retry' : 'recorded';
+    return JSON.stringify({
+        status,
+        event_id: event.event_id,
+        lines_changed: added,
+        added_content: addedContent
+    });
+}
 function handleCleanupFailed(input) {
     const maxAgeHours = input.max_age_hours ?? 168;
     const result = cleanupFailed(maxAgeHours);
@@ -201,17 +377,39 @@ async function handleReplayFailed(input, config) {
     const result = await replayFailed(maxCount, config);
     return JSON.stringify({ status: result.status, replayed: result.replayed, failed: result.failed });
 }
+const BEFORE_EDIT_TOOL_SCHEMA = {
+    name: 'before_edit',
+    description: 'Save a server-side snapshot before file edits.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string' }
+        },
+        required: ['file_path']
+    }
+};
 const AFTER_EDIT_TOOL_SCHEMA = {
     name: 'after_edit',
-    description: 'Record code changes after file edits.',
+    description: 'Record code changes after file edits using a saved snapshot.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string' },
+            snapshot_id: { type: 'string' }
+        },
+        required: ['file_path', 'snapshot_id']
+    }
+};
+const DIRECT_ADD_TOOL_SCHEMA = {
+    name: 'direct_add',
+    description: 'Record added content directly when no pre-edit snapshot is available.',
     inputSchema: {
         type: 'object',
         properties: {
             file_path: { type: 'string' },
-            old_string: { type: 'string' },
-            new_string: { type: 'string' }
+            added_content: { type: 'string' }
         },
-        required: ['file_path', 'old_string', 'new_string']
+        required: ['file_path', 'added_content']
     }
 };
 const CLEANUP_FAILED_TOOL_SCHEMA = {
@@ -236,6 +434,7 @@ const REPLAY_FAILED_TOOL_SCHEMA = {
 };
 async function main() {
     const config = loadConfig();
+    cleanupSnapshotsOnStartup();
     await initProducer(config);
     const server = new Server({
         name: 'code-change-tracker',
@@ -246,15 +445,23 @@ async function main() {
         }
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [AFTER_EDIT_TOOL_SCHEMA, CLEANUP_FAILED_TOOL_SCHEMA, REPLAY_FAILED_TOOL_SCHEMA]
+        tools: [BEFORE_EDIT_TOOL_SCHEMA, AFTER_EDIT_TOOL_SCHEMA, DIRECT_ADD_TOOL_SCHEMA, CLEANUP_FAILED_TOOL_SCHEMA, REPLAY_FAILED_TOOL_SCHEMA]
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const name = request.params.name;
         const input = request.params.arguments ?? {};
+        if (name === 'before_edit') {
+            const result = handleBeforeEdit(input);
+            return { content: [{ type: 'text', text: result }] };
+        }
         if (name === 'after_edit') {
             const result = await handleAfterEdit(input, config);
             return { content: [{ type: 'text', text: result }] };
         }
+        if (name === 'direct_add') {
+            const result = await handleDirectAdd(input, config);
+            return { content: [{ type: 'text', text: result }] };
+        }
         if (name === 'cleanup_failed') {
             const result = handleCleanupFailed(input);
             return { content: [{ type: 'text', text: result }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ronds-mcp-tracker",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "bin": {
     "ronds-mcp-tracker": "./bin/cli.js"