Skip to content

MCP_IMPLEMENTATION.md

Latest commit

 

History

History
392 lines (311 loc) · 9.66 KB

MCP_IMPLEMENTATION.md

File metadata and controls

392 lines (311 loc) · 9.66 KB

MCP Implementation v0.2.0

Overview

Version 0.2.0 is a major refactor from hybrid CLI+MCP to pure MCP server with comprehensive tool suite and MCP Resources support.

What Changed

Architecture Transformation

From (v0.1.0):

  • CLI as primary interface (odsp-memory command)
  • MCP server as secondary mode
  • 8 basic MCP tools

To (v0.2.0):

  • Pure MCP server - Primary and only entry point
  • 15 comprehensive MCP tools - Full feature parity
  • MCP Resources - Browse memories as resources
  • No CLI interface (removed complexity)

Why MCP-Only?

  1. Better Integration - Tools appear natively in Claude
  2. Cleaner UX - No bash command clutter
  3. Automatic Context - Claude can proactively use tools
  4. Simpler Maintenance - Single code path
  5. Resources Support - Browse memories like files

New Features (v0.2.0)

MCP Resources

Memories can be browsed as resources:

memory://list                    → All memories (JSON)
memory://{id}                    → Specific memory (Markdown)
memory://project/{project-id}    → Project memories (JSON)
memory://category/{category}     → Category memories (JSON)

Benefits:

  • Native browsing in MCP clients
  • Read memories without tool calls
  • Organized by project/category
  • Human-readable markdown format

Expanded Tool Set (16 Tools)

Core Operations (9 tools):

  1. remember - Store memory
  2. recall - Search memories
  3. list - List with filters
  4. forget - Delete memory
  5. update - Update content/tags
  6. get_context - Smart project context
  7. cleanup - Remove expired
  8. status - System status
  9. configure_storage - Select OneDrive or set custom path

Advanced Operations (7 tools): 9. link_memories - Link/unlink two memories 10. get_related - Get linked memories 11. merge_memories - Merge multiple into one 12. batch_tag - Add/remove tags in bulk 13. batch_delete - Delete multiple (with filters) 14. get_statistics - Comprehensive analytics 15. visualize_graph - Mermaid relationship diagram 16. export_memories - Export to JSON/Markdown

Previously CLI-only, now in MCP:

  • Memory relationships (link, related, merge)
  • Batch operations (tag, untag, delete)
  • Analytics (stats, graph, export)

Storage Configuration

Flexible Storage Options:

  • Auto-detect OneDrive folders (commercial, consumer)
  • Support for multiple OneDrive accounts
  • Custom storage paths (any folder location)
  • Persistent configuration saved to ~/.claude/odsp-memory/config.json

Detection Priority:

  1. Saved preference (if exists)
  2. Auto-detected OneDrive (prioritizes work/school accounts)
  3. Prompts user if multiple folders detected
  4. Allows custom path configuration

Storage Paths:

  • OneDrive: {folder}/Apps/ClaudeMemory/
  • Custom: Uses specified path directly

Implementation Details

Single Entry Point

File: src/mcp-server.ts Executable: dist/mcp-server.js Invocation: npx @patrick-rodgers/claude-onedrive-memory

Architecture

src/
├── mcp-server.ts         # Main MCP server (ONLY entry point)
├── commands/             # Reusable command logic
│   ├── remember.ts
│   ├── recall.ts
│   ├── list.ts
│   ├── forget.ts
│   ├── update.ts
│   ├── context.ts
│   ├── cleanup.ts
│   ├── status.ts
│   └── index.ts
├── memory.ts            # Core memory operations
├── analytics.ts         # Statistics and graphs
├── batch.ts             # Batch operations
├── search.ts            # Search and ranking
├── storage.ts           # OneDrive detection
├── project.ts           # Git project context
├── triggers.ts          # File pattern detection
└── types.ts             # TypeScript types

Resource Handler

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  // Returns list of browsable resources:
  // - memory://list
  // - memory://{id} for each memory
  // - memory://project/{id} for projects
  // - memory://category/{name} for categories
});

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  // Reads specific resource by URI
  // Returns JSON or Markdown based on resource type
});

Tool Handler

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case 'remember': /* ... */
    case 'recall': /* ... */
    // ... 15 total tools
  }
});

Package Configuration

{
  "name": "@patrick-rodgers/claude-onedrive-memory",
  "version": "0.2.0",
  "description": "Persistent memory for Claude using OneDrive - MCP server with resources",
  "main": "dist/mcp-server.js",
  "bin": {
    "claude-onedrive-memory": "dist/mcp-server.js"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4",
    "gray-matter": "^4.0.3",
    "uuid": "^9.0.0"
  }
}

Usage

Installation

Claude Desktop:

{
  "mcpServers": {
    "claude-onedrive-memory": {
      "command": "npx",
      "args": ["@patrick-rodgers/claude-onedrive-memory"]
    }
  }
}

