claude-mem 3.3.7 → 3.3.9

package/docs/reference/mcp-sdk/server-implementation.md

@@ -0,0 +1,286 @@
+# MCP TypeScript SDK Server Implementation Guide
+
+## Documentation Source
+- **SDK Version**: @modelcontextprotocol/sdk v1.0.0
+- **Last Verified**: 2025-09-01
+- **Official Docs**: https://github.com/modelcontextprotocol/typescript-sdk
+
+## Server Creation Patterns
+
+### Low-Level Server vs McpServer
+
+The SDK provides two approaches for creating MCP servers:
+
+1. **Low-Level Server Class** (Used in claude-mem)
+   - Direct control over request handling
+   - Manual registration with `setRequestHandler`
+   - More flexibility for custom routing logic
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+const server = new Server(
+  {
+    name: 'server-name',
+    version: '1.0.0'
+  },
+  {
+    capabilities: {
+      tools: {}  // Declare tool capability
+    }
+  }
+);
+```
+
+2. **High-Level McpServer Class** (Alternative approach)
+   - Simplified API with `registerTool`, `registerResource`, `registerPrompt`
+   - Automatic routing and validation
+   - Less boilerplate code
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+const server = new McpServer({
+  name: 'server-name',
+  version: '1.0.0'
+});
+```
+
+## Tool Handler Registration
+
+### Pattern 1: Single Handler with CallToolRequestSchema (claude-mem approach)
+
+```typescript
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  // Validate arguments exist
+  if (!args) {
+    throw new Error(`No arguments provided for tool: ${name}`);
+  }
+  
+  // Route to specific tool implementation
+  switch (name) {
+    case 'tool-name':
+      // Tool implementation
+      return {
+        content: [{
+          type: 'text',
+          text: 'Result'
+        }]
+      };
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+```
+
+### Pattern 2: Individual Tool Registration (McpServer approach)
+
+```typescript
+server.registerTool(
+  'tool-name',
+  {
+    title: 'Tool Title',
+    description: 'Tool description',
+    inputSchema: { param: z.string() }
+  },
+  async ({ param }) => ({
+    content: [{
+      type: 'text',
+      text: `Result for ${param}`
+    }]
+  })
+);
+```
+
+## Stdio Transport Usage
+
+### Standard Pattern for CLI-based Servers
+
+```typescript
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+async function main() {
+  // 1. Initialize backend services first
+  await initializeBackend();
+  
+  // 2. Create transport
+  const transport = new StdioServerTransport();
+  
+  // 3. Connect server to transport
+  await server.connect(transport);
+  
+  // 4. Log to stderr (stdout is for protocol)
+  console.error('Server started on stdio');
+}
+```
+
+### Key Points:
+- **Stdin**: Receives MCP protocol messages
+- **Stdout**: Sends MCP protocol responses
+- **Stderr**: Used for logging and diagnostics
+
+## Error Handling Patterns
+
+### Tool Error Response
+
+```typescript
+try {
+  // Tool implementation
+  return {
+    content: [{
+      type: 'text',
+      text: 'Success result'
+    }]
+  };
+} catch (error) {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  
+  // Log to stderr for debugging
+  console.error(`[Error] Tool: ${name}, Error: ${errorMessage}`);
+  
+  // Return error response with isError flag
+  return {
+    content: [{
+      type: 'text',
+      text: `Error: ${errorMessage}`
+    }],
+    isError: true  // Important: Indicates tool failure
+  };
+}
+```
+
+### Startup Error Handling
+
+```typescript
+main().catch((error) => {
+  console.error('Startup error:', error);
+  process.exit(1);  // Exit with error code
+});
+```
+
+## Response Formatting
+
+### Success Response Structure
+
+```typescript
+{
+  content: [
+    {
+      type: 'text',
+      text: 'Response text'
+    }
+  ]
+}
+```
+
+### Error Response Structure
+
+```typescript
+{
+  content: [
+    {
+      type: 'text',
+      text: 'Error: Description'
+    }
+  ],
+  isError: true
+}
+```
+
+### Resource Link Response
+
+```typescript
+{
+  content: [
+    {
+      type: 'resource_link',
+      uri: 'file:///path/to/resource',
+      name: 'Resource Name',
+      mimeType: 'text/plain',
+      description: 'Resource description'
+    }
+  ]
+}
+```
+
+## Lifecycle Management
+
+### Initialization Pattern
+
+```typescript
+async function initializeServer(): Promise<void> {
+  try {
+    // Initialize backend connections
+    await backend.connect();
+    console.error('Backend initialized');
+  } catch (error) {
+    console.error('Initialization failed:', error);
+    throw error;  // Prevent server startup
+  }
+}
+```
+
+### Shutdown Pattern
+
+```typescript
+function setupShutdownHandlers(): void {
+  const handleShutdown = async (signal: string) => {
+    console.error(`Received ${signal}, shutting down...`);
+    
+    try {
+      await backend.disconnect();
+      process.exit(0);  // Clean exit
+    } catch (error) {
+      console.error('Shutdown error:', error);
+      process.exit(1);  // Error exit
+    }
+  };
+  
+  process.on('SIGINT', () => handleShutdown('SIGINT'));
+  process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+  
+  // Handle unexpected errors
+  process.on('uncaughtException', async (error) => {
+    console.error('Uncaught exception:', error);
+    await backend.disconnect();
+    process.exit(1);
+  });
+}
+```
+
+## Best Practices Summary
+
+1. **Server Creation**
+   - Use low-level Server for custom routing
+   - Use McpServer for standard implementations
+
+2. **Transport Usage**
+   - Initialize backends before connecting transport
+   - Use StdioServerTransport for CLI tools
+   - Log to stderr, not stdout
+
+3. **Error Handling**
+   - Always validate tool arguments
+   - Include isError flag in error responses
+   - Log errors to stderr with context
+
+4. **Response Format**
+   - Always return content array
+   - Use consistent type/text structure
+   - Include isError for failures
+
+5. **Lifecycle**
+   - Clean initialization sequence
+   - Graceful shutdown handlers
+   - Proper exit codes (0 for success, 1 for error)
+
+## References
+
+- [MCP TypeScript SDK README](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Low-Level Server Pattern](https://github.com/modelcontextprotocol/typescript-sdk#low-level-server-implementation)
+- [Stdio Transport Example](https://github.com/modelcontextprotocol/typescript-sdk#stdio-transport)
+- [Error Handling Examples](https://github.com/modelcontextprotocol/typescript-sdk#sqlite-explorer)

package/docs/reference/mcp-sdk/stdio-transport.md

@@ -0,0 +1,345 @@
+# MCP TypeScript SDK Stdio Transport Guide
+
+## Documentation Source
+- **SDK Version**: @modelcontextprotocol/sdk v1.0.0
+- **Last Verified**: 2025-09-01
+- **Official Docs**: https://github.com/modelcontextprotocol/typescript-sdk
+
+## Stdio Transport Overview
+
+The StdioServerTransport enables MCP servers to communicate via standard input/output streams, making them ideal for CLI tools and direct integrations with Claude Code.
+
+## Communication Channels
+
+### Stream Usage
+- **stdin**: Receives MCP protocol messages (JSON-RPC)
+- **stdout**: Sends MCP protocol responses (JSON-RPC)
+- **stderr**: Logging and diagnostic output
+
+### Important Rules
+1. **Never write non-protocol data to stdout** - This will break the protocol
+2. **Always use console.error() for logging** - Goes to stderr
+3. **Handle binary data carefully** - Protocol is text-based JSON
+
+## Implementation Patterns
+
+### Basic Stdio Server Setup
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+// Create server
+const server = new Server(
+  { name: 'my-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+// Create and connect transport
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Server is now listening on stdin/stdout
+console.error('Server started'); // Note: console.error for logging
+```
+
+### With McpServer (High-Level API)
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const server = new McpServer({
+  name: 'my-server',
+  version: '1.0.0'
+});
+
+// Register tools, resources, prompts...
+server.registerTool(...);
+
+// Connect to stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## CLI Entry Point Pattern
+
+### Proper Module Detection (ES Modules)
+
+```typescript
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Only run if executed directly
+if (process.argv[1] === __filename || 
+    process.argv[1].endsWith('server.js')) {
+  main().catch((error) => {
+    console.error('Startup error:', error);
+    process.exit(1);
+  });
+}
+```
+
+### Main Function Pattern
+
+```typescript
+async function main(): Promise<void> {
+  try {
+    // 1. Initialize dependencies
+    await initializeDatabase();
+    
+    // 2. Create server
+    const server = createServer();
+    
+    // 3. Create transport
+    const transport = new StdioServerTransport();
+    
+    // 4. Connect
+    await server.connect(transport);
+    
+    // 5. Setup shutdown handlers
+    setupShutdownHandlers();
+    
+    // 6. Log readiness to stderr
+    console.error('MCP server ready on stdio');
+    
+  } catch (error) {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+  }
+}
+```
+
+## Shutdown Handling
+
+### Graceful Shutdown Pattern
+
+```typescript
+function setupShutdownHandlers(): void {
+  const shutdown = async (signal: string) => {
+    console.error(`\nReceived ${signal}, shutting down...`);
+    
+    try {
+      // Clean up resources
+      await cleanupResources();
+      
+      // Note: Transport cleanup is handled automatically
+      process.exit(0);
+    } catch (error) {
+      console.error('Shutdown error:', error);
+      process.exit(1);
+    }
+  };
+  
+  // Handle termination signals
+  process.on('SIGINT', () => shutdown('SIGINT'));   // Ctrl+C
+  process.on('SIGTERM', () => shutdown('SIGTERM')); // Kill
+  process.on('SIGHUP', () => shutdown('SIGHUP'));   // Terminal closed
+  
+  // Handle errors
+  process.on('uncaughtException', (error) => {
+    console.error('Uncaught exception:', error);
+    process.exit(1);
+  });
+  
+  process.on('unhandledRejection', (reason) => {
+    console.error('Unhandled rejection:', reason);
+    process.exit(1);
+  });
+}
+```
+
+## Logging Best Practices
+
+### Do's and Don'ts
+
+```typescript
+// ✅ DO: Log to stderr
+console.error('Server initialized');
+console.error('Processing request:', requestId);
+console.error('Debug info:', { data });
+
+// ❌ DON'T: Log to stdout
+console.log('This breaks the protocol!'); // NEVER DO THIS
+
+// ✅ DO: Use structured logging to stderr
+const log = (level: string, message: string, data?: any) => {
+  console.error(JSON.stringify({
+    timestamp: new Date().toISOString(),
+    level,
+    message,
+    ...data
+  }));
+};
+
+log('info', 'Server started', { port: 'stdio' });
+```
+
+### Debug Mode Pattern
+
+```typescript
+const DEBUG = process.env.DEBUG === 'true';
+
+const debug = (message: string, ...args: any[]) => {
+  if (DEBUG) {
+    console.error(`[DEBUG] ${message}`, ...args);
+  }
+};
+
+// Usage
+debug('Request received:', request);
+```
+
+## Testing Stdio Servers
+
+### Manual Testing
+
+```bash
+# Start server and interact manually
+node dist/server.js
+
+# With debug logging
+DEBUG=true node dist/server.js
+
+# Pipe test input
+echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | node dist/server.js
+```
+
+### Automated Testing Pattern
+
+```typescript
+import { spawn } from 'child_process';
+
+function testServer() {
+  const server = spawn('node', ['dist/server.js']);
+  
+  // Capture stderr for logs
+  server.stderr.on('data', (data) => {
+    console.log('Server log:', data.toString());
+  });
+  
+  // Capture stdout for protocol
+  let response = '';
+  server.stdout.on('data', (data) => {
+    response += data.toString();
+    // Parse and validate response
+  });
+  
+  // Send test request
+  server.stdin.write(JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'initialize',
+    params: {},
+    id: 1
+  }));
+  server.stdin.end();
+}
+```
+
+## Common Issues and Solutions
+
+### Issue 1: Protocol Corruption
+
+**Problem**: Random text in stdout breaks communication
+**Solution**: Always use console.error() for logging
+
+```typescript
+// Wrong
+console.log('Debug:', data); // Breaks protocol
+
+// Right
+console.error('Debug:', data); // Safe for debugging
+```
+
+### Issue 2: Server Not Responding
+
+**Problem**: Server starts but doesn't respond to requests
+**Solution**: Ensure transport is connected
+
+```typescript
+// Check connection is awaited
+await server.connect(transport); // Must await!
+console.error('Transport connected');
+```
+
+### Issue 3: Premature Exit
+
+**Problem**: Server exits immediately
+**Solution**: Don't close stdin/stdout
+
+```typescript
+// Wrong
+process.stdin.end(); // Don't do this
+
+// Right
+// Let the transport manage streams
+```
+
+## Integration with Claude Code
+
+### Configuration in .claude.json
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "node",
+      "args": ["/path/to/dist/server.js"],
+      "env": {
+        "DEBUG": "false"
+      }
+    }
+  }
+}
+```
+
+### Best Practices for Claude Code Integration
+
+1. **Startup Messages**: Log clear startup messages to stderr
+2. **Error Messages**: Provide actionable error messages
+3. **Ready Signal**: Log when server is ready to accept requests
+4. **Version Info**: Include version in startup logs
+
+```typescript
+console.error(`Starting ${serverName} v${version}`);
+console.error('Initializing...');
+// ... initialization ...
+console.error(`${serverName} ready on stdio`);
+```
+
+## Performance Considerations
+
+### Buffering and Streaming
+
+```typescript
+// For large responses, consider streaming
+import { Transform } from 'stream';
+
+class ResponseStream extends Transform {
+  _transform(chunk: any, encoding: string, callback: Function) {
+    // Process chunk
+    this.push(JSON.stringify(chunk));
+    callback();
+  }
+}
+```
+
+### Memory Management
+
+```typescript
+// Clear large objects after use
+let largeData = await processData();
+// Use data...
+largeData = null; // Allow GC
+```
+
+## References
+
+- [StdioServerTransport Docs](https://github.com/modelcontextprotocol/typescript-sdk#stdio-transport)
+- [Server Examples](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/src/examples/server)
+- [MCP Protocol Specification](https://modelcontextprotocol.io/docs)

package/docs/todos/fix-response-format-tasks.md

@@ -0,0 +1,43 @@
+# Todo: Fix Response Format Issue
+
+## Immediate Tasks
+
+### 1. Simplify Analysis Prompt
+- [ ] Open `src/prompts/templates/analysis/AnalysisTemplates.ts`
+- [ ] Remove MCP tool instructions from `buildCompleteAnalysisPrompt`
+- [ ] Remove the entity extraction section
+- [ ] Focus prompt solely on generating pipe-separated summaries
+- [ ] Ensure examples clearly show the 5-part format
+
+### 2. Fix Parser Validation
+- [ ] Open `src/core/compression/TranscriptCompressor.ts`
+- [ ] Update `extractPipeSeparatedLines` to validate exactly 5 parts
+- [ ] Change condition from `>= 3` to `=== 5`
+- [ ] Add debug logging for rejected lines
+
+### 3. Add Better Error Handling
+- [ ] Log the actual format when parsing fails
+- [ ] Show first few lines of response in error messages
+- [ ] Add format validation feedback
+
+### 4. Test Changes
+- [ ] Run `npm run build` to verify no TypeScript errors
+- [ ] Test compression on a sample transcript
+- [ ] Verify pipe-separated output is generated
+- [ ] Check that summaries are extracted to index
+
+### 5. Verify Fix
+- [ ] Run compression on previous failed sessions if possible
+- [ ] Confirm summaries are now extracted
+- [ ] Check archive files contain summaries
+- [ ] Verify no "NO SUMMARIES EXTRACTED" errors
+
+## Files to Modify
+1. `src/prompts/templates/analysis/AnalysisTemplates.ts` - Simplify prompt
+2. `src/core/compression/TranscriptCompressor.ts` - Fix parser validation
+3. `src/shared/logger.ts` - Add better error context (optional)
+
+## Expected Outcome
+- Claude returns clean pipe-separated lines
+- Parser successfully extracts 3-10 summaries
+- Sessions are properly indexed for future reference