session-weaver 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Session Handoff MCP
+
+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,227 @@
+# Session Weaver
+
+[![npm version](https://badge.fury.io/js/session-weaver.svg)](https://www.npmjs.com/package/session-weaver)
+
+解决 AI 编程助手（Cursor/Claude/Kiro 等）会话上下文丢失问题，实现跨会话、跨 AI 工具的上下文无缝交接。
+
+## 核心问题
+
+- AI 会话有 token 上限，长对话后上下文被截断
+- 新开会话时，AI 完全不知道之前做了什么
+- 切换不同 AI 工具时，项目上下文无法迁移
+- 踩过的坑、做过的决策无法持久化传递
+
+## 功能特性（7 工具架构）
+
+| 工具 | 功能 |
+|------|------|
+| `load_context` | 一键加载上下文（模块 + 会话 + 踩坑），自动设置当前模块 |
+| `save_context` | 一键保存进度（更新模块 + 创建会话 + 记录踩坑） |
+| `list_modules` | 查看所有项目或项目内模块概览 |
+| `list_pitfalls` | 查看踩坑记录，支持按项目/模块/标签过滤 |
+| `delete_data` | 删除会话、踩坑、模块或整个项目 |
+| `export_handoff` | 导出全量交接文档（Markdown + JSON） |
+| `import_handoff` | 导入交接文档重建完整项目 |
+
+## 快速开始
+
+### 通过 npm 安装
+
+```bash
+# 全局安装
+npm install -g session-weaver
+
+# 或使用 npx（无需安装，自动更新）
+npx -y session-weaver
+```
+
+## 配置 MCP 客户端
+
+### Claude Desktop
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "session-weaver": {
+      "command": "npx",
+      "args": ["-y", "session-weaver"]
+    }
+  }
+}
+```
+
+### Cursor
+
+编辑 `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "session-weaver": {
+      "command": "npx",
+      "args": ["-y", "session-weaver"]
+    }
+  }
+}
+```
+
+### 其他 MCP 客户端
+
+```json
+{
+  "mcpServers": {
+    "session-weaver": {
+      "command": "npx",
+      "args": ["-y", "session-weaver"]
+    }
+  }
+}
+```
+
+## 使用示例
+
+### 加载上下文（开始工作）
+
+```json
+{
+  "project": "my-app",
+  "module": "payment",
+  "sessionsLimit": 5
+}
+```
+
+返回：模块详情、最近会话、相关踩坑记录
+
+### 保存进度（完成工作）
+
+```json
+{
+  "project": "my-app",
+  "moduleUpdate": {
+    "removeTodos": ["微信SDK接入"],
+    "addDecision": {
+      "description": "选用 Stripe 而非 Paddle",
+      "reason": "更好的 API 文档"
+    }
+  },
+  "session": {
+    "note": "完成微信支付 SDK 接入",
+    "codeState": {
+      "modifiedFiles": ["src/payment/wechat.ts"]
+    }
+  },
+  "newPitfall": {
+    "problem": "微信回调验签失败",
+    "solution": "使用微信支付平台证书，不是商户证书",
+    "tags": ["wechat", "webhook"]
+  }
+}
+```
+
+一键完成：更新模块待办、创建会话、记录踩坑
+
+### 查看全局概览
+
+```json
+// 列出所有项目
+{}
+
+// 查看项目内模块
+{
+  "project": "my-app"
+}
+```
+
+### 导出让其他 AI 接手
+
+```json
+{
+  "project": "my-app"
+}
+```
+
+生成包含全量数据的 Markdown 文档（人类可读 + 机器可解析）
+
+### 导入交接文档
+
+```json
+{
+  "handoffId": "handoff-xxx"
+}
+```
+
+或
+
+```json
+{
+  "markdown": "# 🤖 AI 会话交接文档..."
+}
+```
+
+## 数据存储
+
+所有数据存储在 `~/.session-handoff/` 目录：
+
+```
+~/.session-handoff/
+├── projects/
+│   └── {project-name}.json    # 单文件 = 项目 + 模块 + 会话 + 踩坑
+└── handoffs/
+    └── {handoff-id}.md        # 交接文档
+```
+
+### 单文件结构
+
+每个项目一个 JSON 文件：
+
+```json
+{
+  "project": "my-app",
+  "currentModule": "payment",
+  "modules": {
+    "payment": {
+      "name": "payment",
+      "status": "active",
+      "summary": "支付宝完成，微信待接入",
+      "todos": ["退款接口"],
+      "decisions": [...],
+      "techStack": ["stripe", "alipay-sdk"]
+    }
+  },
+  "sessions": [...],
+  "pitfalls": [...]
+}
+```
+
+**特点：**
+- 单文件原子写入（临时文件 + 重命名，保证数据完整性）
+- 无需数据库，纯 JSON 文件，可手动编辑
+- 易于备份和版本控制
+
+## 上下文基于架构
+
+```
+传统方式：                  Session Weaver：
+读取所有 session 文件   →   读取单文件
+内存过滤排序            →   按模块预筛选
+返回全部数据            →   返回精准上下文
+AI 自行找关联           →   currentModule 自动记忆
+```
+
+## 技术栈
+
+- Node.js >= 18 / TypeScript
+- MCP SDK
+- nanoid (ID 生成)
+- zod (参数校验)
+
+## 许可证
+
+MIT
+
+## 相关链接
+
+- npm: https://www.npmjs.com/package/session-weaver
+- MCP 协议: https://modelcontextprotocol.io

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Session Handoff MCP Server
+ * 7工具完整版 - 上下文基于架构
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+/**
+ * Session Handoff MCP Server
+ * 7工具完整版 - 上下文基于架构
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { StorageManager } from './managers/storage.js';
+import { ContextManager } from './managers/context.js';
+import { ModuleManager } from './managers/module.js';
+import { PitfallManager } from './managers/pitfall.js';
+import { HandoffManager } from './managers/handoff.js';
+import { DeleteManager } from './managers/delete.js';
+// ============ Zod 校验 Schema ============
+// Tool 1: load_context
+const LoadContextSchema = z.object({
+    project: z.string().min(1, '项目名称不能为空'),
+    module: z.string().optional(),
+    includePitfalls: z.boolean().optional(),
+    sessionsLimit: z.number().int().min(1).max(50).optional()
+});
+// Tool 2: save_context
+const SaveContextSchema = z.object({
+    project: z.string().min(1, '项目名称不能为空'),
+    module: z.string().optional(),
+    moduleUpdate: z.object({
+        status: z.enum(['active', 'completed', 'archived']).optional(),
+        summary: z.string().optional(),
+        todos: z.array(z.string()).optional(),
+        addTodos: z.array(z.string()).optional(),
+        removeTodos: z.array(z.string()).optional(),
+        addDecision: z.object({
+            description: z.string(),
+            reason: z.string().optional()
+        }).optional(),
+        techStack: z.array(z.string()).optional()
+    }).optional(),
+    session: z.object({
+        note: z.string().min(1, '会话备注不能为空'),
+        codeState: z.object({
+            modifiedFiles: z.array(z.string()),
+            currentBranch: z.string().optional(),
+            uncommittedChanges: z.string().optional()
+        }).optional(),
+        todos: z.array(z.object({
+            task: z.string(),
+            priority: z.enum(['high', 'medium', 'low']).optional(),
+            done: z.boolean().optional()
+        })).optional(),
+        decisions: z.array(z.object({
+            description: z.string(),
+            reason: z.string(),
+            alternatives: z.array(z.string()).optional()
+        })).optional(),
+        techStack: z.array(z.string()).optional()
+    }).optional(),
+    newPitfall: z.object({
+        problem: z.string().min(1, '问题描述不能为空'),
+        solution: z.string().min(1, '解决方案不能为空'),
+        tags: z.array(z.string()).optional()
+    }).optional()
+});
+// Tool 3: list_modules
+const ListModulesSchema = z.object({
+    project: z.string().optional(),
+    status: z.enum(['active', 'completed', 'archived']).optional(),
+    includeArchived: z.boolean().optional(),
+    withStats: z.boolean().optional()
+});
+// Tool 4: list_pitfalls
+const ListPitfallsSchema = z.object({
+    project: z.string().optional(),
+    module: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    limit: z.number().int().min(1).max(100).optional()
+});
+// Tool 5: delete_data
+const DeleteDataSchema = z.object({
+    project: z.string().min(1, '项目名称不能为空'),
+    sessionId: z.string().optional(),
+    pitfallId: z.string().optional(),
+    moduleName: z.string().optional(),
+    entireProject: z.boolean().optional()
+});
+// Tool 6: export_handoff
+const ExportHandoffSchema = z.object({
+    project: z.string().min(1, '项目名称不能为空'),
+    includeModules: z.boolean().optional(),
+    includeSessions: z.boolean().optional(),
+    includePitfalls: z.boolean().optional()
+});
+// Tool 7: import_handoff
+const ImportHandoffSchema = z.object({
+    handoffId: z.string().optional(),
+    markdown: z.string().optional(),
+    projectName: z.string().optional(),
+    aiTool: z.string().optional()
+}).refine(data => data.handoffId || data.markdown, {
+    message: '必须提供 handoffId 或 markdown'
+});
+// ============ 主服务器类 ============
+class SessionHandoffServer {
+    server;
+    storage;
+    contextManager;
+    moduleManager;
+    pitfallManager;
+    handoffManager;
+    deleteManager;
+    constructor() {
+        this.server = new Server({
+            name: 'session-handoff-mcp',
+            version: '2.0.0'
+        }, {
+            capabilities: {
+                tools: {}
+            }
+        });
+        this.storage = new StorageManager();
+        this.contextManager = new ContextManager(this.storage);
+        this.moduleManager = new ModuleManager(this.storage);
+        this.pitfallManager = new PitfallManager(this.storage);
+        this.handoffManager = new HandoffManager(this.storage);
+        this.deleteManager = new DeleteManager(this.storage);
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // 列出可用工具
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'load_context',
+                    description: '加载指定项目的上下文。返回当前模块详情、最近会话、相关踩坑记录。自动设置 currentModule。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（必填）' },
+                            module: { type: 'string', description: '模块名称（可选，默认使用 currentModule）' },
+                            includePitfalls: { type: 'boolean', description: '是否包含踩坑记录（默认 true）' },
+                            sessionsLimit: { type: 'number', description: '返回最近N条会话（默认 3，最大 50）' }
+                        },
+                        required: ['project']
+                    }
+                },
+                {
+                    name: 'save_context',
+                    description: '保存上下文。可同时更新模块、创建会话、记录踩坑。所有参数可选，按需传递。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（必填）' },
+                            module: { type: 'string', description: '模块名称（可选，默认 currentModule）' },
+                            moduleUpdate: {
+                                type: 'object',
+                                description: '模块层更新（可选）',
+                                properties: {
+                                    status: { type: 'string', enum: ['active', 'completed', 'archived'] },
+                                    summary: { type: 'string' },
+                                    todos: { type: 'array', items: { type: 'string' } },
+                                    addTodos: { type: 'array', items: { type: 'string' } },
+                                    removeTodos: { type: 'array', items: { type: 'string' } },
+                                    addDecision: {
+                                        type: 'object',
+                                        properties: {
+                                            description: { type: 'string' },
+                                            reason: { type: 'string' }
+                                        }
+                                    },
+                                    techStack: { type: 'array', items: { type: 'string' } }
+                                }
+                            },
+                            session: {
+                                type: 'object',
+                                description: '创建新会话（可选）',
+                                properties: {
+                                    note: { type: 'string', description: '会话摘要' },
+                                    codeState: {
+                                        type: 'object',
+                                        properties: {
+                                            modifiedFiles: { type: 'array', items: { type: 'string' } },
+                                            currentBranch: { type: 'string' },
+                                            uncommittedChanges: { type: 'string' }
+                                        }
+                                    },
+                                    todos: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                task: { type: 'string' },
+                                                priority: { type: 'string', enum: ['high', 'medium', 'low'] },
+                                                done: { type: 'boolean' }
+                                            }
+                                        }
+                                    },
+                                    decisions: {
+                                        type: 'array',
+                                        items: {
+                                            type: 'object',
+                                            properties: {
+                                                description: { type: 'string' },
+                                                reason: { type: 'string' },
+                                                alternatives: { type: 'array', items: { type: 'string' } }
+                                            }
+                                        }
+                                    },
+                                    techStack: { type: 'array', items: { type: 'string' } }
+                                },
+                                required: ['note']
+                            },
+                            newPitfall: {
+                                type: 'object',
+                                description: '记录新踩坑（可选）',
+                                properties: {
+                                    problem: { type: 'string' },
+                                    solution: { type: 'string' },
+                                    tags: { type: 'array', items: { type: 'string' } }
+                                },
+                                required: ['problem', 'solution']
+                            }
+                        },
+                        required: ['project']
+                    }
+                },
+                {
+                    name: 'list_modules',
+                    description: '列出项目或模块。不传 project 时列出所有项目；传 project 时列出该项目内模块。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（可选，不传则列出所有项目）' },
+                            status: { type: 'string', enum: ['active', 'completed', 'archived'], description: '按状态过滤模块' },
+                            includeArchived: { type: 'boolean', description: '是否包含已归档模块（默认 false）' },
+                            withStats: { type: 'boolean', description: '是否包含统计数据（默认 true）' }
+                        }
+                    }
+                },
+                {
+                    name: 'list_pitfalls',
+                    description: '列出踩坑记录。支持按项目、模块、标签过滤。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（可选）' },
+                            module: { type: 'string', description: '模块名称（可选）' },
+                            tags: { type: 'array', items: { type: 'string' }, description: '标签过滤' },
+                            limit: { type: 'number', description: '返回数量限制（默认 20）' }
+                        }
+                    }
+                },
+                {
+                    name: 'delete_data',
+                    description: '删除数据。支持删除会话、踩坑、模块或整个项目。参数互斥，只能指定一种删除类型。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（必填）' },
+                            sessionId: { type: 'string', description: '删除指定会话' },
+                            pitfallId: { type: 'string', description: '删除指定踩坑' },
+                            moduleName: { type: 'string', description: '删除指定模块（会级联删除关联的会话和踩坑）' },
+                            entireProject: { type: 'boolean', description: '删除整个项目' }
+                        },
+                        required: ['project']
+                    }
+                },
+                {
+                    name: 'export_handoff',
+                    description: '导出让其他 AI 使用的交接文档（Markdown 格式）。包含项目的全量数据。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            project: { type: 'string', description: '项目名称（必填）' },
+                            includeModules: { type: 'boolean', description: '是否包含模块详情（默认 true）' },
+                            includeSessions: { type: 'boolean', description: '是否包含会话历史（默认 true）' },
+                            includePitfalls: { type: 'boolean', description: '是否包含踩坑记录（默认 true）' }
+                        },
+                        required: ['project']
+                    }
+                },
+                {
+                    name: 'import_handoff',
+                    description: '从交接文档导入项目上下文。',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            handoffId: { type: 'string', description: '交接文档 ID（与 markdown 二选一）' },
+                            markdown: { type: 'string', description: '交接文档内容（与 handoffId 二选一）' },
+                            projectName: { type: 'string', description: '导入后的项目名（可选，默认使用文档中的）' },
+                            aiTool: { type: 'string', description: '来源 AI 工具名' }
+                        }
+                    }
+                }
+            ]
+        }));
+        // 处理工具调用
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case 'load_context': {
+                        const input = LoadContextSchema.parse(args);
+                        const result = await this.contextManager.loadContext(input);
+                        if (!result) {
+                            return {
+                                content: [{ type: 'text', text: JSON.stringify({ error: '项目或模块不存在' }, null, 2) }],
+                                isError: true
+                            };
+                        }
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'save_context': {
+                        const input = SaveContextSchema.parse(args);
+                        const result = await this.contextManager.saveContext(input);
+                        if (!result) {
+                            return {
+                                content: [{ type: 'text', text: JSON.stringify({ error: '保存失败' }, null, 2) }],
+                                isError: true
+                            };
+                        }
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'list_modules': {
+                        const input = ListModulesSchema.parse(args);
+                        const result = await this.moduleManager.listModules(input);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'list_pitfalls': {
+                        const input = ListPitfallsSchema.parse(args);
+                        const result = await this.pitfallManager.listPitfalls(input);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'delete_data': {
+                        const input = DeleteDataSchema.parse(args);
+                        const result = await this.deleteManager.deleteData(input);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'export_handoff': {
+                        const input = ExportHandoffSchema.parse(args);
+                        const result = await this.handoffManager.exportHandoff(input);
+                        if (!result) {
+                            return {
+                                content: [{ type: 'text', text: JSON.stringify({ error: '项目不存在' }, null, 2) }],
+                                isError: true
+                            };
+                        }
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    case 'import_handoff': {
+                        const input = ImportHandoffSchema.parse(args);
+                        const result = await this.handoffManager.importHandoff(input);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+                        };
+                    }
+                    default:
+                        throw new McpError(ErrorCode.MethodNotFound, `未知工具: ${name}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    const issues = error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; ');
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: `参数校验失败: ${issues}` }, null, 2) }],
+                        isError: true
+                    };
+                }
+                if (error instanceof Error) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({ error: error.message }, null, 2) }],
+                        isError: true
+                    };
+                }
+                throw error;
+            }
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Session Handoff MCP Server v2.0.0 running on stdio');
+        console.error(`Storage directory: ${this.storage.getBaseDir()}`);
+    }
+}
+// 启动服务器
+const server = new SessionHandoffServer();
+server.run().catch(console.error);
+//# sourceMappingURL=index.js.map