ronds-mcp-tracker 0.1.7 → 0.1.9

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/server.js

@@ -126,6 +126,24 @@ 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');
 }
@@ -171,6 +189,24 @@ function loadSnapshot(snapshotId) {
     const raw = fs.readFileSync(filePath, 'utf8');
     return JSON.parse(raw);
 }
+function loadLatestSnapshotForFile(filePath) {
+    const dir = ensureSnapshotsDirExists();
+    const snapshots = fs.readdirSync(dir)
+        .map((name) => path.join(dir, name))
+        .filter((snapshotPath) => fs.statSync(snapshotPath).isFile())
+        .map((snapshotPath) => {
+        try {
+            const raw = fs.readFileSync(snapshotPath, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((snapshot) => snapshot !== null && snapshot.file_path === filePath)
+        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+    return snapshots[0] ?? null;
+}
 function deleteSnapshot(snapshotId) {
     const filePath = getSnapshotPath(snapshotId);
     if (fs.existsSync(filePath)) {
@@ -259,7 +295,7 @@ function getFailedEventPath(eventId) {
 }
 function handleBeforeEdit(input) {
     const filePath = validateFilePath(input.file_path);
-    const content = readFileContent(filePath);
+    const content = fs.existsSync(filePath) ? readFileContent(filePath) : '';
     const snapshotId = randomUUID();
     saveSnapshot({
         snapshot_id: snapshotId,
@@ -279,55 +315,54 @@ async function handleAfterEdit(input, config) {
     if (!snapshotId) {
         throw new Error('snapshot_id is required');
     }
-    const snapshot = loadSnapshot(snapshotId);
+    const snapshot = loadSnapshot(snapshotId) ?? loadLatestSnapshotForFile(filePath);
     if (!snapshot) {
-        return JSON.stringify({
-            status: 'snapshot_not_found',
-            snapshot_id: snapshotId,
-            file_path: filePath
-        });
+        return JSON.stringify({ success: false });
     }
     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
-        });
+        return JSON.stringify({ success: false });
     }
     const oldStr = snapshot.content;
     const newStr = readFileContent(filePath);
     const addedLines = getAddedLines(oldStr, newStr);
     const diffStats = countDiff(oldStr, newStr);
-    const gitInfo = await getGitInfo(process.cwd());
-    const event = {
-        event_id: randomUUID(),
-        timestamp: new Date().toISOString(),
-        worker_id: config.worker_id,
-        git: gitInfo ? { repo_name: gitInfo.repo_name } : null,
-        file: { path: getKafkaFilePath(filePath, gitInfo), operation: 'edit' },
-        changes: {
-            added_content: addedLines,
-            added: diffStats.added,
-            removed: diffStats.removed
-        }
-    };
+    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
-        });
+        return JSON.stringify({ success: false });
     }
     deleteSnapshot(snapshotId);
+    return JSON.stringify({ success: true });
+}
+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: 'recorded',
+        status,
         event_id: event.event_id,
-        lines_changed: diffStats.added + diffStats.removed,
-        added_content: addedLines
+        lines_changed: added,
+        added_content: addedContent
     });
 }
 function handleCleanupFailed(input) {
@@ -363,6 +398,18 @@ const AFTER_EDIT_TOOL_SCHEMA = {
         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' },
+            added_content: { type: 'string' }
+        },
+        required: ['file_path', 'added_content']
+    }
+};
 const CLEANUP_FAILED_TOOL_SCHEMA = {
     name: 'cleanup_failed',
     description: 'Clean up failed queue files by age.',
@@ -396,7 +443,7 @@ async function main() {
         }
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [BEFORE_EDIT_TOOL_SCHEMA, 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;
@@ -409,6 +456,10 @@ async function main() {
             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.7",
+  "version": "0.1.9",
   "type": "module",
   "bin": {
     "ronds-mcp-tracker": "./bin/cli.js"