memtrace-mcp-server 1.0.0 → 1.0.2

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.\n\n**IMPORTANT - Content Size Limits (by tier):**\n- Free tier: 10,000 characters max\n- Pro tier: 50,000 characters max\n- Business tier: 100,000 characters max\n\n**Rate Limits (by tier):**\n- Free: 50 requests/day, 10 requests/min\n- Pro: 200 requests/day, 30 requests/min\n- Business: 1000 requests/day, 100 requests/min\n\n**Best Practices:**\n1. Summarize and extract key points on client side before pushing\n2. Focus on important information worth remembering\n3. Keep content concise to avoid hitting limits\n4. Split large content into multiple logical chunks if needed',
         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: 'Raw text content to extract knowledge from and store. Must not exceed your tier\'s character limit (Free: 10K, Pro: 50K, Business: 100K). Recommended: summarize key points before submitting to stay well under the limit.',
+            },
+            project_id: {
+              type: 'string',
+              description: 'Optional project identifier to associate the knowledge with',
             },
           },
-          required: ['items'],
+          required: ['content'],
         },
       },
       {
@@ -176,7 +156,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: [

package/package.json

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