memtrace-mcp-server 1.0.0 → 1.0.1

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__memtrace__pull_knowledge",
+      "mcp__memtrace__get_startup_context",
+      "mcp__memtrace__search_knowledge"
+    ]
+  }
+}

package/PUBLISH.md

@@ -0,0 +1,40 @@
+# 发布 MCP Server 到 NPM
+
+## 发布步骤
+
+1. 登录 NPM（如果还没登录）：
+```bash
+npm login
+```
+
+2. 更新版本号：
+```bash
+# 补丁版本（bug fix）
+npm version patch
+
+# 小版本（新功能）
+npm version minor
+
+# 大版本（破坏性更新）
+npm version major
+```
+
+3. 发布：
+```bash
+npm publish
+```
+
+## 用户更新方式
+
+发布后，用户会自动获取最新版本：
+
+### 方式 1：npx -y（推荐，自动最新）
+配置文件中使用 `npx -y memtrace-mcp-server`，每次启动自动使用最新版
+
+### 方式 2：重启 Claude Code
+用户只需重启 Claude Code / Cursor，npx 会自动下载最新版
+
+### 方式 3：清除缓存（如果需要）
+```bash
+npx clear-npx-cache
+```

package/README.md

@@ -0,0 +1,200 @@
+# MemTrace MCP Server
+
+MCP (Model Context Protocol) server for [MemTrace](https://github.com/chaitin/memtrace) - an AI context memory service that helps AI assistants remember and retrieve information across conversations.
+
+## Features
+
+- 🔍 **Semantic Search**: Find relevant knowledge using natural language queries
+- 💾 **Knowledge Storage**: Store important information, decisions, and insights
+- 🧠 **LLM-Powered Extraction**: Automatically extract structured knowledge from text
+- 🔄 **Context Retrieval**: Get startup context and pull relevant knowledge
+- 🏷️ **Categorization**: Organize knowledge by categories (facts, preferences, decisions, etc.)
+
+## Installation
+
+### Option 1: npx (Recommended - Always Latest)
+
+No installation needed! Just configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "npx",
+      "args": ["-y", "memtrace-mcp-server"],
+      "env": {
+        "MEMTRACE_API_URL": "https://your-memtrace-server.com/api/v1",
+        "MEMTRACE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Global Installation
+
+```bash
+npm install -g memtrace-mcp-server
+```
+
+Then configure:
+
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "memtrace-mcp-server",
+      "env": {
+        "MEMTRACE_API_URL": "https://your-memtrace-server.com/api/v1",
+        "MEMTRACE_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Required Environment Variables
+
+- `MEMTRACE_TOKEN`: Your MemTrace API token (get it from your MemTrace dashboard)
+- `MEMTRACE_API_URL`: MemTrace API base URL (default: `http://localhost:3000/api/v1`)
+
+### Getting Your API Token
+
+1. Log in to your MemTrace instance
+2. Go to Dashboard → Tokens
+3. Create a new MCP token with required permissions
+4. Copy the token and add it to your configuration
+
+## Available Tools
+
+### search_knowledge
+
+Search for relevant knowledge using semantic search.
+
+```typescript
+search_knowledge({
+  query: "search query here",
+  limit: 10  // optional, default: 10
+})
+```
+
+### push_knowledge
+
+Store knowledge by submitting raw content. The server will automatically extract structured knowledge using LLM.
+
+**Important**: It's recommended to summarize/extract key points on the client side before pushing for better results.
+
+```typescript
+push_knowledge({
+  content: "Raw text content containing important information...",
+  project_id: "optional-project-id"  // optional
+})
+```
+
+**Content Size Limits** (per tier):
+- Free: 10,000 characters
+- Pro: 50,000 characters
+- Business: 100,000 characters
+
+### pull_knowledge
+
+Retrieve recent knowledge items.
+
+```typescript
+pull_knowledge({
+  limit: 10,  // optional, default: 10
+  category: "fact"  // optional: fact, preference, procedure, decision, insight, other
+})
+```
+
+### extract_knowledge
+
+Extract knowledge from text/conversation using LLM (preview mode, doesn't save unless `save: true`).
+
+```typescript
+extract_knowledge({
+  content: "Text to extract knowledge from...",
+  save: false,  // optional, default: false
+  project_id: "optional-project-id"  // optional
+})
+```
+
+### get_startup_context
+
+Get startup context with pinned knowledge and recent items for project initialization.
+
+```typescript
+get_startup_context({
+  project_id: "optional-project-id",  // optional
+  max_tokens: 4000  // optional, default: 4000
+})
+```
+
+## Usage Examples
+
+### With Claude Code
+
+1. Install Claude Code CLI
+2. Add MemTrace MCP server to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memtrace": {
+      "command": "npx",
+      "args": ["-y", "memtrace-mcp-server"],
+      "env": {
+        "MEMTRACE_API_URL": "https://your-memtrace-server.com/api/v1",
+        "MEMTRACE_TOKEN": "your-mcp-token-here"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Code
+
+### With Cursor
+
+1. Add to Cursor MCP configuration
+2. Restart Cursor
+
+## Rate Limits
+
+API rate limits vary by subscription tier:
+
+| Tier | Daily Limit | Burst (per minute) |
+|------|-------------|-------------------|
+| Free | 50 requests/day | 10 requests/min |
+| Pro | 200 requests/day | 30 requests/min |
+| Business | 1000 requests/day | 100 requests/min |
+
+## Troubleshooting
+
+### "MEMTRACE_TOKEN environment variable is required"
+
+Make sure you've set the `MEMTRACE_TOKEN` in your MCP server configuration.
+
+### "Failed to push knowledge"
+
+Check:
+1. Your API token is valid
+2. Content doesn't exceed tier limits
+3. Server logs for detailed error messages
+
+### Updating to Latest Version
+
+If using `npx -y`:
+- Just restart your MCP client (Claude Code / Cursor)
+- It will automatically fetch the latest version
+
+If using global installation:
+```bash
+npm update -g memtrace-mcp-server
+```
+
+## License
+
+MIT

package/index.js

@@ -79,40 +79,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'push_knowledge',
-        description: 'Store new knowledge items for future reference. Use this to save important information, decisions, preferences, or learnings.',
+        description: 'Store knowledge by submitting raw content. The server will automatically extract structured knowledge using LLM. Recommended to summarize/extract key points on client side before pushing for better results.',
         inputSchema: {
           type: 'object',
           properties: {
-            items: {
-              type: 'array',
-              description: 'Array of knowledge items to store',
-              items: {
-                type: 'object',
-                properties: {
-                  title: {
-                    type: 'string',
-                    description: 'Short descriptive title for the knowledge',
-                  },
-                  content: {
-                    type: 'string',
-                    description: 'The knowledge content to store',
-                  },
-                  category: {
-                    type: 'string',
-                    enum: ['fact', 'preference', 'procedure', 'decision', 'insight', 'other'],
-                    description: 'Category of the knowledge',
-                  },
-                  tags: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Tags for organizing the knowledge',
-                  },
-                },
-                required: ['title', 'content'],
-              },
+            content: {
+              type: 'string',
+              description: 'The raw text content to extract knowledge from and store. Can be conversation history, notes, or any text containing important information.',
+            },
+            project_id: {
+              type: 'string',
+              description: 'Optional project identifier to associate the knowledge with',
             },
           },
-          required: ['items'],
+          required: ['content'],
         },
       },
       {
@@ -132,6 +112,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
         },
       },
+      {
+        name: 'extract_knowledge',
+        description: 'Extract knowledge from text/conversation using LLM. Use this to analyze text and identify key facts, preferences, decisions, and insights that should be remembered.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            content: {
+              type: 'string',
+              description: 'The text or conversation content to extract knowledge from',
+            },
+            save: {
+              type: 'boolean',
+              description: 'If true, save extracted knowledge to the database (default: false)',
+            },
+            project_id: {
+              type: 'string',
+              description: 'Optional project identifier to associate with extracted knowledge',
+            },
+          },
+          required: ['content'],
+        },
+      },
       {
         name: 'get_startup_context',
         description: 'Get startup context including pinned knowledge and recent items. Call this at the beginning of a session.',
@@ -176,7 +178,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'push_knowledge': {
         const result = await apiCall('/mcp/knowledge/push', 'POST', {
-          items: args.items,
+          content: args.content,
+          project_id: args.project_id,
         });
         return {
           content: [
@@ -203,6 +206,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case 'extract_knowledge': {
+        const result = await apiCall('/mcp/knowledge/extract', 'POST', {
+          content: args.content,
+          save: args.save || false,
+          project_id: args.project_id,
+        });
+
+        let responseText = `Extracted ${result.items.length} knowledge item(s):\n\n`;
+        for (const item of result.items) {
+          responseText += `**${item.title}** (${item.category}, confidence: ${(item.confidence * 100).toFixed(0)}%)\n`;
+          responseText += `${item.content}\n`;
+          if (item.tags && item.tags.length > 0) {
+            responseText += `Tags: ${item.tags.join(', ')}\n`;
+          }
+          responseText += '\n';
+        }
+
+        if (result.saved) {
+          responseText += `\n✓ Knowledge items have been saved to the database.`;
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: responseText,
+            },
+          ],
+        };
+      }
+
       case 'get_startup_context': {
         const context = await apiCall('/context/startup', 'POST', {
           project_id: args.project_id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for MemTrace - AI context memory service",
   "main": "index.js",
   "type": "module",