ronds-mcp-tracker 0.1.7 → 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/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');
 }
@@ -259,7 +277,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,
@@ -299,19 +317,14 @@ async function handleAfterEdit(input, config) {
     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({
@@ -330,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);
@@ -363,6 +400,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 +445,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 +458,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.8",
   "type": "module",
   "bin": {
     "ronds-mcp-tracker": "./bin/cli.js"