diff options
Diffstat (limited to 'mcp-servers/memory-mcp-server/.claude/commands/setup.md')
| -rw-r--r-- | mcp-servers/memory-mcp-server/.claude/commands/setup.md | 381 |
1 files changed, 381 insertions, 0 deletions
diff --git a/mcp-servers/memory-mcp-server/.claude/commands/setup.md b/mcp-servers/memory-mcp-server/.claude/commands/setup.md new file mode 100644 index 0000000..5a9db1d --- /dev/null +++ b/mcp-servers/memory-mcp-server/.claude/commands/setup.md @@ -0,0 +1,381 @@ +--- +description: Initialize Memory MCP Server project from scratch +argument-hint: "[quick, full, or database]" +allowed-tools: Write, MultiEdit, Bash, Task, TodoWrite +--- + +# Memory MCP Server Setup + +Initialize and configure the Memory MCP Server project based on $ARGUMENTS: + +## Quick Setup + +Initialize minimal working MCP server with memory capabilities: + +```bash +# Initialize project +npm init -y +npm install @modelcontextprotocol/sdk zod dotenv +npm install -D typescript @types/node tsx nodemon +npm install @neondatabase/serverless drizzle-orm@^0.44.4 +npm install openai pgvector + +# Create TypeScript config +npx tsc --init +``` + +## Full Setup + +Complete project initialization with all features: + +### 1. Project Structure + +```text +memory-mcp-server/ +├── src/ +│ ├── index.ts # MCP server entry point +│ ├── server.ts # Server initialization +│ ├── tools/ # MCP tool implementations +│ │ ├── createMemory.ts +│ │ ├── searchMemories.ts +│ │ ├── getMemory.ts +│ │ ├── updateMemory.ts +│ │ └── deleteMemory.ts +│ ├── db/ +│ │ ├── client.ts # Database connection +│ │ ├── schema.ts # Drizzle schema +│ │ └── migrations/ # Database migrations +│ ├── services/ +│ │ ├── embeddings.ts # OpenAI embeddings +│ │ ├── vectorSearch.ts # pgvector operations +│ │ └── memoryLifecycle.ts # Memory management +│ ├── types/ +│ │ └── index.ts # TypeScript types +│ └── utils/ +│ ├── logger.ts # Structured logging +│ └── errors.ts # Error handling +├── tests/ +│ ├── unit/ +│ ├── integration/ +│ └── fixtures/ +├── .env.example +├── .mcp.json # MCP manifest +├── tsconfig.json +├── package.json +├── drizzle.config.ts +└── README.md +``` + +### 2. Package Dependencies + +```json +{ + "name": "memory-mcp-server", + "version": "1.0.0", + "type": "module", + "scripts": { + "dev": "tsx watch src/index.ts", + "build": "tsc", + "start": "node dist/index.js", + "test": "jest", + "test:watch": "jest --watch", + "test:coverage": "jest --coverage", + "lint": "eslint . --ext .ts", + "typecheck": "tsc --noEmit", + "db:generate": "drizzle-kit generate", + "db:migrate": "drizzle-kit migrate", + "db:studio": "drizzle-kit studio" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^1.0.0", + "@neondatabase/serverless": "^1.0.1", + "drizzle-orm": "^0.44.4", + "zod": "^4.0.17", + "openai": "^4.0.0", + "pgvector": "^0.2.0", + "dotenv": "^16.0.0", + "winston": "^3.0.0" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "typescript": "^5.0.0", + "tsx": "^4.0.0", + "nodemon": "^3.0.0", + "jest": "^29.0.0", + "@types/jest": "^29.0.0", + "ts-jest": "^29.0.0", + "eslint": "^8.0.0", + "@typescript-eslint/eslint-plugin": "^6.0.0", + "@typescript-eslint/parser": "^6.0.0", + "drizzle-kit": "^0.32.0" + } +} +``` + +### 3. TypeScript Configuration + +```json +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "lib": ["ES2022"], + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "tests"] +} +``` + +### 4. Environment Variables + +```bash +# .env +DATABASE_URL="postgresql://user:pass@host/dbname?sslmode=require" +OPENAI_API_KEY="sk-..." +MCP_SERVER_PORT=3000 +LOG_LEVEL=info +NODE_ENV=development + +# Vector search settings +VECTOR_SEARCH_LIMIT=10 +SIMILARITY_THRESHOLD=0.7 + +# Memory lifecycle +MEMORY_EXPIRATION_DAYS=90 +MAX_MEMORIES_PER_USER=10000 +IMPORTANCE_DECAY_RATE=0.1 +``` + +### 5. MCP Manifest + +```json +{ + "name": "memory-mcp-server", + "version": "1.0.0", + "description": "Persistent memory management for AI assistants", + "author": "Your Name", + "license": "MIT", + "server": { + "command": "node", + "args": ["dist/index.js"], + "transport": "stdio" + }, + "tools": { + "create_memory": { + "description": "Create a new memory with vector embedding", + "inputSchema": { + "type": "object", + "properties": { + "content": { "type": "string" }, + "type": { "type": "string" }, + "importance": { "type": "number" }, + "expires_at": { "type": "string" } + }, + "required": ["content", "type"] + } + }, + "search_memories": { + "description": "Search memories using semantic similarity", + "inputSchema": { + "type": "object", + "properties": { + "query": { "type": "string" }, + "limit": { "type": "number" }, + "threshold": { "type": "number" } + }, + "required": ["query"] + } + } + } +} +``` + +## Database Setup + +Initialize Neon PostgreSQL with pgvector: + +### 1. Create Database + +```sql +-- Enable pgvector extension +CREATE EXTENSION IF NOT EXISTS vector; + +-- Create database schema +CREATE SCHEMA IF NOT EXISTS memory_mcp; +``` + +### 2. Drizzle Schema + +```typescript +// src/db/schema.ts +import { pgTable, uuid, text, timestamp, boolean, real, vector, index, jsonb } from 'drizzle-orm/pg-core'; + +export const users = pgTable('users', { + id: uuid('id').primaryKey().defaultRandom(), + external_id: text('external_id').notNull().unique(), + created_at: timestamp('created_at').defaultNow().notNull(), + metadata: jsonb('metadata') +}); + +export const companions = pgTable('companions', { + id: uuid('id').primaryKey().defaultRandom(), + name: text('name').notNull(), + user_id: uuid('user_id').references(() => users.id), + created_at: timestamp('created_at').defaultNow().notNull(), + is_active: boolean('is_active').default(true) +}); + +export const memories = pgTable('memories', { + id: uuid('id').primaryKey().defaultRandom(), + companion_id: uuid('companion_id').references(() => companions.id), + user_id: uuid('user_id').references(() => users.id), + content: text('content').notNull(), + type: text('type').notNull(), + embedding: vector('embedding', { dimensions: 1536 }), + importance: real('importance').default(0.5), + access_count: integer('access_count').default(0), + last_accessed: timestamp('last_accessed'), + expires_at: timestamp('expires_at'), + is_archived: boolean('is_archived').default(false), + created_at: timestamp('created_at').defaultNow().notNull(), + updated_at: timestamp('updated_at').defaultNow().notNull() +}, (table) => ({ + embeddingIdx: index('memories_embedding_idx') + .using('ivfflat', table.embedding.op('vector_cosine_ops')) + .with({ lists: 100 }), + userIdx: index('memories_user_idx').on(table.user_id), + companionIdx: index('memories_companion_idx').on(table.companion_id), + typeIdx: index('memories_type_idx').on(table.type) +})); +``` + +### 3. Migration Commands + +```bash +# Generate migration +npx drizzle-kit generate + +# Run migrations +npx drizzle-kit migrate + +# Open Drizzle Studio +npx drizzle-kit studio +``` + +## Initial Server Implementation + +```typescript +// src/index.ts +import { Server } from '@modelcontextprotocol/sdk/server/index.js'; +import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; +import { z } from 'zod'; +import { createMemoryTool } from './tools/createMemory.js'; +import { searchMemoriesTool } from './tools/searchMemories.js'; + +const server = new Server({ + name: 'memory-mcp-server', + version: '1.0.0' +}, { + capabilities: { + tools: {} + } +}); + +// Register tools +server.setRequestHandler('tools/list', async () => ({ + tools: [ + createMemoryTool.definition, + searchMemoriesTool.definition + ] +})); + +server.setRequestHandler('tools/call', async (request) => { + const { name, arguments: args } = request.params; + + switch (name) { + case 'create_memory': + return await createMemoryTool.handler(args); + case 'search_memories': + return await searchMemoriesTool.handler(args); + default: + throw new Error(`Unknown tool: ${name}`); + } +}); + +// Start server +const transport = new StdioServerTransport(); +await server.connect(transport); +console.log('Memory MCP Server started'); +``` + +## Testing Setup + +```bash +# Install test dependencies +npm install -D jest @types/jest ts-jest + +# Create Jest config +npx ts-jest config:init + +# Run tests +npm test +``` + +## Development Workflow + +```bash +# Start development server +npm run dev + +# In another terminal, test MCP connection +npx @modelcontextprotocol/cli connect stdio "npm run start" + +# Test tool execution +npx @modelcontextprotocol/cli call create_memory '{"content": "Test memory"}' +``` + +## Production Deployment + +```dockerfile +# Dockerfile +FROM node:20-alpine +WORKDIR /app +COPY package*.json ./ +RUN npm ci --only=production +COPY dist ./dist +CMD ["node", "dist/index.js"] +``` + +## Monitoring & Observability + +```typescript +// src/utils/logger.ts +import winston from 'winston'; + +export const logger = winston.createLogger({ + level: process.env.LOG_LEVEL || 'info', + format: winston.format.json(), + transports: [ + new winston.transports.Console(), + new winston.transports.File({ filename: 'error.log', level: 'error' }), + new winston.transports.File({ filename: 'combined.log' }) + ] +}); +``` + +This setup provides a complete foundation for the Memory MCP Server with all necessary configurations and best practices. |