Claude Code CLI:

{
  "mcpServers": {
    "claude-onedrive-memory": {
      "command": "npx",
      "args": ["@patrick-rodgers/claude-onedrive-memory"]
    }
  }
}

Local Development:

{
  "mcpServers": {
    "claude-onedrive-memory": {
      "command": "node",
      "args": ["/path/to/dist/mcp-server.js"]
    }
  }
}

Example Tool Calls

Basic operations:

// Store memory
{ tool: "remember", category: "project", content: "Uses React" }

// Search
{ tool: "recall", query: "React", limit: 5 }

// Smart context
{ tool: "get_context", limit: 5 }

Advanced operations:

// Link memories
{ tool: "link_memories", id1: "abc", id2: "def", operation: "link" }

// Merge memories
{ tool: "merge_memories", ids: ["abc", "def", "ghi"] }

// Batch tag
{ tool: "batch_tag", tag: "important", operation: "add", category: "decision" }

// Statistics
{ tool: "get_statistics" }

// Export
{ tool: "export_memories", format: "json" }

Example Resource Reads

// List all memories
ReadResource("memory://list")

// Read specific memory
ReadResource("memory://abc123")

// Read project memories
ReadResource("memory://project/github.com%2Fuser%2Frepo")

// Read category
ReadResource("memory://category/decision")

Testing

Build

npm run build

MCP Inspector

npm test
# Opens MCP Inspector to manually test tools and resources

Local Testing

node dist/mcp-server.js
# Server starts on stdio, logs to stderr

Migration from v0.1.0

For Users

Before (v0.1.0):

  • CLI commands: odsp-memory remember project "..."
  • MCP tools: 8 basic operations
  • Bash command prompts needed

After (v0.2.0):

  • No CLI (removed)
  • 15 MCP tools with full features
  • Resources for browsing
  • More natural integration

MCP Config - No Change:

{
  "mcpServers": {
    "claude-onedrive-memory": {
      "command": "npx",
      "args": ["@patrick-rodgers/claude-onedrive-memory"]
    }
  }
}

Data Storage - No Change:

  • Same OneDrive location
  • Same file format
  • Existing memories work as-is

Breaking Changes

  1. CLI removed - No more odsp-memory command
  2. Package name - Main export is now dist/mcp-server.js
  3. Bin name - claude-onedrive-memory instead of odsp-memory

Non-Breaking

  • Storage format - Unchanged
  • OneDrive location - Unchanged
  • Memory data - Fully compatible
  • Core tools - Same API (remember, recall, etc.)

Benefits of MCP-Only

  1. Simplified Architecture - One code path, easier to maintain
  2. Better UX - No switching between CLI and MCP
  3. More Features - All advanced features now in MCP
  4. Resources - Browse memories like files
  5. Proactive Use - Claude can remember/recall automatically
  6. Cleaner Conversations - No bash command clutter

Future Enhancements

Potential v0.3.0 Features

  • Prompt caching - Cache frequently accessed memories
  • Webhook notifications - OneDrive change detection
  • Multi-user sync - Shared team memories
  • Encryption - Optional memory encryption
  • Search improvements - Semantic search with embeddings
  • Memory templates - Pre-defined memory structures
  • Auto-categorization - AI-suggested categories

Version History

  • v0.0.1-0.0.3 - CLI-only tool
  • v0.1.0 - Hybrid CLI + MCP (8 tools)
  • v0.2.0 - Pure MCP server (15 tools + resources) ← Current

Files Changed (v0.1.0 → v0.2.0)

Removed

  • src/cli.ts - CLI entry point (no longer needed)

Modified

  • src/mcp-server.ts - Complete rewrite with resources + 15 tools
  • package.json - Updated for MCP-only (bin, description, version)
  • README.md - Comprehensive MCP-focused documentation
  • skill.md - Updated for MCP tools instead of CLI commands

Added

  • MCP Resources support (ListResources, ReadResource handlers)
  • 7 new tools (link_memories, get_related, merge_memories, batch_tag, batch_delete, get_statistics, visualize_graph, export_memories)

Unchanged

  • All core modules (memory.ts, storage.ts, search.ts, etc.)
  • Storage format and location
  • OneDrive detection logic
  • Git project detection
  • Type definitions

Success Criteria

  • ✅ Compiles without errors
  • ✅ All 15 tools available
  • ✅ Resources work correctly
  • ✅ OneDrive detection works
  • ✅ Project scoping works
  • ✅ Existing memories readable
  • ⏳ Manual testing with MCP Inspector
  • ⏳ Testing with Claude Desktop/Code

Documentation

  • ✅ README.md - Comprehensive user guide
  • ✅ skill.md - Claude instruction manual
  • ✅ MCP_IMPLEMENTATION.md - This file
  • ✅ Inline code documentation